Cuando un sitio, una API o un servidor deja de responder, descubrirlo por el usuario llega demasiado tarde. O Uptime Kuma es una herramienta de monitorización self-hosted con interfaz web: ejecuta comprobaciones a intervalos regulares, registra el histórico y envía alertas cuando un servicio cambia de estado. En esta guía, lo instalaremos con Docker Compose, lo publicaremos con Nginx y configuraremos los primeros monitores con seguridad.
Por qué usar Uptime Kuma
Kuma tiene sentido cuando necesitas saber rápidamente si algo que consume el usuario sigue accesible: un sitio web, una API, un puerto TCP, una resolución DNS o la finalización de un trabajo. Reúne la comprobación, el historial, el cambio de estado, la notificación y una página de estado en una interfaz sencilla. Como es self-hosted, las URL, las credenciales de notificación y el historial permanecen en tu infraestructura, en lugar de en una cuenta de monitorización de terceros.
Esto no lo convierte en un sustituto universal. El tiempo de actividad no es observabilidad completa: un endpoint puede responder y aun así estar lento, sin espacio en disco o con una cola acumulada. La mejor elección es usarlo como la capa de disponibilidad y alerta rápida, junto con métricas y registros cuando la operación necesite un diagnóstico profundo.
En qué lenguaje está desarrollado
Uptime Kuma es una aplicación para Node.js, predominantemente en JavaScript. La interfaz web utiliza Vue 3 e Vite; el repositorio también incluye TypeScript en la cadena de desarrollo. Por eso la ejecución sin Docker exige Node.js 20.4 o superior, pero la ruta con contenedor evita instalar Node y dependencias del proyecto directamente en el host.
Qué monitoriza Uptime Kuma
El proyecto es una alternativa ligera para acompanhar la disponibilidad de servicios sin externalizar el panel. Admite monitores HTTP(S), TCP, búsqueda de palabras clave y consulta JSON en HTTP(S), WebSocket, ping, DNS, push, servidores Steam y contenedores Docker. También ofrece páginas públicas de estado, gráfica de latencia, información de certificado, soporte para proxy, autenticación de dos factores e integraciones de notificación.
No sustituye a métricas detalladas: para CPU, memoria, disco y series temporales de servidores, combínalo con Prometheus y Node Exporter. Kuma responde a otra pregunta: “¿este endpoint está accesible ahora y alguien fue avisado?”.
Instala Docker, Compose y Nginx en Ubuntu
Los comandos siguientes son para Ubuntu 22.04 LTS, 24.04 LTS o posterior soportado por Docker. Utilizan el repositorio oficial de Docker, que ofrece el Engine y el plugin moderno docker compose. En una máquina que ya ejecuta contenedores, no elimines ni sustituyas paquetes sin revisar el impacto: la documentación de Docker lista docker.io, docker-compose, containerd e runc entre los paquetes que pueden entrar en conflicto con la instalación oficial.
En un host nuevo, instala los requisitos previos, Nginx y la clave del repositorio:
sudo apt update
sudo apt install -y ca-certificates curl nginx
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg
-o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.ascAñade la fuente APT. El comando lee automáticamente el nombre clave y la arquitectura de la instalación actual:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt updateInstale Docker Engine, Compose y habilite los servicios:
sudo apt install -y docker-ce docker-ce-cli containerd.io
docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker nginx
sudo docker run hello-world
docker compose versionEl primer comando de prueba descarga una imagen pequeña y se cierra; confirma que el daemon funciona. Manténgase sudo en los comandos de Docker o configure el acceso posterior a la instalación de forma consciente: pertenecer al grupo docker equivale, en la práctica, a tener poder administrativo sobre el host. Antes de exponer puertos de contenedores, revise también el cortafuegos: las reglas publicadas por Docker pueden sortear las reglas de UFW.
Antes de empezar
Necesita un host Linux con Docker Engine y el plugin Docker Compose. El ejemplo usa un directorio propio en /opt, un volumen local para los datos y el puerto del servicio limitado a 127.0.0.1. Así, la interfaz no queda abierta directamente en internet; Nginx será la única puerta de entrada.
La base de datos de Uptime Kuma se encuentra en el directorio de datos. No coloque ese directorio en NFS: el proyecto no lo admite, porque los bloqueos de archivo necesarios para SQLite no son adecuados en ese escenario. Incluya /opt/uptime-kuma/data en la copia de seguridad del servidor.
Levanta Uptime Kuma con Docker Compose
Cree el directorio y el archivo compose.yaml:
sudo install -d -m 0755 /opt/uptime-kuma
sudoedit /opt/uptime-kuma/compose.yamlUse esta configuración. La etiqueta :2 sigue la versión más reciente de la línea 2 y es la recomendada por el proyecto. Para fijar una versión concreta, use una etiqueta 2.x.x. No use :latest como atajo para la versión 2: ese nombre está obsoleto y aún apunta a la rama 1.
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "127.0.0.1:3001:3001"Inicie y confirme el estado:
cd /opt/uptime-kuma
sudo docker compose up -d
sudo docker compose ps
curl -I http://127.0.0.1:3001En la primera apertura, cree la cuenta administrativa. Guarde esa contraseña en un gestor de contraseñas y active 2FA en los ajustes. Para seguir el inicio, use sudo docker compose logs -f.
Publica con Nginx y HTTPS
Elija un subdominio, por ejemplo status-admin.exemplo.com, y apunte el DNS al servidor. Uptime Kuma debe quedar en la raíz de ese subdominio; no admite la instalación en un subdirectorio como exemplo.com/kuma/.
Primero, emita un certificado TLS para el subdominio mediante el método empleado en su servidor. No abra la interfaz ni cree la cuenta administrativa antes de que HTTPS esté activo: el inicio de sesión por HTTP expone la credencial. Después, cree el server block final. Ajuste las rutas del certificado a su entorno; la compatibilidad con WebSocket es importante para que la interfaz se actualice en tiempo real:
server {
listen 80;
server_name status-admin.exemplo.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name status-admin.exemplo.com;
ssl_certificate /etc/letsencrypt/live/status-admin.exemplo.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/status-admin.exemplo.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Pruebe antes de recargar:
sudo nginx -t
sudo systemctl reload nginxValide https://status-admin.exemplo.com y solo entonces haga el primer inicio de sesión. Al activar la opción Trust Proxy en Kuma, hágalo solamente si toda solicitud llega a través de un proxy inverso que usted controla; de lo contrario, los encabezados reenviados pueden falsificar la IP de origen. Para una revisión de Nginx en Debian o Ubuntu, consulte nuestra guía sobre Nginx y versiones de PHP.
Crea monitores que realmente avisen algo útil
En el panel, haga clic en Add New Monitor. Comience con pocas comprobaciones que representen un recorrido real:
- HTTP(S): la URL pública del sitio o de la API. Defina los códigos HTTP aceptados según la aplicación.
- Keyword: una página de salud que deba contener un marcador conocido, como
ok. - TCP: el puerto de un servicio que debe aceptar conexiones, como SMTP o una aplicación interna.
- DNS: un registro crítico, útil para detectar errores de resolución o cambios inesperados.
- Push: trabajos de copia de seguridad, sincronización o mantenimiento: el job llama a la URL exclusiva proporcionada por Kuma al finalizar. Si la señal no llega dentro de la ventana configurada, el monitor entrará en estado de alerta.
Evita intervalos agresivos por defecto. Un monitor con muchos falsos positivos se ignora rápidamente. Define el timeout, los reintentos y el intervalo según la criticidad y la capacidad del servicio monitorizado.
Configura notificaciones antes del fallo
Abre Settings → Notifications, registra el canal elegido y utiliza el botón de prueba. Uptime Kuma dispone de integraciones para SMTP, Telegram, Discord, Slack, Gotify, Pushover y muchos otros servicios. Después, asocia la notificación a cada monitor: crear el canal por sí solo no envía alertas.
Empieza con una ruta que alguien realmente supervise. Para servicios críticos, utiliza más de un destino y documenta quién responde a cada tipo de alerta.
Página pública de estado, sin exponer la administración
En Status Pages, crea una página con los monitores que pueden mostrarse al público. Está separada del panel administrativo: publique solo lo que sea apropiado revelar. Una página de estado es útil para reducir llamadas durante una indisponibilidad, pero no debe listar servicios internos, direcciones privadas o detalles de infraestructura.
Actualización y copia de seguridad
Realice una copia de seguridad del directorio de datos antes de actualizar. En una ventana de mantenimiento, el flujo básico es:
cd /opt/uptime-kuma
sudo docker compose pull
sudo docker compose up -d --force-recreate
sudo docker compose logs --tail=100Consulte las notas de la versión oficiales antes de actualizar, sobre todo en cambios de versión principal. El proyecto mantiene también una guía específica para la migración de v1 a v2.
Medidas de seguridad
- No publique el puerto
3001directamente; manténgalo detrás de127.0.0.1HTTPS y autenticación. - Use contraseña exclusiva, 2FA y actualizaciones periódicas.
- Proteja la copia de seguridad de
data: puede contener URL, tokens de notificación e información sobre su infraestructura. - El monitor de contenedores puede requerir acceso al socket Docker. Este socket controla el daemon; no lo monte sin comprender el impacto y nunca trate esa instancia como un panel público.
Alternativas: cuál usar en cada escenario
- Gatus: monitorización self-hosted escrito en Go y definido en un archivo de configuración. Es una buena opción para equipos que prefieren revisar los checks en Git y aplicar la configuración como código.
- Prometheus con Blackbox Exporter: recopila métricas de probes HTTP, TCP, ICMP y DNS e integra alertas en el ecosistema Prometheus. Elígelo cuando los datos deben convertirse en series temporales, cuadros de mando y reglas más sofisticadas.
- Zabbix: plataforma más amplia para hosts, red, descubrimiento y plantillas. Sirve para inventarios más grandes; para pocos endpoints, suele requerir más operación que Kuma.
- Cachet: está enfocado en la comunicación de incidentes y en una página pública de estado. Puede complementar a un monitor, pero no debe elegirse por sí solo esperando el mismo conjunto de probes que Kuma.
En resumen: elige Kuma por su interfaz rápida y su conjunto de checks listos; Gatus para configuración versionada; Prometheus/Blackbox para métricas y alertas como código; y Zabbix cuando la necesidad es monitorizar toda la infraestructura.
Dónde encaja Kuma en tu operación
Uptime Kuma es excelente como capa sencilla de disponibilidad y alerta: un panel para sus endpoints, jobs y páginas de estado. Para una monitorización profunda de hosts, completa la estrategia con Prometheus; para conocer alternativas tradicionales, consulta las historias de Nagios y de Zabbix. La instalación oficial, la configuración avanzada de proxy y el código fuente están en el repositorio de Uptime Kuma.