Uptime Kuma en Docker: monitoriza tu homelab
Uptime Kuma es una herramienta de monitorización self-hosted que puedes desplegar con Docker en minutos. Este tutorial explica cómo instalarlo, crear tus primeros monitores y recibir alertas cuando algo falla.
Tienes servicios corriendo y cero alertas activas
Si tienes un homelab con varios contenedores levantados —Jellyfin, Nextcloud, Vaultwarden, lo que sea— y nunca has configurado ningún sistema de alertas, no eres el único. La mayoría empieza igual: los servicios arrancan, funcionan, y mientras nadie se queja asumes que todo va bien. El problema llega cuando alguien de casa te dice «oye, que no carga la película» y llevas horas caído sin saberlo.
Montar un sistema de monitorización puede sonar a cosa seria, de empresa con sysadmins dedicados y herramientas que tardan días en configurar. Si has mirado Nagios o Zabbix y has cerrado la pestaña a los dos minutos, te entiendo. No es para lo que tienes montado en casa, ni para el tiempo que le quieres dedicar.
En este tutorial vas a instalar Uptime Kuma con Docker, configurar tus primeros monitores y conectar alertas reales a Telegram —o al canal que uses— para que cuando algo caiga te enteres tú antes que nadie. Sin agentes externos, sin cuentas de pago, y sin tocar nada de lo que ya tienes corriendo.
Por qué importa
Despliegue en minutos
Una imagen Docker y un volumen en /app/data es todo lo que necesitas para arrancar la interfaz en el puerto 3001.
Chequeos cada 20 segundos
El intervalo mínimo configurable es 20 s por monitor: HTTP, TCP, ping ICMP o contenedor Docker.
Alertas donde ya estás
Conecta Telegram, Discord, Slack, ntfy o email desde la UI; sin tocar ningún fichero de configuración.
Status page incluida
Crea una página pública con URL propia para comunicar incidencias sin exponer la interfaz de administración.
Instalación de Uptime Kuma con Docker
Uptime Kuma corre perfectamente en un contenedor Docker. No necesita base de datos externa, un proxy especial ni configuración previa: arranca, apunta a un volumen y ya está funcionando.
Lo único imprescindible es un volumen persistente. Sin él, los datos —monitores, historiales, alertas— se pierden cada vez que recreas el contenedor. Con el volumen, puedes recrear el contenedor sin perder nada.
Comando Docker básico
docker run -d \
--restart=always \
-p 3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:1Con :1 en vez de :latest te quedas en la rama estable. El tag :latest puede incluir versiones beta con cambios no consolidados, así que mejor no usarlo en producción.
Con Docker Compose
Si ya tienes otros servicios en Compose, lo más limpio es añadir Uptime Kuma al mismo fichero:
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
restart: always
ports:
- "3001:3001"
volumes:
- uptime-kuma-data:/app/data
volumes:
uptime-kuma-data:Levántalo con docker compose up -d y en unos segundos tendrás la interfaz en http://tu-ip:3001. Primer servicio añadido, sin tocar nada más.
Primera vez: crear cuenta y ojear la interfaz
Al abrir el navegador por primera vez te pide crear una cuenta de administrador. No hay usuario por defecto; tú defines las credenciales en ese primer acceso y ya no vuelve a pedírtelo.
La interfaz es un panel único: la lista de monitores a la izquierda, el detalle con el historial de respuestas a la derecha. No hay menús complicados ni wizards de configuración de cuatro pasos.
Un detalle importante desde el principio: el puerto 3001 queda abierto en HTTP plano. Para uso interno en la red local está perfectamente bien; para exponerlo a internet necesitas un proxy inverso con HTTPS, que vemos al final del post.
Crear tus primeros monitores
Una vez dentro, el botón Add New Monitor es tu punto de entrada. Uptime Kuma soporta varios tipos de comprobación; los más habituales en un homelab son HTTP(s), TCP port y ping.
Monitor HTTP(s)
El tipo más habitual. Uptime Kuma hace una petición HTTP al endpoint que indiques y comprueba el código de respuesta. Si devuelve 200, el servicio está marcado como up.
- Haz clic en Add New Monitor
- Tipo: HTTP(s)
- URL: la dirección completa, por ejemplo
https://mi-nextcloud.lan - Interval: mínimo 20 segundos; para servicios importantes, 60 s suele ser suficiente
- Guarda y ya empieza a monitorizar
Ten en cuenta que un monitor HTTP solo ve la capa HTTP. Tu app puede responder 200 con un error interno que no se refleja en el status code. Para detectar ese tipo de fallos necesitarías un endpoint de health check propio en la aplicación.
Monitor TCP port
Útil para servicios que no hablan HTTP: bases de datos, brokers MQTT, servidores de juegos. Selecciona tipo TCP Port, pon el host y el puerto, y Uptime Kuma abre una conexión TCP para comprobar si el puerto responde. Sin más.
Ping (ICMP)
Para comprobar que un dispositivo de red está vivo: el NAS, un switch gestionado, la impresora de red. Selecciona Ping, pon la IP o hostname y listo. Es el monitor más simple y también el más rápido de configurar.
Notificaciones: que te avise antes de que te enteres por otro lado
De nada sirve un monitor si no te avisa cuando algo cae. La configuración está en Settings → Notifications; una vez creado un canal lo asignas a uno o varios monitores desde la edición de cada uno.
Opciones que funcionan bien en un homelab:
- Telegram: necesitas un bot token y tu chat ID. En unos minutos lo tienes listo y los mensajes llegan al instante, sin depender de servidores de correo.
- Email: SMTP estándar. Funciona con cualquier servidor de correo, incluyendo Gmail con una app password.
- Gotify / ntfy: si ya tienes notificaciones push self-hosted, conectarlo es trivial vía URL y token de acceso.
- Webhook genérico: para integraciones custom o servicios que no están en la lista nativa.
Si quieres distintos canales según la criticidad —alertas críticas al móvil, informativos por email— puedes asignar canales diferentes por monitor. La granularidad está ahí si la necesitas.
Status pages: comunica el estado sin levantar el teléfono
Uptime Kuma incluye páginas de estado públicas. Puedes crear una URL del tipo /status/mi-pagina que muestre el estado actual de los servicios que elijas, sin dar acceso al panel de administración.
Es útil cuando tienes usuarios internos —familia, un equipo pequeño— que quieren saber si algo está caído sin tener que preguntarte directamente. O simplemente para tenerlo visible en una pantalla secundaria del homelab junto al resto de dashboards.
Cada status page es configurable: nombre, logo opcional, qué monitores aparecen y si se muestra el historial de incidencias. No es una herramienta de comunicación corporativa, pero para un homelab o equipo pequeño cumple perfectamente.
Exponerlo con un proxy inverso (imprescindible si lo sacas a internet)
Repetimos esto porque importa: exponer el puerto 3001 directamente a internet sin TLS es un riesgo operacional real. Las credenciales viajan en claro y la interfaz queda accesible para cualquiera que escanee ese puerto.
La solución estándar es un reverse proxy que termine TLS. Con Caddy es especialmente sencillo porque gestiona los certificados Let’s Encrypt de forma automática:
uptime.tudominio.com {
reverse_proxy uptime-kuma:3001
}Con Nginx Proxy Manager —si ya lo tienes corriendo en el homelab— es igual de directo desde la UI. Con Traefik puedes hacerlo con labels en el propio Compose sin tocar ficheros de configuración adicionales.
Un aviso final que conviene no pasar por alto: Uptime Kuma no tiene alta disponibilidad nativa. Si el host donde corre se cae, el monitor se cae con él. Para uso doméstico eso suele ser perfectamente aceptable; si necesitas que el propio sistema de monitorización sea resistente a caídas del host, tendrás que plantearte una solución redundante o complementarlo con un servicio externo.
Preguntas frecuentes
Q: ¿Funciona Uptime Kuma si mi servidor se cae?
A: Depende de dónde lo tengas instalado. Uptime Kuma no tiene clustering ni alta disponibilidad nativa: si el host que lo corre se cae, el monitor también cae. Para homelab es más que suficiente, pero no lo uses como única guardia si necesitas detectar caídas del propio servidor que lo aloja.
Q: ¿Qué pasa si borro el contenedor Docker?
A: Pierdes todos tus monitores, alertas y páginas de estado si no tienes un volumen persistente montado. Los datos viven en SQLite dentro de /app/data; mapea ese directorio a tu host antes de arrancar el contenedor y no perderás nada al recrearlo o actualizarlo.
Q: ¿Vale Uptime Kuma para detectar cualquier tipo de caída?
A: Para caídas de capa HTTP, TCP, ping o DNS, sí funciona bien. Lo que no detecta es el estado interno de tu aplicación: si tu web responde 200 pero la base de datos está rota por dentro, Uptime Kuma lo verá como 'online'. Para eso necesitarías endpoints de healthcheck propios en tu app.
Q: ¿Cómo recibo alertas en Telegram o Discord?
A: Desde la propia interfaz web, en la sección 'Notification', configuras la integración con tu canal de Telegram, Discord, Slack, Gotify u otros. No hay fichero de configuración externo; todo se gestiona desde la UI. El número exacto de integraciones disponibles varía según la versión que instales.
Q: ¿Es seguro exponer el puerto 3001 directamente a internet?
A: No es recomendable. Por defecto el puerto 3001 no tiene TLS, lo que expone tu interfaz de administración en claro. Si quieres acceder desde fuera de tu red local, ponle por delante un reverse proxy como Caddy, Nginx o Traefik con HTTPS; de lo contrario cualquiera en tu red o ruta podría interceptar las credenciales.
Deja una respuesta