Jugando con Docker: Monitoriza tus servicios con Uptime Kuma

Monitoriza tus servicios con Uptime Kuma en Docker

Si tienes un homelab, un VPS, una web, un servidor de domótica o varios contenedores Docker funcionando, hay una pregunta que tarde o temprano aparece:

¿Cómo me entero cuando algo se cae?

Puedes mirar los servicios manualmente. Puedes abrir cada panel de vez en cuando. Puedes confiar en que “si algo falla ya me avisará alguien”.

Pero eso no es monitorización. Eso es esperanza.

Para mí, una de las herramientas más cómodas para empezar a monitorizar servicios es Uptime Kuma: sencilla, visual, autohospedada y perfecta para recibir avisos cuando algo deja de responder.

No sustituye a Prometheus, Grafana, Loki o un sistema completo de observabilidad. No pretende hacerlo. Uptime Kuma responde a una pregunta mucho más directa:

¿Mis servicios están vivos?

Y para un homelab, muchas veces esa es la pregunta más importante.

---

Cómo llegó Uptime Kuma a mi laboratorio

Cuando mi laboratorio empezó a crecer, llegó un momento en el que ya no bastaba con asumir que todo seguía funcionando.

Cada vez tenía más servicios funcionando: Home Assistant, AdGuard Home, Caddy, Docker, distintas máquinas virtuales y otros proyectos que iban apareciendo con el tiempo.

Necesitaba una forma sencilla de saber cuándo algo dejaba de responder, sin tener que entrar continuamente a comprobar si todo seguía en marcha.

No buscaba una plataforma enorme de observabilidad. Tampoco quería depender de un servicio externo para algo tan básico como saber si mis propios sistemas seguían vivos.

Buscando una alternativa autoalojada encontré Uptime Kuma en GitHub. Me gustó desde el principio porque proponía exactamente lo que necesitaba: una instalación muy sencilla, una interfaz clara y notificaciones inmediatas cuando algo dejaba de responder.

Con el tiempo también he ido probando otras herramientas que prometían hacer muchas más cosas. Uptime Kuma nunca ha intentado competir ahí. Su objetivo es mucho más simple: decirte si un servicio está disponible o no.

Y precisamente por eso sigue formando parte de mi laboratorio años después.

Requisitos previos

Este tutorial asume que ya tienes:

• Un servidor Linux, VPS o máquina de tu homelab.
• Docker instalado.
• Docker Compose V2 disponible como docker compose.
• Acceso SSH al servidor.
• Un usuario con permisos para ejecutar Docker.
• Telegram si quieres recibir alertas en el móvil.

Si todavía no tienes claro cómo encaja Docker en una empresa o en un homelab, puedes empezar por mi artículo de introducción a Docker.

---

Paso 1: preparar el entorno

Crea una carpeta para Uptime Kuma:

sudo mkdir -p /opt/uptime-kuma
sudo chown -R $USER:$USER /opt/uptime-kuma
cd /opt/uptime-kuma

Dentro de esta carpeta guardaremos el archivo Compose y los datos persistentes.

La persistencia es importante. Uptime Kuma guarda configuración, monitores, usuarios y estado en su carpeta de datos. Si no montas un volumen, perderás la configuración al recrear el contenedor.

---

Paso 2: crear el docker-compose.yml

Crea el archivo:

nano docker-compose.yml

Y pega esta configuración:

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

Algunos matices:

• No uso version: '3'. En Docker Compose moderno el campo version ya no hace falta y puede generar avisos.
• El puerto por defecto de Uptime Kuma es 3001.
• La carpeta ./data se monta en /app/data, que es donde Uptime Kuma guarda sus datos.
• Usa almacenamiento local o un volumen fiable. Evita montar la base de datos sobre ubicaciones con problemas de bloqueo de archivos, como ciertos NFS.
• “3001:3001” publica Uptime Kuma en todas las interfaces del host por defecto. Antes de dejar el servicio operativo, revisa el Paso 8: puedes limitarlo a una IP LAN concreta, limitarlo al loopback o eliminar ports cuando Caddy está en Docker.

