Cómo instalar Kuvasz en Docker- Monitoreo de uptime y SSL en Docker

Kuvasz | Uptime Monitoring | Docker

Kuvasz: Monitoreo de uptime y SSL autohospedado en Docker

Monitorea la disponibilidad de tus sitios, APIs y certificados SSL. Notificaciones en tiempo real, páginas de estado públicas y API REST completa. Alternativa open source a Pingdom y StatusCake.

¿Qué es Kuvasz?

Kuvasz es un servicio de monitoreo de uptime y SSL open source construido en Kotlin. Monitorea la disponibilidad de tus sitios web, APIs y servicios, verifica el estado de tus certificados SSL, y te notifica en tiempo real cuando algo falla. Es una alternativa autohospedada, gratuita y de código abierto a servicios comerciales como Pingdom, StatusCake o UptimeRobot.

El nombre "Kuvasz" viene de una antigua raza húngara de perros guardianes, lo cual es perfecto: Kuvasz es como un perro guardián para tu infraestructura, vigilando 24/7 que todos tus servicios sigan funcionando. Con monitoreo HTTP(S), verificación de certificados SSL, notificaciones en múltiples canales (Email, Slack, Discord, Telegram), y páginas de estado públicas para mantener a tus usuarios informados.

Controla tu monitoreo: No depende de servicios externos. Tus datos de monitoreo están en tu servidor. Sin limites de monitores, sin comisiones por alertas, sin restricciones artificiales.

Características principales

Monitoreo HTTP(S)

Controla disponibilidad de sitios web, APIs y servicios con peticiones HTTP configurables.

Monitoreo SSL

Verifica certificados SSL diariamente. Alertas antes de que expiren.

Monitores push (cron/heartbeat)

Monitorea trabajos cron, backups y tareas programadas con heartbeat.

Notificaciones multi-canal

Email, Slack, Discord, Telegram, PagerDuty. Configurable por monitor.

Páginas de estado

Crea páginas públicas o privadas para mantener usuarios/equipo informados.

API REST completa

Gestiona monitores y obtén datos via API documentada.

Monitoreo geo-distribuido

Deploy múltiples instancias para monitorear desde diferentes ubicaciones.

Integración Prometheus

Exporta métricas a Prometheus y OpenTelemetry.

IaC con YAML

Configura monitores via archivo YAML para reproducibilidad.

Interfaz moderna

UI responsive con modo oscuro, accesible desde desktop y móvil.

Headers y body personalizados

Configura headers HTTP, JSON body y status codes esperados.

Open Source

100% código abierto bajo Apache 2.0. Completamente auditable.

Requisitos del sistema

• Docker y Docker Compose instalados
• PostgreSQL 12+ (en contenedor)
• 512 MB de RAM mínimo (1+ GB recomendado)
• 100 MB de espacio en disco mínimo
• Puerto 8080 disponible (configurable)
• Opcional: servidor SMTP para notificaciones por email

Instalación rápida

Opción 1: Docker Run (30 segundos)

docker run -d \ --name kuvasz \ -p 8080:8080 \ kuvaszmonitoring/kuvasz:latest

Opción 2: Docker Compose (recomendado)

version: '3.8' services: postgres: image: postgres:16 container_name: kuvasz-postgres environment: - POSTGRES_DB=kuvasz - POSTGRES_USER=kuvasz - POSTGRES_PASSWORD=kuvasz-password volumes: - postgres-data:/var/lib/postgresql/data restart: unless-stopped kuvasz: image: kuvaszmonitoring/kuvasz:latest container_name: kuvasz depends_on: - postgres ports: - "8080:8080" environment: - DATASOURCE_URL=jdbc:postgresql://postgres:5432/kuvasz - DATASOURCE_USERNAME=kuvasz - DATASOURCE_PASSWORD=kuvasz-password - TZ=Europe/Madrid restart: unless-stopped volumes: postgres-data:

docker compose up -d

Accede a http://localhost:8080 y comienza a crear monitores.

Crear tu primer monitor

Monitor HTTP básico

1. Abre http://localhost:8080 en tu navegador
2. Haz clic en Create Monitor
3. Configura:
   • Name: Mi sitio web
   • URL: https://midominio.com
   • Method: GET
   • Check interval: 60 segundos
   • Expected status code: 200
