Cómo instalar Uptime Kuma en un VPS

Qué vigila realmente Uptime Kuma

Uptime Kuma comprueba disponibilidad desde fuera: si un servicio responde, cuánto tarda y cuándo caduca su certificado. No mide el consumo de CPU ni el estado interno del sistema operativo; para eso existen otras herramientas.

Los tipos de monitor más usados:

• HTTP(s): código de estado y tiempo de respuesta de una URL.
• HTTP con palabra clave: además del código 200, exige que la respuesta contenga un texto. Detecta la página que "carga" pero muestra un error de base de datos.
• TCP Port: comprueba que un puerto acepta conexiones (por ejemplo, 5432 de PostgreSQL o 25 de un servidor de correo).
• Ping: latencia ICMP hacia un host.
• DNS: que un registro resuelve al valor esperado.
• Push: el servicio monitorizado llama a Uptime Kuma; si deja de llamar, salta la alerta. Es la forma correcta de vigilar cron jobs y scripts de backup.
• Certificado TLS: aviso con días de antelación antes de que caduque.

Ese último punto evita uno de los incidentes más comunes y más evitables: un certificado que caduca un sábado porque la renovación automática llevaba dos meses fallando en silencio.

Requisitos y dónde instalarlo

Uptime Kuma es ligero: una aplicación Node.js con base SQLite que cabe en el VPS más pequeño. Lo importante no es el tamaño del servidor, sino dónde lo pones.

Regla central: el monitor no puede vivir en el servidor que vigila. Si instalas Uptime Kuma en el mismo VPS que tu web y ese VPS se apaga, no habrá alerta porque el que debía enviarla también está apagado. Usa un segundo servidor, preferiblemente en otra región o proveedor.

El disco lo consume el historial de latidos, no la aplicación. Cada monitor guarda un registro por comprobación; cien monitores cada 60 segundos generan unos 144.000 registros diarios. Ajusta la retención en los ajustes generales si el disco crece más de lo esperado.

Instalar Uptime Kuma con Docker

Con Docker ya instalado, la instalación es un único comando. La serie 2 es la estable actual del proyecto:

docker volume create uptime-kuma
docker run -d --name uptime-kuma \
  --restart=unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v uptime-kuma:/app/data \
  louislam/uptime-kuma:2

Fíjate en el detalle de 127.0.0.1:3001:3001: enlaza el puerto solo a la interfaz local, de modo que Uptime Kuma no queda expuesto a internet mientras configuras el proxy inverso. Si prefieres probar primero por IP, cambia esa parte por -p 3001:3001, pero corrígelo antes de dejarlo en producción.

Si aún no tienes Docker, la guía de Docker en VPS cubre la instalación desde el repositorio oficial. En un servidor donde ya administras varios servicios, es más ordenado usar Compose:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - uptime-kuma:/app/data

volumes:
  uptime-kuma:

docker compose up -d
docker logs --tail=50 uptime-kuma

En el primer arranque, Uptime Kuma pide crear la cuenta administradora. Créala de inmediato: hasta que exista, cualquiera que llegue al puerto puede reclamar la instancia.

Poner Nginx delante con HTTPS y WebSockets

Uptime Kuma usa WebSockets para actualizar el panel en tiempo real, así que el proxy inverso necesita las cabeceras de upgrade o el panel se quedará colgado en "Conectando".

server {
    listen 80;
    server_name estado.tuempresa.com;

    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;
        proxy_read_timeout 86400;
    }
}

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d estado.tuempresa.com

El proxy_read_timeout alto evita que Nginx corte la conexión WebSocket cada minuto. Si el panel se recarga solo o muestra desconexiones constantes, ese valor y las cabeceras Upgrade son lo primero que hay que revisar; la guía del error 502 en Nginx ayuda a separar las causas.

Configurar alertas por Telegram

Sin notificación configurada, Uptime Kuma es solo un panel bonito que nadie mira a las 3 de la mañana. Telegram es la vía más rápida de montar y es gratuita.