Nota sobre instalaciones existentes: este ejemplo está preparado para una instalación nueva de Uptime Kuma 2. Si ya tienes una instalación antigua basada en :1 o :latest, no cambies el tag sin más: detén el servicio, realiza primero una copia de seguridad de ./data, cambia la imagen a :2, arranca de nuevo y revisa los logs de la migración.

La migración desde Uptime Kuma 1 puede tardar varios minutos o incluso más, según el tamaño de la base de datos y el rendimiento del equipo. No interrumpas el proceso mientras los logs indiquen que la migración continúa. Si se interrumpe o falla, restaura la copia de ./data antes de intentarlo de nuevo.

docker compose down
tar -czf uptime-kuma-pre-v2-$(date +%F).tar.gz data
# Edita docker-compose.yml y cambia:
# louislam/uptime-kuma:1 o louislam/uptime-kuma:latest
# por:
# louislam/uptime-kuma:2
docker compose pull
docker compose up -d
docker compose logs -f uptime-kuma

Si quieres mantenerlo un poco más ordenado, también puedes usar una red dedicada:

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

networks:
  monitoring:
    name: monitoring

Para una instalación sencilla, cualquiera de las dos opciones vale.

---

Paso 3: desplegar el contenedor

Levanta Uptime Kuma:

docker compose up -d

Comprueba que está corriendo:

docker ps

Y si algo falla, revisa los logs:

docker logs uptime-kuma

También puedes ver el estado con:

docker compose ps

---

Paso 4: acceder a Uptime Kuma

Abre en el navegador:

http://IP-DE-TU-SERVIDOR:3001

Si lo estás ejecutando en tu propia máquina:

http://localhost:3001

La primera vez, Uptime Kuma te pedirá crear el usuario administrador.

Usa una contraseña fuerte. Parece obvio, pero Uptime Kuma es una herramienta de monitorización que puede contener información sensible: nombres de servicios, dominios internos, IPs, rutas, tokens de notificación y estructura de tu red.

No es un panel para dejar abierto alegremente a Internet.

---

Paso 5: crear tus primeros monitores

Una vez dentro, toca añadir servicios.

En Uptime Kuma, pulsa Add New Monitor y elige el tipo de comprobación.

Servicio	Tipo recomendado	Ejemplo
Web pública	HTTP(s)	https://tudominio.com
Home Assistant	HTTP(s)	http://192.168.1.50:8123
AdGuard Home	HTTP(s)	http://192.168.1.60:8081
Pi-hole DNS	DNS	192.168.1.61
Servidor Linux	Ping	192.168.1.10
Servicio en puerto concreto	TCP Port	192.168.1.10:22
Certificado SSL	HTTP(s) o certificado	https://tudominio.com

Hoy monitorizo prácticamente todos los servicios que considero importantes, tanto internos como externos. No porque quiera saberlo todo, sino porque quiero enterarme rápido cuando algo deja de funcionar.

Cuando elimino un servicio o lo sustituyo por otro, simplemente actualizo el monitor correspondiente o lo dejo en pausa por si vuelve a formar parte del laboratorio en el futuro.

Al final, Uptime Kuma termina convirtiéndose también en una fotografía bastante fiel de la infraestructura que realmente permanece funcionando con el paso del tiempo.

Mi recomendación inicial:

• Intervalo de 60 segundos para servicios importantes.
• Reintentos antes de marcar como caído.
• No crear 200 monitores el primer día.
• Empezar por lo que realmente te importa.

Monitorizarlo todo suena bien, pero si luego recibes alertas por cualquier tontería, dejarás de hacerles caso.

La alerta que no vas a atender es ruido.

---

Paso 6: configurar alertas con Telegram

Una de las mejores combinaciones para un homelab es Uptime Kuma + Telegram.

No quiero tener un panel abierto continuamente para comprobar que todo sigue funcionando. Prefiero que, cuando algo importante deje de responder, sea el propio sistema quien venga a buscarme.

Esa fue una de las razones por las que Uptime Kuma terminó convirtiéndose en una herramienta fija dentro de mi laboratorio.

Crear el bot en Telegram

1. Abre Telegram.
2. Busca @BotFather.
3. Ejecuta el comando /newbot.
4. Ponle un nombre al bot.
5. Elige un username que termine en bot.
6. BotFather te dará un token.

