Table of Contents
- Despliegue con Traefik
- Requisitos Previos
- Configuración
- 1. Preparar archivos
- 2. Configurar variables de entorno
- 3. Verificar configuración
- 4. Desplegar
- 5. Verificar despliegue
- 6. Acceder
- Labels de Traefik Explicados
- WebSockets
- Solución de Problemas
- Error 502 Bad Gateway
- Certificado SSL no se genera
- Uptime Kuma no actualiza en tiempo real
- DOMAIN_HOST no se resuelve
- Configuración Avanzada
- Múltiples dominios
- Forzar HTTPS (redirigir HTTP → HTTPS)
- Restringir acceso por IP
- Autenticación básica (antes de login de Uptime Kuma)
- Siguiente Paso
Despliegue con Traefik
Esta guía explica cómo desplegar Uptime Kuma usando Traefik como proxy inverso con SSL automático mediante Let's Encrypt.
Requisitos Previos
- ✅ Stack de Traefik desplegado y funcionando
- ✅ Red Docker
proxycreada externamente - ✅ DNS configurado apuntando a tu servidor (ejemplo:
uptime.example.com) - ✅ Puertos 80 y 443 accesibles desde Internet
Configuración
1. Preparar archivos
cd uptime-kuma
cp docker-compose.override.traefik.yml.example docker-compose.override.yml
cp .env.example .env
2. Configurar variables de entorno
Edita .env:
nano .env
Contenido:
DOMAIN_HOST=uptime.example.com
Reemplaza uptime.example.com con tu dominio real.
3. Verificar configuración
docker-compose.override.yml:
services:
uptime-kuma:
labels:
- traefik.enable=true
- traefik.http.routers.uptime-kuma.rule=Host(`${DOMAIN_HOST}`)
- traefik.http.routers.uptime-kuma.entrypoints=websecure
- traefik.http.routers.uptime-kuma.tls.certresolver=letsencrypt
- traefik.http.services.uptime-kuma.loadbalancer.server.port=3001
Importante: Uptime Kuma escucha en puerto 3001 (no 80).
4. Desplegar
docker compose up -d
5. Verificar despliegue
# Ver logs
docker compose logs -f uptime-kuma
# Verificar contenedor activo
docker compose ps
# Verificar red proxy
docker network inspect proxy | grep uptime-kuma
Salida esperada (logs):
uptime-kuma | ✅ Server is ready
uptime-kuma | Listening on http://0.0.0.0:3001
6. Acceder
Navega a: https://uptime.example.com
En el primer acceso, Uptime Kuma te pedirá crear una cuenta de administrador.
Labels de Traefik Explicados
| Label | Descripción |
|---|---|
traefik.enable=true |
Habilita Traefik para este contenedor |
traefik.http.routers.uptime-kuma.rule=Host(...) |
Regla de enrutamiento por dominio |
traefik.http.routers.uptime-kuma.entrypoints=websecure |
Usa entrypoint HTTPS (443) |
traefik.http.routers.uptime-kuma.tls.certresolver=letsencrypt |
Genera certificado SSL automático |
traefik.http.services.uptime-kuma.loadbalancer.server.port=3001 |
Puerto del contenedor (⚠️ 3001, no 80) |
WebSockets
Uptime Kuma requiere WebSockets para actualizar datos en tiempo real.
Traefik soporta WebSockets automáticamente sin configuración adicional.
Solución de Problemas
Error 502 Bad Gateway
Causa: Traefik no puede conectar al contenedor.
Solución:
# Verificar que el contenedor está en la red proxy
docker network inspect proxy | grep uptime-kuma
# Verificar puerto correcto en labels
docker inspect uptime-kuma | grep "loadbalancer.server.port"
# Debe mostrar: 3001
Certificado SSL no se genera
Causa: DNS no apunta al servidor o puerto 80/443 bloqueado.
Verificar DNS:
nslookup uptime.example.com
# Debe devolver la IP de tu servidor
Verificar Traefik:
docker logs traefik | grep uptime-kuma
Solución:
- Asegurar que DNS apunta correctamente
- Verificar firewall permite puertos 80 y 443
- Revisar logs de Traefik para errores de Let's Encrypt
Uptime Kuma no actualiza en tiempo real
Causa: WebSockets bloqueados (raro en Traefik).
Verificar en navegador (consola F12):
WebSocket connection to 'wss://uptime.example.com/socket.io/...' failed
Solución: Traefik soporta WebSockets automáticamente, pero si hay problemas:
# NO necesario normalmente, pero si hay issues:
labels:
- traefik.http.middlewares.uptime-ws.headers.customrequestheaders.Connection=Upgrade
- traefik.http.middlewares.uptime-ws.headers.customrequestheaders.Upgrade=websocket
- traefik.http.routers.uptime-kuma.middlewares=uptime-ws
DOMAIN_HOST no se resuelve
Causa: Variable no se exporta correctamente.
Verificar:
docker inspect uptime-kuma | grep "traefik.http.routers.uptime-kuma.rule"
Debe mostrar:
Host(`uptime.example.com`)
Si muestra Host(${DOMAIN_HOST}), el .env no se cargó.
Solución:
# Recrear stack
docker compose down
docker compose up -d
Configuración Avanzada
Múltiples dominios
labels:
- traefik.http.routers.uptime-kuma.rule=Host(`uptime.example.com`) || Host(`status.example.com`)
Forzar HTTPS (redirigir HTTP → HTTPS)
Traefik ya lo hace automáticamente con websecure entrypoint.
Restringir acceso por IP
labels:
- traefik.http.middlewares.uptime-whitelist.ipwhitelist.sourcerange=192.168.1.0/24,10.0.0.0/8
- traefik.http.routers.uptime-kuma.middlewares=uptime-whitelist
Autenticación básica (antes de login de Uptime Kuma)
# Generar usuario/password
htpasswd -nb admin password
# Salida: admin:$apr1$...
labels:
- traefik.http.middlewares.uptime-auth.basicauth.users=admin:$$apr1$$...
- traefik.http.routers.uptime-kuma.middlewares=uptime-auth
⚠️ Nota: Escapa $ con $$ en docker-compose.yml.
Siguiente Paso
Continúa con Configuración Inicial para crear tu cuenta administrador y configurar notificaciones.