1. 1 Abre Telegram y escribe a @BotFather. Envía /newbot, elige nombre y usuario del bot y copia el token que devuelve.
2. 2 Envía cualquier mensaje a tu nuevo bot (o añádelo a un grupo y escribe algo). Sin ese paso, el bot no puede iniciar conversación contigo.
3. 3 Consulta tu chat ID:

curl -s "https://api.telegram.org/bot<TU_TOKEN>/getUpdates" | head -c 800

Busca en la respuesta el campo "chat":{"id":...}. En un grupo, ese identificador empieza por un guion.

1. 1 En Uptime Kuma, ve a Perfil → Notificaciones → Configurar notificación, elige tipo Telegram, pega el token y el chat ID, y pulsa Probar. Si el mensaje no llega, no guardes: el problema es el chat ID o el paso 2.
2. 2 Marca la notificación como predeterminada para que se aplique a los monitores nuevos.

Configura también un segundo canal por correo (SMTP) para el caso de que Telegram falle. Y prueba las alertas de verdad: detén un servicio a propósito y comprueba que el mensaje llega al teléfono correcto.

Crear los monitores que importan

Un monitor útil comprueba lo que el usuario percibe, no lo que es cómodo medir. Estos son los ajustes que marcan la diferencia:

• Intervalo: 60 segundos es un buen equilibrio. Bajar a 20 segundos multiplica el historial y no suele aportar nada.
• Reintentos: configura 2 o 3 antes de marcar caída. Evita alertas por un microcorte de red.
• Palabra clave: para una web dinámica, exige un texto que solo aparezca si la base responde. Un WordPress con la base caída puede devolver 200 con una página de error.
• Grupos: agrupa por cliente o por proyecto para que la página de estado tenga sentido.
• Monitores Push: para tareas programadas. El script llama a la URL push al terminar con éxito; si el backup no corre, el monitor se pone rojo solo.

# Al final de tu script de backup
curl -fsS -m 10 "https://estado.tuempresa.com/api/push/TOKEN?status=up&msg=OK" > /dev/null

Añade también un monitor TCP a los puertos de tus bases de datos y un monitor DNS a tus dominios principales. Un cambio de DNS no autorizado se detecta antes con eso que revisando el panel del registrador.

Página de estado pública

Uptime Kuma permite publicar una página de estado con los monitores que elijas, en un dominio propio. Es útil para clientes: reduce los correos de "¿está caído?" durante un incidente.

Ve a Páginas de estado → Nueva, elige el slug, añade los grupos de monitores y decide si publicas el porcentaje de disponibilidad y los tiempos de respuesta. Publica solo lo que quieras que se vea: los nombres de los monitores internos pueden revelar más infraestructura de la que conviene.

Si la página de estado vive en el mismo VPS que Uptime Kuma, recuerda que en una caída total de ese servidor tampoco estará disponible. Para comunicación de incidentes de cara al cliente, algunos equipos publican la página en un servidor independiente.

Uptime Kuma frente a otras herramientas

Uptime Kuma y una herramienta de métricas internas no compiten, se complementan. Kuma te dice que algo se cayó; las métricas del servidor te dicen por qué. Para esa segunda parte, la guía de ver el consumo de CPU y RAM en Linux cubre las herramientas básicas.

Backups y actualizaciones

Todo el estado de Uptime Kuma vive en el volumen montado en /app/data: monitores, historial, notificaciones y usuarios. Copiarlo es copiar la instalación entera.

docker stop uptime-kuma
docker run --rm -v uptime-kuma:/data -v $(pwd):/backup alpine \
  tar czf /backup/uptime-kuma-$(date +%F).tar.gz -C /data .
docker start uptime-kuma

Detener el contenedor durante la copia evita capturar la base SQLite a mitad de una escritura. Envía el archivo resultante fuera del VPS con rsync y cron.

Para actualizar:

docker pull louislam/uptime-kuma:2
docker stop uptime-kuma && docker rm uptime-kuma
# vuelve a ejecutar el mismo docker run, con el mismo volumen

Con Compose es docker compose pull && docker compose up -d. Haz backup antes de cada salto de versión mayor: la migración de la serie 1.x a la 2.x reorganiza la tabla de latidos en el primer arranque y no se deshace.

Problemas frecuentes