Ese token es una contraseña. No lo publiques, no lo pegues en capturas y no lo subas a GitHub. Si documentas la instalación, usa siempre valores ficticios o [REDACTADO]. Un token de Telegram expuesto puede permitir enviar mensajes como tu bot.

Obtener tu chat ID

Para que Uptime Kuma pueda enviarte mensajes, necesita saber a qué chat enviarlos.

La forma sencilla:

1. Escribe un mensaje a tu bot desde Telegram.
2. Obtén el chat ID usando una herramienta como @userinfobot o consultando la API de Telegram.

Si usas un grupo, añade el bot al grupo y obtén el ID del grupo.

En grupos, normalmente tendrás que dar permisos al bot para enviar mensajes.

Configurar Telegram en Uptime Kuma

1. Entra en Uptime Kuma.
2. Ve a Settings → Notifications.
3. Pulsa Setup Notification.
4. Elige Telegram.
5. Introduce el token del bot.
6. Introduce el chat ID.
7. Prueba la notificación.
8. Guarda.

Después, asigna esa notificación a los monitores importantes.

No hace falta que todo avise. Un monitor informativo puede quedarse sin alerta. Un servicio crítico sí debe avisar.

---

Paso 7: qué alertas tienen sentido

Mi criterio es sencillo:

Solo quiero alertas accionables.

Ejemplos de alertas útiles:

• Home Assistant no responde.
• AdGuard Home o Pi-hole no resuelven DNS.
• La web principal cae.
• Un certificado está cerca de caducar.
• El reverse proxy deja de responder.
• Un servidor importante no responde por ping.

Ejemplos de alertas que pueden convertirse en ruido:

• Servicios de prueba.
• Contenedores que apagas a propósito.
• Checks externos demasiado sensibles.
• Alertas por latencia puntual.
• Servicios no críticos con intervalos demasiado agresivos.

Con el tiempo también he aprendido que una alerta solo merece existir si, cuando aparece, sabes exactamente qué vas a hacer con ella.

Si empiezas a recibir avisos continuamente por cosas que realmente no requieren ninguna acción, terminarás ignorándolos todos. Y en ese momento la monitorización deja de cumplir su función.

No monitorizo para saberlo todo. Monitorizo para enterarme a tiempo de aquello sobre lo que realmente puedo actuar.

---

Paso 8: exponer Uptime Kuma de forma segura

Para uso doméstico, lo más seguro es no exponer Uptime Kuma directamente a Internet.

Opciones recomendadas:

• Acceso solo desde LAN.
• Acceso remoto por WireGuard o Tailscale.
• Reverse proxy con HTTPS y autenticación adicional si sabes lo que estás haciendo.

Si quieres usar Caddy como proxy inverso, puedes publicarlo con HTTPS. Pero no lo dejaría solo con usuario y contraseña de Uptime Kuma si va a estar expuesto al mundo.

Como mínimo:

• HTTPS.
• Contraseña fuerte.
• Autenticación adicional en el proxy si es posible.
• Restricción por IP o VPN si puedes.
• Actualizaciones frecuentes.

Sobre la publicación del puerto:

• Acceso directo desde la LAN: publica preferentemente el puerto en la IP LAN concreta del servidor:

  ports:
    - "IP_LAN_DEL_HOST:3001:3001"

  Sustituye IP_LAN_DEL_HOST por la dirección real del servidor. No configures una redirección de ese puerto en el router y verifica desde qué redes resulta accesible. En Linux con Docker Engine no confíes únicamente en UFW para limitar un puerto publicado; utiliza reglas compatibles con Docker o controles de red adicionales cuando sean necesarios.

• Caddy instalado en el host: limita el puerto al loopback:

  ports:
    - "127.0.0.1:3001:3001"

• Caddy dentro de Docker: elimina completamente ports y conecta ambos contenedores a la red Docker compartida.

Si quieres usar Caddy como proxy inverso, tienes dos arquitecturas posibles. Elige una y no combines fragmentos de ambas.

Escenario A — Caddy y Uptime Kuma en Docker. Caddy y Uptime Kuma deben estar conectados a la misma red Docker definida por el usuario. En este escenario Uptime Kuma no necesita publicar el puerto 3001 en el host.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - "./data:/app/data"
    networks:
      - proxy

