Cómo instalar Uptime Kuma para monitorización básica

Probado con Uptime Kuma 2.5.5 · Docker Engine 29.5 · Docker Compose v2 · verificado 2026-09-16

Actualizado: 2026-09-16

Uptime Kuma es probablemente el monitor de disponibilidad autoalojado de código abierto más usado hoy. Nació en 2021 como proyecto personal de Louis Lam y ha crecido hasta acumular más de 90.000 estrellas en GitHub^[1] y más de 180 millones de descargas de su imagen en Docker Hub. Esta guía cubre cómo instalarlo con Docker de forma razonable, configurar los monitores básicos, enchufar avisos a Telegram y Discord, y los errores operativos más habituales la primera vez.

Los pasos se han vuelto a ejecutar el 16 de septiembre de 2026 con Uptime Kuma 2.5.5, publicada ese mismo día, sobre Docker Engine 29.5 y Docker Compose v2. Las salidas que verás son las de esa prueba.

Puntos clave

• Uptime Kuma llena el hueco entre "montar Prometheus + Blackbox Exporter + Alertmanager" y "pagar una suscripción mensual a UptimeRobot".

• Un solo contenedor cubre comprobaciones HTTP, TCP, ping, DNS, gRPC, bases de datos y más de 90 canales de aviso.

• Fija la etiqueta de la imagen: usa 2 o 2.5.5, porque latest todavía descarga la rama 1.x.

• Configurar backup desde el primer día: todo el estado vive en /app/data; si ese volumen se pierde, se pierde toda la configuración.

• No dejar la interfaz expuesta sin HTTPS ni autenticación fuerte: Kuma guarda credenciales sensibles de notificación.

• Validar los avisos con un monitor artificial que falle a propósito antes de confiar en que el flujo real funciona.

Qué es Uptime Kuma y qué esperar

Uptime Kuma es una aplicación web escrita en Node.js que monitoriza disponibilidad de servicios mediante comprobaciones periódicas y notifica cuando detecta caídas. Soporta una variedad amplia de tipos de comprobación:

• HTTP/HTTPS con validación de código de respuesta y contenido del cuerpo.

• Ping ICMP, puertos TCP abiertos, consultas DNS.

• PostgreSQL, MySQL/MariaDB, SQL Server, Oracle, MongoDB y Redis, además de endpoints gRPC.

• Caducidad de certificados TLS y de dominios, como opción de los monitores HTTP.

• Más de una docena de tipos adicionales, entre ellos NTP (desde la 2.5.0) y SFTP (desde la 2.5.4).

La interfaz web permite agrupar monitores, definir páginas de estado públicas y configurar más de noventa canales de avisos.

La propuesta pragmática: llenar el hueco entre "montar Prometheus más Blackbox Exporter más Alertmanager con reglas a mano" y pagar un servicio externo como UptimeRobot. Para equipos con entre cinco y cien servicios que monitorizar, es la opción más razonable. La instalación es un archivo Compose, un comando y dos pantallas en el navegador, y la configuración es visual, sin YAML ni código. Es el complemento natural de un sistema de backups como restic: mientras restic protege los datos, Kuma vigila que los servicios estén vivos.

Requisitos previos

• Un servidor con Docker instalado. Cualquier distribución Linux reciente vale; Debian 13 o Ubuntu 24.04 son opciones estables. La imagen se publica para amd64, arm64 y arm.

• Recursos: en nuestra prueba, 100 monitores HTTP cada 60 s contra un servicio local mantuvieron el contenedor entre 114 y 162 MiB de RAM. La CPU no pasó del 1 % de un núcleo salvo picos del 6,4 %, en una máquina compartida con carga media de 40 sobre 18 núcleos. Un VPS de 1 vCPU y 1 GB tiene margen para eso, aunque no lo hemos probado.

• Almacenamiento: la imagen completa pesa unos 600 MB comprimida (1,8 GB en disco en arm64) y la 2.5.5-slim, sin MariaDB ni Chromium embebidos, unos 180 MB. El directorio de datos pasó de 1,4 MB a 4,4 MB en seis minutos con 100 monitores. Cada noche, Kuma borra los latidos sin cambio de estado de más de 24 horas, y el resumen diario se guarda 365 días por defecto (Ajustes → Historial de monitor).

