# 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**:
   ```env
   DOMAIN_HOST=uptime.example.com
   ```

   **Para NPM**: No requiere variables

5. En **Advanced mode**, añadir (solo Traefik):
   ```yaml
   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

```bash
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)

```bash
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

```bash
# No requiere .env ni override
```

### 3. Iniciar el servicio

```bash
docker compose up -d
```

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

### 4. Verificar el despliegue

```bash
# 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:
   ```bash
   cp docker-compose.override.traefik.yml.example docker-compose.override.yml
   ```

2. Configurar `.env`:
   ```bash
   cp .env.example .env
   nano .env
   ```

3. Editar `DOMAIN_HOST`:
   ```env
   DOMAIN_HOST=uptime.example.com
   ```

4. Desplegar:
   ```bash
   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**:
   - Obtener bot token de [@BotFather](https://t.me/botfather)
   - Obtener Chat ID de [@userinfobot](https://t.me/userinfobot)
   - Pegar ambos en Uptime Kuma

   **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`:
```yaml
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**

```bash
# 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

```bash
#!/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
```cron
0 2 * * * /usr/local/bin/backup-uptime-kuma.sh >> /var/log/backup-uptime-kuma.log 2>&1
```

### Restauración

```bash
# 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.

```bash
# 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`:

```yaml
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**:
```bash
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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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):

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

---

## Recursos

- 📖 [Documentación oficial](https://github.com/louislam/uptime-kuma/wiki)
- 🐛 [Reportar problemas](https://github.com/louislam/uptime-kuma/issues)
- 💬 [Comunidad Discord](https://discord.gg/uptime-kuma)
- 🐳 [Docker Hub](https://hub.docker.com/r/louislam/uptime-kuma)

---

## Licencia

Este repositorio de configuración: MIT  
Uptime Kuma: [MIT License](https://github.com/louislam/uptime-kuma/blob/master/LICENSE)