networks:
  proxy:
    external: true

La red proxy debe ser la misma utilizada por el contenedor de Caddy. Si todavía no existe:

docker network create proxy

El Caddyfile será:

uptime.tudominio.com {
    reverse_proxy uptime-kuma:3001
}

En este escenario no uses 127.0.0.1:3001: dentro del contenedor de Caddy esa dirección apunta al propio contenedor. Tampoco es necesario publicar el puerto de Uptime Kuma en el host.

Escenario B — Caddy instalado directamente en el host. Uptime Kuma sigue en Docker, pero el puerto se publica únicamente en el loopback del host:

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"

Y en el Caddyfile del host:

uptime.tudominio.com {
    reverse_proxy 127.0.0.1:3001
}

Después de modificar el Compose, vuelve a aplicar la configuración:

docker compose up -d

Para seguir esta guía, elige una de las dos rutas. Docker permite conectar Uptime Kuma a la red interna de Caddy y publicar además un puerto, pero eso crea una segunda vía de acceso. Hazlo solo de forma intencionada, aplicando las restricciones de red correspondientes.

Recomendación principal: Caddy en Docker, red interna y sin ports; Caddy en el host, bind al loopback.

Pero mi recomendación real sigue siendo esta:

LAN o VPN primero.
Internet solo si hay una razón clara.

Si quieres profundizar, puedes ver mi artículo sobre proxy inverso con Caddy.

---

Paso 9: actualizar Uptime Kuma

Actualizar con Docker Compose es sencillo:

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

Antes de actualizar, especialmente si tienes muchos monitores, haz copia de la carpeta de datos:

tar -czf uptime-kuma-backup-$(date +%F).tar.gz data

O intégrala en tu sistema de backups.

La carpeta importante es:

/opt/uptime-kuma/data

Ahí está la configuración de Uptime Kuma. Si pierdes esa carpeta, pierdes monitores, notificaciones y usuarios.

Llevo utilizando Uptime Kuma desde hace años y, sinceramente, ha sido una de las herramientas más agradecidas de mantener. La he actualizado muchas veces y nunca me ha dado un problema serio. Sigue enviando las notificaciones, sigue comprobando los servicios y sigue haciendo exactamente aquello para lo que lo instalé.

Con el tiempo he aprendido que eso también dice mucho de una tecnología. Hay herramientas que impresionan el primer día y empiezan a complicarse cuando pasan los meses. Uptime Kuma ha sido justo lo contrario: hace una sola cosa, la hace muy bien y apenas exige mantenimiento.

---

Paso 10: copia de seguridad

Esto se olvida mucho.

Uptime Kuma no suele contener “datos de negocio”, pero sí contiene una parte importante de tu operación: qué servicios monitorizas, cómo los llamas, cómo avisas y qué estructura tienes.

Como mínimo, haz backup de:

/opt/uptime-kuma/docker-compose.yml
/opt/uptime-kuma/data

Si ya tienes una estrategia de backups 3-2-1, inclúyelo ahí.

Y si estás montando un sistema de monitorización más completo, puedes combinar Uptime Kuma con Prometheus, Grafana y alertas por Telegram, como explico en el artículo sobre monitorización de homelab con Uptime Kuma, Prometheus y Grafana.

---

Mi criterio hoy

Con muy poco esfuerzo puedes tener un sistema que te avise cuando algo importante deja de funcionar.

Pero para mí el verdadero valor de Uptime Kuma no está en que pueda monitorizar páginas web, APIs, puertos o certificados.

Está en la tranquilidad de saber que no tengo que comprobar continuamente si todo sigue funcionando.

Hoy sigue siendo una de esas herramientas que apenas llaman la atención porque simplemente cumplen su cometido. Y probablemente ese sea el mayor elogio que puedo hacerle a un software que forma parte de mi laboratorio desde hace tanto tiempo.

Con el tiempo he descubierto que una buena herramienta de monitorización no es la que más información ofrece. Es la que consigue que dejes de preocuparte por comprobar continuamente si todo sigue funcionando.

¿Usas Uptime Kuma, Grafana, Netdata o algo distinto para monitorizar tu homelab? Cuéntalo en los comentarios — las configuraciones reales enseñan más que cualquier captura perfecta.