Cómo instalar Uptime Kuma con Docker en Ubuntu 24.04

Uptime Kuma es una herramienta de monitorización de disponibilidad autoalojada: comprueba periódicamente webs, puertos, DNS o hosts por ping, te avisa cuando algo cae y publica una página de estado para tus usuarios. En este tutorial la desplegarás con Docker Compose en Ubuntu 24.04, la publicarás detrás de Nginx con un certificado de Let's Encrypt y configurarás tus primeros monitores, una notificación y una página de estado.

Requisitos previos

Para seguir esta guía necesitas:

Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 1 GB de RAM.
Un usuario no root con privilegios sudo.
Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker (consulta la guía "Cómo instalar Docker en Ubuntu 24.04, Debian 12 y Rocky 9").
Un dominio o subdominio, en esta guía status.your_domain, con un registro DNS A apuntando a la IP pública del servidor (your_server_ip).
Los puertos 80 y 443 accesibles desde Internet.

Uptime Kuma debería ejecutarse en un servidor distinto de los que vigila: si monitoriza su propia máquina, no podrá avisarte cuando esa máquina caiga.

Paso 1: Crear el proyecto de Docker Compose

Crea un directorio para Uptime Kuma. Los datos (base de datos, certificados subidos, configuración) se guardarán en el subdirectorio data, lo que facilita las copias de seguridad:

mkdir -p ~/uptime-kuma
cd ~/uptime-kuma

Crea el archivo compose.yaml:

nano compose.yaml

Añade el siguiente contenido:

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

Algunos detalles de este archivo:

La etiqueta 2 sigue la rama estable 2.x y recibe correcciones sin saltar a una versión mayor por sorpresa.
El puerto se publica solo en 127.0.0.1. Docker añade sus propias reglas de iptables y los puertos publicados en todas las interfaces se saltan UFW, así que es más seguro que solo Nginx pueda llegar al contenedor.
restart: unless-stopped hace que el contenedor arranque de nuevo tras un reinicio del servidor.

Paso 2: Arrancar Uptime Kuma

Descarga la imagen y arranca el contenedor en segundo plano:

docker compose up -d

Comprueba que el contenedor está en marcha:

docker compose ps

NAME          IMAGE                    COMMAND                  SERVICE       CREATED          STATUS                    PORTS
uptime-kuma   louislam/uptime-kuma:2   "/usr/bin/dumb-init …"   uptime-kuma   30 seconds ago   Up 29 seconds (healthy)   127.0.0.1:3001->3001/tcp

Verifica también que responde en el puerto local:

curl -sI http://127.0.0.1:3001

HTTP/1.1 302 Found
...

Si algo falla, revisa los logs con docker compose logs -f uptime-kuma.

Paso 3: Configurar Nginx como proxy inverso

Instala Nginx y Certbot con su plugin para Nginx:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

Permite el tráfico HTTP y HTTPS en el firewall. Si UFW no está activo todavía, permite antes SSH para no perder el acceso:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Crea un bloque de servidor para Uptime Kuma:

sudo nano /etc/nginx/sites-available/uptime-kuma

Uptime Kuma usa WebSockets para actualizar la interfaz en tiempo real, por lo que las cabeceras Upgrade y Connection son imprescindibles:

server {
    listen 80;
    listen [::]:80;
    server_name status.your_domain;

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

Activa el sitio, comprueba la sintaxis y recarga Nginx:

sudo ln -s /etc/nginx/sites-available/uptime-kuma /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Paso 4: Obtener un certificado TLS con Let's Encrypt

Pide el certificado con Certbot. El plugin de Nginx añade la configuración HTTPS y la redirección de HTTP a HTTPS en el mismo archivo:

sudo certbot --nginx -d status.your_domain

Certbot te pedirá un correo para avisos de caducidad y que aceptes las condiciones. Al terminar verás:

Successfully deployed certificate for status.your_domain to /etc/nginx/sites-enabled/uptime-kuma
Congratulations! You have successfully enabled HTTPS on https://status.your_domain

El paquete de Certbot instala un temporizador de systemd que renueva el certificado automáticamente. Puedes simular una renovación para comprobarlo:

sudo certbot renew --dry-run

Paso 5: Completar la configuración inicial

Abre https://status.your_domain en el navegador. El asistente de la primera ejecución te pide:

El tipo de base de datos. Para una instalación pequeña o mediana, elige SQLite, que no necesita ningún servicio adicional.
El usuario administrador y una contraseña robusta.

Después, entra en Settings > Reverse Proxy y marca Trust Proxy como Yes. Así Uptime Kuma usa la IP real del visitante que le envía Nginx en X-Forwarded-For en lugar de 127.0.0.1.

Consejo

activa la autenticación en dos pasos desde Settings > Security. El panel da acceso a toda tu configuración de alertas y a las URL internas que monitorizas.

Paso 6: Crear monitores

Pulsa Add New Monitor en el panel. Estos son los tipos más útiles para empezar:

Tipo	Qué comprueba	Ejemplo
HTTP(s)	Que la URL responde con un código aceptado (2xx por defecto)	`https://your_domain`
HTTP(s) - Keyword	Que además la respuesta contiene un texto	`/health` que devuelve `ok`
TCP Port	Que un puerto acepta conexiones	`db.your_domain`, puerto `5432`
Ping	Que el host responde a ICMP	`your_server_ip`
DNS	Que un nombre resuelve con el servidor y tipo de registro indicados	`your_domain`, registro `A`

Para un monitor HTTP(s) típico:

Monitor Type: HTTP(s).
Friendly Name: un nombre descriptivo, por ejemplo Web principal.
URL: https://your_domain.
Heartbeat Interval: 60 segundos es un buen valor por defecto.
Retries: pon 1 o 2 para que un fallo puntual de red no dispare una alerta.
Marca Certificate Expiry Notification para recibir un aviso antes de que caduque el certificado TLS de la web.

Guarda el monitor. En unos segundos aparecerá en la lista de la izquierda con su primer latido en verde y el tiempo de respuesta en la gráfica.

Para comprobar desde el propio servidor que el objetivo es alcanzable (útil si un monitor aparece en rojo y no sabes por qué), usa las herramientas habituales:

curl -sI https://your_domain
nc -zv db.your_domain 5432
dig +short your_domain A

Paso 7: Configurar notificaciones

Uptime Kuma admite decenas de canales (correo SMTP, Telegram, Discord, Slack, Microsoft Teams, webhooks, etc.). Se configuran una vez y luego se asignan a los monitores.

Por ejemplo, para Telegram:

Crea un bot con @BotFather en Telegram y copia el token.
En Uptime Kuma, ve a Settings > Notifications > Setup Notification.
Elige Telegram, pega el Bot Token y pulsa Auto Get para obtener el Chat ID después de enviar un mensaje a tu bot.
Marca Default enabled para que se aplique a los monitores nuevos y, si quieres, Apply on all existing monitors.
Pulsa Test y comprueba que llega el mensaje de prueba. Luego pulsa Save.

Para verificar el flujo completo, crea un monitor TCP Port contra un puerto cerrado (por ejemplo your_server_ip, puerto 9), espera a que pase a Down y comprueba que recibes el aviso. Borra el monitor después.

Paso 8: Publicar una página de estado

Una página de estado muestra a tus usuarios la disponibilidad de tus servicios sin darles acceso al panel.

Pulsa Status Pages en el menú superior y después New Status Page.
Indica un nombre (por ejemplo Estado de los servicios) y un slug (por ejemplo servicios).
En el editor, añade un grupo, elige qué monitores se muestran en él y personaliza la descripción, el logotipo y el pie de página.
Pulsa Save.

La página queda publicada en:

https://status.your_domain/status/servicios

Ábrela en una ventana privada del navegador para confirmar que se ve sin iniciar sesión.

Cuando programes una intervención, crea una ventana desde Maintenance en el menú superior y asóciala a los monitores afectados: durante ese periodo no se enviarán alertas y la página de estado mostrará el aviso de mantenimiento.

Paso 9: Copias de seguridad y actualizaciones

Todo el estado de Uptime Kuma vive en ~/uptime-kuma/data. Para una copia consistente de la base de datos SQLite, detén el contenedor unos segundos mientras la empaquetas:

cd ~/uptime-kuma
docker compose stop
sudo tar -czf ~/uptime-kuma-backup-$(date +%F).tar.gz -C ~/uptime-kuma data
docker compose start

Comprueba que el archivo se ha creado y cópialo fuera del servidor (por ejemplo con scp o rsync):

ls -lh ~/uptime-kuma-backup-*.tar.gz

Para actualizar a la última versión de la rama 2.x, descarga la imagen nueva y recrea el contenedor:

cd ~/uptime-kuma
docker compose pull
docker compose up -d

Importante

haz siempre una copia de data antes de actualizar. Si vienes de Uptime Kuma 1.x, el primer arranque con la versión 2 migra la base de datos y puede tardar bastante con historiales grandes; no interrumpas el contenedor durante la migración.

Solución de problemas

La interfaz carga pero se queda en "Cannot connect to the socket server": faltan las cabeceras de WebSocket en Nginx. Revisa que proxy_http_version 1.1, Upgrade y Connection están en el bloque location y recarga Nginx.

502 Bad Gateway en Nginx: el contenedor no está en marcha o no escucha en 127.0.0.1:3001. Comprueba docker compose ps y docker compose logs uptime-kuma.

Los monitores Ping fallan aunque el host responde desde tu equipo: muchos proveedores y firewalls bloquean ICMP. Usa un monitor TCP Port o HTTP(s) contra ese host.

Certbot falla con Timeout during connect: el registro DNS no apunta aún a your_server_ip o el puerto 80 está cerrado. Comprueba dig +short status.your_domain y sudo ufw status.

Conclusión

Tienes Uptime Kuma funcionando con Docker Compose en Ubuntu 24.04, publicado con HTTPS detrás de Nginx, con monitores, notificaciones y una página de estado pública. Al estar todo en un único directorio, hacer copias y actualizar es cuestión de un par de comandos.

Como siguientes pasos puedes:

Automatizar la copia del directorio data con un temporizador de systemd o una tarea de cron que la envíe a otro servidor.
Usar monitores de tipo Push para vigilar tareas programadas: la tarea llama a una URL al terminar y Uptime Kuma avisa si deja de hacerlo.
Complementar la disponibilidad con métricas de rendimiento del servidor mediante Netdata o Prometheus y Grafana.

On this page