4. Haz clic en Save

Monitor SSL

1. Ve a Monitors → New Monitor
2. Selecciona SSL Monitor
3. Introduce el hostname: midominio.com
4. Puerto: 443 (por defecto)
5. Alert threshold: 30 días (antes de expirar)

Monitor push (heartbeat)

1. Crea un Push Monitor
2. Kuvasz genera una URL única
3. En tu cron job: curl https://kuvasz.tudominio.com/api/push/{monitor_id}
4. Si no llama en el timeout, Kuvasz alerta

Configurar notificaciones

Email (SMTP)

MAIL_SMTP_HOST=smtp.gmail.com MAIL_SMTP_PORT=587 MAIL_SMTP_USERNAME=tu-email@gmail.com MAIL_SMTP_PASSWORD=tu-app-password MAIL_SMTP_FROM_ADDRESS=alerts@kuvasz.tudominio.com

Slack

1. Crea una aplicación Slack en tu workspace
2. Genera un Webhook URL
3. En Kuvasz, ve a Integrations → Add
4. Selecciona Slack y pega el Webhook
5. Asigna a cada monitor

Discord

1. En Discord, crea un Webhook en tu canal
2. Copia la URL
3. En Kuvasz, crea integración Discord

Configurar monitores con YAML (IaC)

Kuvasz soporta Infrastructure as Code con YAML:

monitors: - name: API principal url: https://api.tudominio.com/health type: HTTP checkInterval: 30 expectedStatusCode: 200 - name: SSL tudominio.com type: SSL hostname: tudominio.com port: 443 alertThresholdDays: 30

Crear página de estado pública

1. Ve a Status Pages → Create
2. Configura:
   • Name: Status page
   • Path: /status
   • Public: True
   • Selecciona monitores: Los que quieras mostrar
3. La página se actualiza automáticamente

Tip: Usa páginas privadas para tu equipo y públicas para clientes.

Configurar HTTPS con Caddy

kuvasz.tudominio.com { reverse_proxy localhost:8080 }

Caddy genera automáticamente certificados Let's Encrypt.

Monitoreo avanzado

Headers personalizados

Configura headers HTTP para cada monitor:

Authorization: Bearer token-aqui User-Agent: Kuvasz-Monitor/1.0

Body JSON personalizado

Envía payload JSON en monitores POST/PUT:

{ "action": "health_check", "timestamp": "2025-05-07" }

Validación de respuesta

• Status code esperado: 200, 201, etc.
• Timeout: Configurable en segundos
• Palabra clave en respuesta: Busca texto en el body

Gestión y mantenimiento

Ver logs

docker compose logs -f kuvasz

Reiniciar Kuvasz

docker compose restart kuvasz

Detener todo

docker compose down

Backup de base de datos

docker compose exec postgres \ pg_dump -U kuvasz kuvasz > backup-$(date +%Y%m%d).sql

Actualizar a la última versión

docker compose pull docker compose up -d

Usar API REST

# Listar todos los monitores curl -s http://localhost:8080/api/v2/monitors | jq # Obtener eventos de un monitor curl -s http://localhost:8080/api/v2/monitors/{id}/events | jq

Casos de uso

• Hosting/ISP: Monitoreo de uptime para clientes con páginas de estado
• SaaS: Alertas internas de disponibilidad de servicios
• Agencias: Monitoreo de sitios de múltiples clientes en una sola instancia
• Empresas: Monitoreo interno de APIs y servicios
• Freelancers: Notificaciones de fallos en sus propios proyectos
• DevOps: Integración con Prometheus y alertas automáticas
• E-commerce: Monitoreo de checkout, APIs de pagos, SSL certificates

---

Referencias oficiales

• Kuvasz Official Website
• Repositorio oficial - GitHub
• Imagen Docker - Docker Hub
• Demo en vivo
• Documentación oficial

Apoya el canal GENBYTE

Suscríbete al canal de YouTube Suscríbete a la newsletter semanal Invítame a un Ko-fi genbyte@proton.me

Sígueme en mis redes sociales

Telegram Discord YouTube GitHub Blog Twitter