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

Actualizado: 2026-05-03

Uptime Kuma es probablemente el monitor de disponibilidad autoalojado más popular del panorama de código abierto. Aparecido en 2021 como proyecto personal de Louis Lam, ha crecido hasta tener más de 60.000 estrellas en GitHub, una comunidad activa y despliegues en producción en miles de organizaciones pequeñas y medianas. 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 que es fácil cometer la primera vez.

Puntos clave

• Uptime Kuma llena el hueco entre “montar Prometheus + Blackbox Exporter + Alertmanager” y “pagar 50 euros al mes a UptimeRobot”.
• Un contenedor de ~200 MB cubre comprobaciones HTTP, TCP, ping, DNS, SSL, gRPC y más de 90 canales de aviso.
• 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.
• Consultas SQL contra bases de datos, endpoints gRPC.
• Certificados SSL próximos a expirar.
• Más de una docena de tipos adicionales.

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 50 euros al mes a UptimeRobot”. Para equipos con entre cinco y cien servicios que monitorizar, es la opción más razonable. La instalación lleva diez minutos, la configuración es visual sin YAML ni código, y un contenedor de 200 MB cubre todo el caso de uso sin más piezas. 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.
• Recursos mínimos: con 100 monitores activos, Kuma usa aproximadamente 200 MB de RAM y menos del 5% de CPU de un núcleo. Cualquier VPS modesto (1 vCPU, 1 GB RAM) es suficiente.
• Almacenamiento: con comprobaciones cada 60 segundos de 50 monitores, la base crece aproximadamente 100 MB al mes. Planifica al menos 10 GB dedicados a Kuma si quieres conservar histórico largo.
• Si vas a exponer Kuma a internet, necesitas un dominio, un proxy inverso (nginx, Caddy o Traefik) y certificados SSL válidos.

Instalación con Docker

La forma recomendada es Docker Compose con un archivo de configuración pequeño:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1.23.16
    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. Abre el navegador en http://tu-servidor:3001 y verás la pantalla de creación del usuario administrador. Elige un usuario y contraseña robustos: Uptime Kuma no tiene sistema de recuperación de contraseña directo y recuperar acceso requiere editar la base de datos manualmente.

La versión 1.23.x es la rama estable a finales de 2025; la 2.0 está disponible pero con algunos detalles todavía en movimiento. Para una instalación nueva de producción, la 1.23 es la opción conservadora.

Configuración inicial básica

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

1. Zona horaria en Configuración → General; por defecto está en UTC; configúrala a Europe/Madrid si operas desde aquí.
2. Autenticación de dos factores en Configuración → Seguridad con Google Authenticator, Authy o 1Password: es una línea de defensa importante dado que Kuma mantiene credenciales sensibles.
3. Si Kuma está detrás de un proxy inverso, marca “Confiar en cabeceras de proxy” en General, sin lo cual 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 intervalo de 60 segundos. Verifica al menos el código de respuesta y opcionalmente 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.

Para servicios internos expuestos por TCP, usa el tipo Port; para certificados SSL próximos a expirar, hay un tipo específico que conviene configurar con umbral de 21 días.

Agrupa los monitores en etiquetas coherentes por criticidad (crítico, importante, informativo) y por sistema. Así puedes filtrar en paneles y dirigir avisos distintos a canales distintos según gravedad.

Configurar avisos a Telegram

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

1. Habla con @BotFather en Telegram, sigue las instrucciones y apunta el token que te da.
2. Abre una conversación con el bot y envíale /start, luego consulta https://api.telegram.org/bot<TU_TOKEN>/getUpdates para ver el identificador del chat. Para un grupo, añade el bot al grupo y haz el mismo truco.
3. En Uptime Kuma: Configuración → Notificaciones → Añadir → Telegram. Pega el token y el identificador de chat, y prueba con el botón “Probar”.

Asigna esta notificación a los monitores preferiblemente desde las etiquetas de grupo, no monitor por monitor, para mantener la configuración manejable.

Configurar avisos a Discord

Discord usa webhooks entrantes:

1. En tu servidor de Discord: ajustes del canal → Integraciones → Webhooks → Nuevo webhook. Copia la URL del webhook.
2. En Uptime Kuma: Notificaciones → Añadir → 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 (aproximadamente 30 por minuto). 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. Para producción seria con muchos monitores, considera agrupar avisos por ventana de tiempo usando un intermediario como ntfy.sh 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 el menú lateral: Páginas de Estado → Añadir Nueva. Elige qué monitores mostrar, el tema y el 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.

Errores frecuentes que evitar

1. No configurar backup — Uptime Kuma guarda todo en /app/data; si ese volumen se pierde, pierdes toda la configuración y el historial. Programa una copia diaria del directorio de datos a otra ubicación.
2. 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.
3. 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.
4. Intervalos demasiado agresivos — 10 segundos para 100 monitores genera mucha carga; 60 segundos es razonable para la mayoría de casos.

Conclusión

Uptime Kuma es una herramienta notablemente bien hecha para 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, te enseña disciplina de pensar qué merece ser monitorizado, y 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.