groales/uptime-kuma
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ba4d3c73008e5f76d79f3c66ae123e64b811d839
uptime-kuma/README.md

14 KiB
Raw Blame History

Uptime Kuma - Monitorización de Servicios

Uptime Kuma es una herramienta de monitorización self-hosted moderna y elegante. Permite monitorizar servicios HTTP(s), TCP, Ping, DNS, Docker containers, y mucho más con notificaciones multi-canal.

Características

  • ✅ Monitorización multi-protocolo: HTTP(s), TCP, HTTP(s) Keyword, HTTP(s) Json Query, Ping, DNS, Docker, Steam Game Server
  • ✅ Notificaciones: 90+ servicios (Telegram, Discord, Slack, Email, Gotify, Webhooks, etc.)
  • ✅ Status Pages: Páginas de estado públicas personalizables
  • ✅ Mapeo de servicios: Vista gráfica de dependencias
  • ✅ Certificados SSL: Monitorización de expiración
  • ✅ Multi-idioma: Interfaz en múltiples idiomas incluyendo español
  • ✅ 2FA: Autenticación de dos factores
  • ✅ Sin base de datos externa: Usa SQLite embebida

Requisitos Previos

  • Docker y Docker Compose instalados
  • Proxy inverso configurado:
    • Traefik con red proxy externa, o
    • Nginx Proxy Manager
  • Dominio con DNS apuntando al servidor

⚠️ IMPORTANTE: Este repositorio NO incluye modo standalone. Requiere proxy inverso (Traefik o NPM) para funcionar.

Despliegue con Portainer

Opción A: Git Repository (recomendado)

  1. En Portainer, ir a Stacks → Add stack

  2. Seleccionar Repository

  3. Configurar:

    • Repository URL: https://git.ictiberia.com/groales/uptime-kuma
    • Repository reference: refs/heads/main
    • Compose path: docker-compose.yml

  4. En Environment variables, añadir:

    Para Traefik:

    DOMAIN_HOST=uptime.example.com

    Para NPM: No requiere variables

  5. En Advanced mode, añadir (solo Traefik):

    additional_files:
  - docker-compose.override.traefik.yml.example

  6. Click en Deploy the stack

Opción B: Web Editor

  1. En Portainer, ir a Stacks → Add stack
  2. Nombre: uptime-kuma
  3. Selecciona Web editor
  4. Pega el contenido de docker-compose.yml
  5. En Environment variables, añade las mismas variables que la Opción A
  6. Click en Deploy the stack

Despliegue con Docker CLI

Si prefieres trabajar desde la línea de comandos:

1. Clonar el repositorio

git clone https://git.ictiberia.com/groales/uptime-kuma.git
cd uptime-kuma

2. Elegir modo de despliegue

Opción A: Traefik (recomendado para producción)

cp docker-compose.override.traefik.yml.example docker-compose.override.yml
cp .env.example .env
nano .env  # Editar: configurar DOMAIN_HOST

Opción B: Nginx Proxy Manager

# No requiere .env ni override

3. Iniciar el servicio

docker compose up -d

La inicialización tarda 10-20 segundos (creación de base de datos SQLite).

4. Verificar el despliegue

# Ver logs en tiempo real
docker compose logs -f uptime-kuma

# Verificar contenedores activos
docker compose ps

# Ver base de datos creada
docker compose exec uptime-kuma ls -lh /app/data/

Acceso:

  • Traefik: https://<DOMAIN_HOST> (ejemplo: https://uptime.example.com)
  • NPM: Configurar en NPM apuntando a uptime-kuma puerto 3001

Primera configuración: Al acceder por primera vez, Uptime Kuma te pedirá crear una cuenta de administrador.

Modos de Despliegue

Traefik (Proxy Inverso con SSL automático)

Requisitos:

  • Stack de Traefik desplegado
  • Red proxy creada
  • DNS apuntando al servidor

Configuración:

  1. Copiar archivo override:

    cp docker-compose.override.traefik.yml.example docker-compose.override.yml

  2. Configurar .env:

    cp .env.example .env
nano .env

  3. Editar DOMAIN_HOST:

    DOMAIN_HOST=uptime.example.com

  4. Desplegar:

    docker compose up -d

Acceso: https://uptime.example.com

Nginx Proxy Manager (NPM)

Requisitos:

  • NPM desplegado
  • Ambos servicios en red proxy

Configuración en NPM:

  1. Ir a Hosts → Proxy Hosts → Add Proxy Host

  2. Details:

    • Domain Names: uptime.example.com
    • Scheme: http
    • Forward Hostname/IP: uptime-kuma
    • Forward Port: 3001
    • ✅ Block Common Exploits
    • ✅ Websockets Support (⚠️ IMPORTANTE: Uptime Kuma requiere WebSockets)

  3. SSL:

    • ✅ SSL Certificate: Request a new SSL Certificate
    • ✅ Force SSL
    • ✅ HTTP/2 Support
    • ✅ HSTS Enabled

  4. Save