• Monta /app/data en un disco local o en un volumen de Docker. El proyecto no admite NFS, porque SQLite necesita bloqueos de fichero POSIX para no corromperse.

• Si vas a exponer Kuma a internet, necesitas un dominio, certificados válidos y un proxy inverso (nginx, Caddy, Traefik o Nginx Proxy Manager) que reenvíe las cabeceras Upgrade y Connection de WebSocket. Kuma no funciona bajo una subruta como /kuma: necesita un dominio o subdominio propio.

Instalación con Docker

La forma recomendada es Docker Compose con un archivo de configuración pequeño, fijado a la versión 2.5.5:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.5
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"
    environment:
      - UPTIME_KUMA_PORT=3001
    healthcheck:
      test: ["CMD", "extra/healthcheck"]
      interval: 60s
      timeout: 30s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 512M

Guarda esto como docker-compose.yml y levanta con docker compose up -d (la imagen también está publicada en Docker Hub^[2]). La imagen ya define ese mismo healthcheck con un periodo de arranque de 180 s, y Docker conserva ese periodo al combinarlo con el del compose. Si el proxy inverso corre en la misma máquina, publica el puerto como "127.0.0.1:3001:3001" para no dejarlo abierto a la red.

Comprueba el arranque con docker compose logs; una instalación nueva de la 2.5.5 escribió esto (extracto):

Welcome to Uptime Kuma
Your Node.js version: 22.22.3
2026-09-16T20:55:40Z [SERVER] INFO: Uptime Kuma Version: 2.5.5
2026-09-16T20:55:41Z [SERVER] INFO: Data Dir: ./data/
2026-09-16T20:55:41Z [SETUP-DATABASE] INFO: Starting Setup Database
2026-09-16T20:55:41Z [SETUP-DATABASE] INFO: -  http://localhost:3001
2026-09-16T20:55:41Z [SETUP-DATABASE] INFO: Waiting for user action...

Abre el navegador en http://tu-servidor:3001. Desde la 2.0, la primera pantalla pregunta qué base de datos usar: MariaDB embebida (solo en la imagen completa), MariaDB/MySQL externa o SQLite. Elige SQLite, que la propia pantalla recomienda para despliegues pequeños. Kuma guarda la elección en data/db-config.json, y pasar después de SQLite a MariaDB no tiene soporte oficial.

La pantalla siguiente es "Crea tu cuenta de administrador". Elige un usuario y una contraseña robustos: Kuma exige al menos 6 caracteres que mezclen letras y números, y no tiene recuperación por correo. Si pierdes la contraseña, restablécela desde el contenedor:

docker exec -it uptime-kuma npm run reset-password

El script pide la nueva contraseña dos veces y la muestra en pantalla mientras la escribes (aquí se ha omitido). Después cierra las demás sesiones abiertas y termina así:

Found user: admin
New Password:
Confirm New Password:
Connecting to ws://localhost:3001 to disconnect all other socket clients
Logged in.
Password reset successfully.

La rama 2.x es la estable desde que salió la 2.0.0, el 20 de octubre de 2025, el mismo día que la 1.23.17, última de la serie 1.x. Cuidado con latest: la wiki la da por obsoleta y en nuestra prueba todavía descargó la 1.23.17. Usa louislam/uptime-kuma:2 o una versión fija como 2.5.5, publicada el 16 de septiembre de 2026.

Uptime Kuma no tiene soporte multiusuario: la instalación crea una sola cuenta, rechaza un segundo alta y la 2.5.5 no trae pantalla para añadir usuarios. Para un equipo pequeño, comparte esa cuenta con 2FA o pon delante un proxy con su propia autenticación.

Qué cambió desde la 2.4.0

Esta guía se escribió con Uptime Kuma 2.4.0 (31 de mayo de 2026) y pasó a la 2.5.3 el 2 de septiembre. El 16 de septiembre de 2026 repetimos la instalación en linux/arm64 con la 2.5.5, marcada como Latest en la página de versiones de GitHub^[3]. El contenedor pasó su propio extra/healthcheck, y un directorio de datos creado con la 2.5.3 arrancó sin parches de base de datos y con monitores, avisos y usuario intactos. Esto trae la serie 2.5:

• 2.5.0^[4] (1 de agosto de 2026): tipo de monitor NTP, intervalos sin el tope de 24 días, cabeceras adicionales en los avisos SMTP, etiqueta next-rootless, columnas up/down de stat_daily ampliadas a INTEGER sin signo y nuevos proveedores de SMS.
• 2.5.1^[5] (22 de agosto de 2026): nuevos proveedores de avisos (SMS Gateway, ClickUp, TurboSMTP, BearSMS, Pinglet y otros).
• 2.5.2^[6] y 2.5.3^[7] (22 de agosto de 2026): arreglan la instalación sin Docker que rompió la 2.5.1 y corrigen el número de versión; por lo demás, la 2.5.3 es la 2.5.1.
• 2.5.4^[8] (11 de septiembre de 2026): actualiza JSONata a 2.2.2, que corrige la CVE-2026-77415^[9] (ejecución de código arbitrario con expresiones manipuladas, de gravedad crítica); cierra una debilidad de denegación de servicio que las notas identifican como GHSA-wf2j-5mc7-5c4w; añade el tipo de monitor SFTP y los proveedores Signalgrid, Notify! y Amoot SMS.
• 2.5.5^[10] (16 de septiembre de 2026): corrige una fuga de memoria en los monitores TCP.

Si vienes de la 2.5.3, la 2.5.4 ya justifica la actualización. La 2.5.3 lleva JSONata 2.1.1, dentro del rango afectado, y Kuma usa esa biblioteca para evaluar las consultas JSON de sus monitores. Detén el contenedor, copia data, cambia la etiqueta y vuelve a levantarlo, como indica la guía de migración^[11]:

docker compose down
sudo cp -a data data-2.5.3
sed -i 's/uptime-kuma:2.5.3/uptime-kuma:2.5.5/' docker-compose.yml
docker compose up -d
docker compose logs -f

Configuración inicial básica

Nada más entrar por primera vez, conviene ajustar tres cosas:

• Zona horaria en Ajustes → General. Hay dos: "Mostrar Zona Horaria" sigue por defecto la del navegador, y la del servidor arranca en UTC dentro del contenedor si no defines la variable TZ. Pon la del servidor en Europe/Madrid si operas desde aquí.

• Autenticación de dos factores en Ajustes → Seguridad, con cualquier aplicación TOTP (Google Authenticator, Authy o 1Password): es una línea de defensa importante dado que Kuma mantiene credenciales sensibles.

• Si Kuma está detrás de un proxy inverso, ve a Ajustes → Proxy Inverso → Encabezados HTTP y pon "Proxy de Confianza" en Sí. Sin eso, las direcciones IP que registra son las del proxy y no las reales.

Crear los primeros monitores

Para cada monitor conviene pensar en tres ejes: qué compruebo (endpoint), cada cuánto (intervalo) y qué considera fallo (condiciones).

Para sitios web públicos, la comprobación estándar es HTTP con el intervalo por defecto de 60 segundos. Verifica al menos el código de respuesta y, con el tipo de palabra clave para HTTP(s), que el cuerpo contenga una cadena específica. Esto último es clave: un monitor que solo verifica código 200 no detecta cuando tu aplicación devuelve una página de error bonita con código 200.

Desde la 2.0, los monitores nuevos se crean con 0 reintentos, así que un solo fallo dispara el aviso. Si un corte de pocos segundos no debe despertar a nadie, sube "Reintentos" a 1 o 2 y ajusta el intervalo de reintento.

Para servicios internos expuestos por TCP, usa el tipo TCP Port. Los certificados no tienen un tipo propio: activa "Notificación de Caducidad del Certificado" en el monitor HTTP (viene desactivada) y fija los umbrales en Ajustes → Notificaciones, que por defecto avisa a 7, 14 y 21 días. El aviso de caducidad del dominio, en cambio, viene activado en los monitores nuevos.

Agrupa los monitores por criticidad (crítico, importante, informativo) y por sistema. Las etiquetas sirven para filtrar el panel, pero no dirigen avisos, que se asignan monitor a monitor. Para mandar los avisos graves a un canal propio, crea un monitor de tipo Grupo con ese canal y mete dentro los monitores críticos: el grupo cae en cuanto cae uno de sus hijos. En nuestra prueba, el grupo envió [Criticos] [🔴 Down] Child monitors down: CANARIO - no tocar.

