Uptime Kuma es una herramienta de monitorización autoalojada y de código abierto que comprueba de forma periódica si tus sitios web, APIs, puertos o servidores responden, y te avisa por correo, Telegram, Discord u otros canales cuando algo cae. En esta guía instalarás Uptime Kuma con Docker Compose en Ubuntu 24.04, lo publicarás detrás de Nginx con un certificado HTTPS de Let's Encrypt y crearás tu primer monitor con notificaciones.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath. Con 1 GB de RAM es suficiente para decenas de monitores.
  • Un usuario no root con privilegios sudo.
  • Un dominio o subdominio (en esta guía your_domain, por ejemplo status.example.com) con un registro DNS A que apunte a la IP pública del servidor.
  • UFW activo con SSH permitido.

Es buena idea instalar Uptime Kuma en un servidor distinto de los que vas a vigilar: si ese servidor cae, el monitor seguirá funcionando y podrá avisarte.

Paso 1: Instalar Docker Engine

Instala Docker desde el repositorio oficial de Docker, que incluye el plugin docker compose. Primero añade la clave del repositorio:

sudo apt update
sudo apt install ca-certificates curl
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.asc

Añade el repositorio:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Instala los paquetes:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Comprueba que el servicio está activo y que Compose funciona:

sudo systemctl is-active docker
docker compose version

active
Docker Compose version v2.39.4

Paso 2: Crear el archivo de Docker Compose

Crea un directorio para Uptime Kuma. Sus datos (monitores, historial y usuarios) se guardarán en un subdirectorio data dentro de él:

sudo mkdir -p /opt/uptime-kuma
cd /opt/uptime-kuma

Crea el archivo de Compose:

sudo nano /opt/uptime-kuma/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

Dos detalles importantes:

  • El puerto se publica solo en 127.0.0.1, de modo que Uptime Kuma no es accesible directamente desde Internet. Nginx hará de proxy inverso con HTTPS. Esto importa porque Docker añade sus propias reglas de iptables y un puerto publicado en todas las interfaces quedaría abierto aunque UFW no lo permita.
  • La etiqueta 2 sigue la versión mayor 2 de Uptime Kuma y recibe sus actualizaciones menores.

Paso 3: Iniciar Uptime Kuma

Arranca el contenedor en segundo plano:

sudo docker compose up -d

Comprueba que está en marcha. El estado pasará a healthy al cabo de unos segundos:

sudo 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 que responde en local:

curl -sI http://127.0.0.1:3001 | head -n 1

HTTP/1.1 302 Found

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

Paso 4: Configurar Nginx como proxy inverso

Instala Nginx y Certbot con su plugin para Nginx:

sudo apt install nginx certbot python3-certbot-nginx

Crea el bloque de servidor para tu dominio:

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

Añade esta configuración, sustituyendo your_domain por tu dominio. Las cabeceras Upgrade y Connection son necesarias porque la interfaz de Uptime Kuma funciona sobre WebSockets:

server {
    listen 80;
    listen [::]:80;
    server_name 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

Abre los puertos HTTP y HTTPS en el firewall:

sudo ufw allow "Nginx Full"

Paso 5: Obtener un certificado HTTPS

Certbot obtiene un certificado de Let's Encrypt, añade la configuración TLS al bloque de servidor y configura la redirección de HTTP a HTTPS:

sudo certbot --nginx -d your_domain

Introduce un correo para los avisos de caducidad y acepta los términos. Al terminar verás:

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

El paquete de Certbot instala un temporizador de systemd que renueva el certificado de forma automática. Comprueba que la renovación funciona:

sudo certbot renew --dry-run

Paso 6: Crear la cuenta de administrador

Abre https://your_domain en el navegador. La primera vez, Uptime Kuma 2 te pregunta qué base de datos usar: elige SQLite, que es suficiente para una instalación de este tamaño y guarda todo en /opt/uptime-kuma/data.

Después crea el usuario administrador con una contraseña fuerte. Este formulario solo aparece una vez y cualquiera que llegue antes que tú podría usarlo, así que completa este paso nada más publicar el dominio.

Paso 7: Añadir un monitor y una notificación

Configura primero el canal de alertas para poder asignarlo a los monitores:

  1. Ve a Settings > Notifications y pulsa Setup Notification.
  2. Elige el tipo, por ejemplo Telegram, Discord o Email (SMTP), y rellena los datos que pide.
  3. Pulsa Test para confirmar que recibes el mensaje de prueba y guarda.

Ahora crea el monitor:

  1. Pulsa Add New Monitor.
  2. En Monitor Type elige HTTP(s).
  3. En Friendly Name escribe un nombre descriptivo y en URL la dirección completa del sitio, por ejemplo https://www.example.com.
  4. Heartbeat Interval: 60 segundos es un buen punto de partida.
  5. En la sección de notificaciones, activa el canal que creaste.
  6. Guarda.

En pocos segundos el monitor aparecerá en verde con su tiempo de respuesta. Uptime Kuma también avisa por defecto cuando un certificado TLS está a punto de caducar. Otros tipos útiles son TCP Port (para un servicio como una base de datos o un servidor de juegos), Ping y Keyword, que comprueba que la página contiene un texto concreto y detecta errores que siguen devolviendo HTTP 200.

Para probar la alerta, crea un monitor temporal hacia una URL que no exista y comprueba que recibes el aviso de caída. Después bórralo.

Paso 8: Actualizar y hacer copias de seguridad

Para actualizar Uptime Kuma a la última versión 2.x, descarga la imagen nueva y recrea el contenedor. Los datos se conservan porque están en el volumen:

cd /opt/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

Para una copia de seguridad consistente, detén el contenedor, archiva el directorio de datos y vuelve a arrancarlo:

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

Guarda ese archivo fuera del servidor.

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 y las líneas Upgrade y Connection están en el bloque location y recarga Nginx.

Certbot falla con un error de validación. El registro A de your_domain no apunta todavía al servidor o el puerto 80 está cerrado. Comprueba la resolución con dig +short your_domain y las reglas con sudo ufw status.

El contenedor se reinicia en bucle. Revisa sudo docker compose logs. Si el directorio data tiene permisos incorrectos o el disco está lleno, el arranque falla; comprueba el espacio con df -h.

Conclusión

Tienes Uptime Kuma funcionando en Docker, publicado con HTTPS detrás de Nginx y enviando alertas cuando uno de tus sitios deja de responder. Como siguientes pasos, crea una página de estado pública desde Status Pages para informar a tus usuarios, añade monitores de tipo TCP Port para tus bases de datos y automatiza la copia de seguridad del directorio data.