Acceso: https://uptime.example.com

Comparación: Traefik vs NPM

Característica Traefik Nginx Proxy Manager
Configuración Archivo .env Interfaz web
SSL Automático (Let's Encrypt) Manual (1 click)
WebSockets Automático Requiere activar checkbox
Renovación SSL Automática Automática
Complejidad Media Baja

Configuración Inicial

1. Crear cuenta administrador

Al acceder por primera vez:

  1. Ingresa username (será el usuario de login)
  2. Ingresa password (mínimo 6 caracteres)
  3. Click en Create

⚠️ IMPORTANTE: No hay usuario por defecto. El primer usuario que crees será administrador.

2. Configurar idioma

  1. Click en el icono de perfil (esquina superior derecha)
  2. Settings → Appearance
  3. Language: Selecciona Español o tu idioma preferido

3. Configurar notificaciones (recomendado)

  1. Settings → Notifications

  2. Click en Setup Notification

  3. Elige el tipo de notificación:

    Telegram:

    Discord:

    • Crear Webhook en canal de Discord
    • Pegar URL del webhook

    Email (SMTP):

    • Hostname: smtp.gmail.com (ejemplo)
    • Port: 587
    • Username: tu email
    • Password: app password
    • From Email: tu email
    • To Email: destinatario

  4. Click en Test para verificar

  5. Save

4. Habilitar autenticación 2FA (recomendado)

  1. Settings → Security
  2. Two Factor Authentication
  3. Escanear QR con app (Google Authenticator, Authy)
  4. Ingresar código de 6 dígitos
  5. Enable

Añadir Monitorización

Monitor HTTP(s)

  1. Click en Add New Monitor
  2. Monitor Type: HTTP(s)
  3. Configurar:
    • Friendly Name: Nombre descriptivo (ej: "Web Producción")
    • URL: https://example.com
    • Heartbeat Interval: 60 segundos (frecuencia de check)
    • Retries: 3 (reintentos antes de marcar como down)
    • Heartbeat Retry Interval: 60 segundos
    • Advanced:
      • Method: GET (o POST, HEAD)
      • Expected Status Code: 200-299 (códigos de éxito)
      • Keyword: Buscar palabra clave en respuesta (opcional)
  4. Notifications: Seleccionar notificaciones configuradas
  5. Save

Monitor TCP

Para monitorizar puertos (SSH, bases de datos, etc.):

  1. Monitor Type: TCP Port
  2. Configurar:
    • Friendly Name: "SSH Server"
    • Hostname: 192.168.1.100
    • Port: 22
    • Heartbeat Interval: 60 segundos
  3. Save

Monitor Ping

Para monitorizar disponibilidad de red:

  1. Monitor Type: Ping
  2. Configurar:
    • Friendly Name: "Router Principal"
    • Hostname: 192.168.1.1
    • Heartbeat Interval: 60 segundos
  3. Save

Monitor Docker Container

Para monitorizar contenedores Docker:

  1. Monitor Type: Docker Container
  2. Configurar:
    • Friendly Name: "NetBox Container"
    • Docker Daemon: unix:///var/run/docker.sock (requiere montar socket)
    • Container Name: netbox
  3. Save

⚠️ Nota: Requiere añadir volumen en docker-compose.yml:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock:ro

Monitor DNS

Para verificar resolución DNS:

  1. Monitor Type: DNS
  2. Configurar:
    • Friendly Name: "DNS Cloudflare"
    • Hostname: example.com
    • Resolver Server: 1.1.1.1
    • Resource Record Type: A
  3. Save

Status Pages (Páginas de Estado)

Crear página pública

  1. Click en Status Pages (menú lateral)
  2. Click en Add New Status Page
  3. Configurar:
    • Title: Nombre de la página (ej: "Estado de Servicios")
    • Slug: URL amigable (ej: servicios)
    • Description: Descripción opcional
    • Theme: Light/Dark
    • Custom CSS: Personalización avanzada (opcional)
  4. Add Group: Agrupar monitores (ej: "Aplicaciones", "Infraestructura")
  5. Arrastrar monitores a los grupos
  6. Save

Acceso público: https://uptime.example.com/status/servicios

Tipos de visualización

  • Default: Lista vertical con estado actual
  • List: Lista compacta
  • Badge: Badges estilo shields.io
  • Grid: Cuadrícula

Backup y Restauración

Backup Manual

Uptime Kuma usa SQLite embebida en /app/data/kuma.db.

Método 1: Copia de volumen

# Detener contenedor
docker compose stop uptime-kuma

# Copiar base de datos
docker compose cp uptime-kuma:/app/data/kuma.db ./backup/kuma-$(date +%Y%m%d).db

# Reiniciar contenedor
docker compose start uptime-kuma

Método 2: Backup en caliente (requiere Litestream - avanzado)

Instalar Litestream para backups continuos a S3/MinIO.

Backup Automático con Script

#!/bin/bash
# backup-uptime-kuma.sh

BACKUP_DIR="/backups/uptime-kuma"
RETENTION_DAYS=30

mkdir -p $BACKUP_DIR

# Backup
docker compose -f /path/to/uptime-kuma/docker-compose.yml \
  exec -T uptime-kuma \
  sqlite3 /app/data/kuma.db ".backup /app/data/kuma-backup.db"

docker compose -f /path/to/uptime-kuma/docker-compose.yml \
  cp uptime-kuma:/app/data/kuma-backup.db \
  $BACKUP_DIR/kuma-$(date +%Y%m%d-%H%M%S).db

# Limpiar backups antiguos
find $BACKUP_DIR -name "kuma-*.db" -mtime +$RETENTION_DAYS -delete

echo "Backup completado: $(date)"

Cron: Ejecutar diariamente a las 2 AM

0 2 * * * /usr/local/bin/backup-uptime-kuma.sh >> /var/log/backup-uptime-kuma.log 2>&1

Restauración

# Detener contenedor
docker compose stop uptime-kuma

# Restaurar base de datos
docker compose cp ./backup/kuma-20241205.db uptime-kuma:/app/data/kuma.db

# Reiniciar contenedor
docker compose start uptime-kuma

Actualización

Actualizar a última versión

Uptime Kuma usa versionado semántico. Tag 1 siempre apunta a la última versión 1.x.

# Backup previo
docker compose exec uptime-kuma sqlite3 /app/data/kuma.db ".backup /app/data/kuma-pre-update.db"

# Actualizar imagen
docker compose pull uptime-kuma

# Recrear contenedor
docker compose up -d uptime-kuma

# Verificar logs
docker compose logs -f uptime-kuma

Actualización automática con Watchtower

Añadir en docker-compose.yml:

services:
  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower-uptime-kuma
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_STOPPED=false
      - WATCHTOWER_MONITOR_ONLY=false
      - WATCHTOWER_SCHEDULE=0 0 4 * * *  # 4 AM diario
    command: uptime-kuma

Solución de Problemas

El contenedor no inicia

Verificar logs:

docker compose logs uptime-kuma

Problemas comunes:

  • Base de datos corrupta → Restaurar desde backup
  • Permisos en volumen → chown -R 1000:1000 /var/lib/docker/volumes/uptime-kuma_data

No se puede acceder a la interfaz

Traefik:

# Verificar labels
docker inspect uptime-kuma | grep -A 10 Labels

# Verificar red proxy
docker network inspect proxy

NPM:

  • Verificar WebSockets habilitado
  • Verificar Forward Port: 3001

Notificaciones no funcionan

Telegram:

  • Verificar bot token válido
  • Verificar chat ID correcto (debe comenzar con -)
  • Bot debe estar añadido al grupo/canal

Email:

  • Verificar SMTP port: 587 (TLS) o 465 (SSL)
  • Gmail requiere "App Password" (no contraseña de cuenta)
  • Verificar firewall no bloquea puertos SMTP

Monitores reportan "down" incorrectamente

Ajustar configuración:

  • Aumentar Heartbeat Interval (ej: de 60 a 120 segundos)
  • Aumentar Retries (ej: de 3 a 5 intentos)
  • Aumentar Heartbeat Retry Interval
  • Verificar Expected Status Code (algunos sitios usan 301/302)

Verificar desde contenedor:

# Probar conectividad desde el contenedor
docker compose exec uptime-kuma wget -O- https://example.com

# Probar DNS
docker compose exec uptime-kuma nslookup example.com

Base de datos corrupta

Síntomas: Error al iniciar, monitores desaparecen

Solución:

# Intentar reparar
docker compose exec uptime-kuma sqlite3 /app/data/kuma.db "PRAGMA integrity_check;"

# Si falla, restaurar desde backup
docker compose stop uptime-kuma
docker compose cp ./backup/kuma-latest.db uptime-kuma:/app/data/kuma.db
docker compose start uptime-kuma

Status Page no carga

  • Verificar slug correcto en URL
  • Verificar página configurada como "Public"
  • Limpiar cache del navegador (Ctrl+F5)

Variables de Entorno

Uptime Kuma tiene configuración mínima por variables de entorno (la mayoría se configura desde UI).

Variable Descripción Ejemplo Requerida
DOMAIN_HOST Dominio para Traefik uptime.example.com Sí (Traefik)

Configuración avanzada (opcional):

environment:
  - UPTIME_KUMA_PORT=3001  # Cambiar puerto (por defecto 3001)
  - UPTIME_KUMA_HOST=0.0.0.0  # Bind address

Recursos

Licencia

Este repositorio de configuración: MIT
Uptime Kuma: MIT License

Reference in New Issue View Git Blame Copy Permalink