Configurar avisos a Telegram

Telegram es uno de los canales de aviso más cómodos:

• Habla con @BotFather en Telegram, sigue las instrucciones y apunta el token que te da (el proceso está descrito en la documentación oficial de bots de Telegram^[12]).

• Abre una conversación con el bot y envíale /start. El botón "Obtener automáticamente" del formulario de Kuma lee el identificador del chat; a mano, consulta https://api.telegram.org/bottu_token_del_bot/getUpdates, con tu token pegado tras bot. Para un grupo, añade el bot al grupo y haz el mismo truco.

• En Uptime Kuma: Ajustes → Notificaciones → Configurar notificación, y elige Telegram en "Tipo de notificación". Pega el token y el identificador de chat, y prueba con el botón "Test".

Para no asignar la notificación monitor a monitor, marca en ese mismo formulario "Habilitado por defecto", que la añade a los monitores nuevos, y "Aplicar en todos los monitores existentes" para los que ya tienes.

Configurar avisos a Discord

Discord usa webhooks entrantes:

• En tu servidor de Discord: ajustes del canal → Integraciones → Webhooks → Nuevo webhook. Copia la URL del webhook.

• En Uptime Kuma: Ajustes → Notificaciones → Configurar notificación → Discord. Pega la URL y elige nombre y avatar opcionales. Prueba y asigna a los monitores deseados.

Un detalle importante: Discord limita la frecuencia de mensajes por webhook. Su documentación de límites de tasa^[13] explica que calcula los límites por webhook, que pueden cambiar y que no conviene fijarlos en el código; al superarlos, la API responde con HTTP 429. Si tienes 100 monitores y todos fallan a la vez por un corte de red, Discord puede empezar a rechazar mensajes y perderás avisos.

Cuando el número de monitores crece, agrupa los críticos bajo un monitor de tipo Grupo con un único aviso, o usa un intermediario como ntfy o un servicio de guardia dedicado.

Página de estado pública

Una característica útil es la página de estado pública, donde puedes mostrar el estado de servicios seleccionados a usuarios externos sin darles acceso al panel completo. En la cabecera: Páginas de estado → Nueva Página de Estado. Pon un nombre y un slug, y en el editor elige qué monitores mostrar, el tema y los nombres de dominio.

La práctica recomendada es tener al menos dos páginas:

• Una pública con los servicios cara al usuario.

• Una interna con todos los monitores incluyendo los internos. Esto te permite comunicar estado a clientes sin revelar detalles de tu infraestructura.

Kuma no protege las páginas de estado con contraseña: cualquiera que conozca la ruta /status/ seguida del slug puede verla. Protege la interna con la autenticación del proxy inverso o déjala accesible solo por VPN.

Probar los avisos con un monitor que falle a propósito

Configurar Telegram o Discord y ver el mensaje de prueba solo demuestra que el token es válido. No demuestra que te vayas a enterar de una caída real: el botón de prueba no recorre el mismo camino que un monitor que cambia de estado. La forma barata de comprobarlo es crear una caída de verdad, en algo que no importe.

1. Crea un monitor HTTP contra un puerto cerrado, por ejemplo http://127.0.0.1:9, o contra un dominio inventado. Llámalo algo obvio como CANARIO - no tocar.

2. Bájale el intervalo y los reintentos (por ejemplo, 20 s y 1 reintento) para no esperar. Asócialo a todos los canales de aviso que quieras validar, no solo a uno.

3. Espera al aviso de caída. En nuestra prueba con la 2.5.5, el monitor quedó pendiente con el primer fallo y el aviso salió 20 s después con el texto [CANARIO - no tocar] [🔴 Down] connect ECONNREFUSED 127.0.0.1:9. Si no llega, el problema está en el canal, no en tu servicio, y lo has descubierto en frío, no a las tres de la mañana.

4. Apunta el monitor a algo que sí responda y confirma que llega también el aviso de recuperación (en la prueba, [CANARIO - no tocar] [✅ Up] 200 - OK). Es el que más se olvida de configurar y el que te dice que la incidencia ya terminó.

