---
title: "Cómo instalar Uptime Kuma con Docker en Ubuntu 24.04"
description: "Instala Uptime Kuma con Docker Compose en Ubuntu 24.04, publícalo con Nginx y HTTPS, crea monitores y alertas y monta una página de estado para tus servicios."
category: "Stack de Observabilidad"
language: es
source: https://cubepath.com/es/docs/stack-de-observabilidad/instalacion-de-uptime-kuma-para-monitoreo-de-estado
updated: 2026-09-25
---

# 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:

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

Crea el archivo `compose.yaml`:

```bash
nano compose.yaml
```

Añade el siguiente contenido:

```yaml
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:

```bash
docker compose up -d
```

Comprueba que el contenedor está en marcha:

```bash
docker compose ps
```

```output
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:

```bash
curl -sI http://127.0.0.1:3001
```

```output
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:

```bash
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:

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

Crea un bloque de servidor para Uptime Kuma:

```bash
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:

```nginx
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:

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

```output
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:

```bash
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:

```output
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:

```bash
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:

1. El tipo de base de datos. Para una instalación pequeña o mediana, elige **SQLite**, que no necesita ningún servicio adicional.
2. 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:

1. **Monitor Type**: `HTTP(s)`.
2. **Friendly Name**: un nombre descriptivo, por ejemplo `Web principal`.
3. **URL**: `https://your_domain`.
4. **Heartbeat Interval**: 60 segundos es un buen valor por defecto.
5. **Retries**: pon `1` o `2` para que un fallo puntual de red no dispare una alerta.
6. 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:

```bash
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:

1. Crea un bot con `@BotFather` en Telegram y copia el token.
2. En Uptime Kuma, ve a **Settings > Notifications > Setup Notification**.
3. Elige **Telegram**, pega el **Bot Token** y pulsa **Auto Get** para obtener el **Chat ID** después de enviar un mensaje a tu bot.
4. Marca **Default enabled** para que se aplique a los monitores nuevos y, si quieres, **Apply on all existing monitors**.
5. 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.

1. Pulsa **Status Pages** en el menú superior y después **New Status Page**.
2. Indica un nombre (por ejemplo `Estado de los servicios`) y un slug (por ejemplo `servicios`).
3. 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.
4. Pulsa **Save**.

La página queda publicada en:

```text
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:

```bash
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`):

```bash
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:

```bash
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.