5. Deja el canario pausado, no borrado. Cuando cambies de token, de canal o de versión, lo reactivas un minuto y vuelves a tener la certeza.

Repite esta comprobación cada vez que toques la configuración de notificaciones. Un aviso que no salta es indistinguible de no tener monitorización.

Errores frecuentes que evitar

• No configurar backup: Uptime Kuma guarda todo en /app/data; si ese volumen se pierde, pierdes toda la configuración y el historial. Desde la 2.0, copiar ese directorio es el único método de copia soportado, porque la exportación a JSON desapareció. Programa una copia diaria del directorio de datos a otra ubicación.

• Dejar la interfaz expuesta sin HTTPS ni autenticación fuerte: Kuma gestiona credenciales sensibles (tokens de avisos, cadenas de conexión, URLs internas). Exponerla con una contraseña débil es regalar una entrada a tu infraestructura.

• No validar los avisos: tras configurar Telegram o Discord, prueba con un monitor artificial que caiga a propósito para confirmar que el aviso llega. No confíes en que está funcionando porque viste el mensaje de prueba; el flujo real "monitor falla, aviso sale" tiene más piezas.

• Intervalos demasiado agresivos: 10 segundos multiplica por seis las peticiones frente a 60 segundos, tanto contra tus servicios como contra la base de datos de Kuma. Los 60 segundos por defecto son un buen punto de partida.

Preguntas frecuentes

¿Uptime Kuma es gratuito?

Sí. Es software de código abierto bajo licencia MIT, sin coste de licencia ni límite de monitores. El único gasto real es el servidor donde lo alojas.

¿Qué pasa si el servidor donde corre Uptime Kuma se cae?

Dejas de recibir avisos mientras dure la caída, porque el propio monitor no puede vigilarse a sí mismo. Si la monitorización es crítica, conviene un heartbeat externo independiente (otro Kuma en un proveedor distinto, o un servicio de guardia de terceros) que te avise cuando Kuma deja de responder.

¿Admite varios usuarios con permisos distintos?

No. Uptime Kuma 2.5.5 tiene una sola cuenta de administrador: la instalación rechaza un segundo alta y no hay pantalla para gestionar usuarios. Si otras personas necesitan entrar, comparte la cuenta con 2FA activado o pon delante un proxy inverso con su propia autenticación y control de acceso.

¿Cómo recupero la contraseña de administrador?

Ejecuta docker exec -it uptime-kuma npm run reset-password y escribe la nueva contraseña dos veces. El script cierra las demás sesiones abiertas, y en nuestra prueba la nueva contraseña funcionó al momento. No hizo falta reiniciar el contenedor ni tocar la base de datos a mano.

Conclusión

Uptime Kuma resuelve bien un problema acotado. No intenta ser Grafana, no intenta ser Prometheus con reglas complejas, no gestiona métricas de aplicación. Hace una cosa (comprobar si tus cosas están vivas y avisarte si no) y la hace con simpleza suficiente para que un equipo pequeño la mantenga sin dedicar tiempo significativo.

Para un equipo que acaba de entrar en monitorización seria, Uptime Kuma es probablemente la mejor primera pieza a instalar antes que nada más. Te da cobertura básica inmediata y te enseña la disciplina de pensar qué merece ser monitorizado. Cuando llegue el momento de añadir observabilidad más profunda con Prometheus o con una pila completa (como los cuadros de mando SRE con IA), Kuma seguirá cubriendo su capa sin interferir. Es una herramienta que no compite con nada más; simplemente hace su trabajo y desaparece del radar hasta que algo falla, que es exactamente lo que se le pide a un monitor de disponibilidad.

Lee también la versión en inglés: How to install Uptime Kuma for basic monitoring.

Fuentes

1. GitHub
2. Docker Hub
3. página de versiones de GitHub
4. 2.5.0
5. 2.5.1
6. 2.5.2
7. 2.5.3
8. 2.5.4
9. CVE-2026-77415
10. 2.5.5
11. guía de migración
12. documentación oficial de bots de Telegram
13. documentación de límites de tasa
14. Uptime Kuma Wiki: etiquetas de Docker
15. Uptime Kuma Wiki: restablecer la contraseña desde la línea de comandos
16. Uptime Kuma Wiki: proxy inverso