traefikNucleo/README.md

Traefik Nucleo - Reverse Proxy Configuration

Configuración de Traefik v3.5 para el servidor Nucleo002.

📁 Estructura del Proyecto

traefikNucleo/
├── docker-compose.yml          # Configuración principal de Traefik
├── traefik/
│   └── traefik.yml            # Configuración estática
├── dynamic/
│   └── middlewares.yml        # Middlewares (security, cors, etc.)
├── examples/
│   ├── whoami-service.yml     # Ejemplo de servicio nuevo
│   └── existing-service.yml   # Ejemplo para servicios existentes
└── README.md                  # Este archivo

🚀 Inicio Rápido

1. Configuración inicial

Antes de iniciar, DEBES CAMBIAR:

1. Email en traefik/traefik.yml (línea 43):

   email: TU-EMAIL@AQUI.com  # Para Let's Encrypt
   

2. Dominio del dashboard en docker-compose.yml (línea 47):

   - "traefik.http.routers.dashboard.rule=Host(`traefik.TU-DOMINIO.com`)"
   

3. Contraseña del dashboard (línea 54):

   # Generar hash de contraseña:
   htpasswd -nb admin tu-password-seguro
   
   # Reemplazar en docker-compose.yml:
   - "traefik.http.middlewares.dashboard-auth.basicauth.users=HASH-AQUI"
   

2. Iniciar Traefik

# Desde el directorio traefikNucleo/
docker compose up -d

# Ver logs
docker compose logs -f traefik

# Verificar que está corriendo
docker ps | grep traefik

3. Acceder al Dashboard

Después de configurar el DNS de tu dominio:

https://traefik.TU-DOMINIO.com

Usuario: admin Password: la que configuraste

📋 Conectar Servicios Existentes a Traefik

Opción A: Via labels en docker-compose.yml

Edita el docker-compose.yml de tu servicio y agrega:

services:
  tu-servicio:
    # ... configuración existente ...

    networks:
      - tu-red-original
      - traefik-network  # ← AGREGAR ESTO

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.NOMBRE.rule=Host(`DOMINIO.com`)"
      - "traefik.http.routers.NOMBRE.entrypoints=websecure"
      - "traefik.http.routers.NOMBRE.tls.certresolver=letsencrypt"
      - "traefik.http.services.NOMBRE.loadbalancer.server.port=PUERTO"

networks:
  traefik-network:
    external: true

Luego:

docker compose up -d

Opción B: Conectar contenedor corriendo (sin reiniciar)

# 1. Conectar a la red de Traefik
docker network connect traefik-network nombre-del-contenedor

# 2. Agregar labels dinámicamente
docker update \
  --label traefik.enable=true \
  --label traefik.http.routers.NOMBRE.rule='Host(`DOMINIO.com`)' \
  --label traefik.http.routers.NOMBRE.entrypoints=websecure \
  --label traefik.http.routers.NOMBRE.tls.certresolver=letsencrypt \
  --label traefik.http.services.NOMBRE.loadbalancer.server.port=PUERTO \
  nombre-del-contenedor

# 3. Reiniciar el contenedor para aplicar labels
docker restart nombre-del-contenedor

🔧 Comandos Útiles

Gestión de Traefik

# Ver logs en tiempo real
docker compose logs -f traefik

# Reiniciar Traefik (recargar configuración)
docker compose restart traefik

# Detener Traefik
docker compose down

# Detener y eliminar volúmenes (CUIDADO: borra certificados SSL)
docker compose down -v

Ver configuración activa

# Ver todos los routers activos
docker exec traefik traefik healthcheck

# Inspeccionar contenedor de Traefik
docker inspect traefik

Gestión de certificados

# Ver certificados almacenados
docker volume inspect traefik-letsencrypt

# Backup de certificados
docker run --rm -v traefik-letsencrypt:/data -v $(pwd):/backup \
  alpine tar czf /backup/letsencrypt-backup.tar.gz /data

🌐 Ejemplos de Servicios

Servicio de prueba (whoami)

cd examples/
docker compose -f whoami-service.yml up -d

Accede a: https://whoami.TU-DOMINIO.com

Tus servicios existentes

Ver archivo examples/existing-service.yml para plantilla.

Servicios actuales que puedes migrar:

• ✅ gitea (puerto 3000)
• ✅ portainer (puerto 9443)
• ✅ authentik (puertos 9100, 9444)
• ✅ openwebui (puerto 3020)
• ✅ snatchgame-client (puerto 3010)
• ✅ planilla-ui (puerto 3008)
• Y más...

🔐 SSL/TLS Automático

Traefik solicita automáticamente certificados SSL de Let's Encrypt cuando:

1. El dominio apunta a tu IP pública
2. Los puertos 80 y 443 están accesibles desde internet
3. El contenedor tiene tls.certresolver=letsencrypt en sus labels

Troubleshooting SSL

Si los certificados no se generan:

# Ver logs de ACME (Let's Encrypt)
docker compose logs traefik | grep acme

# Verificar que el dominio apunta a tu IP
dig TU-DOMINIO.com

# Verificar conectividad externa
curl -I http://TU-DOMINIO.com

📊 Middlewares Disponibles

Los middlewares procesan las peticiones antes de llegar al servicio.

Usa los middlewares agregándolos a tus labels:

labels:
  - "traefik.http.routers.NOMBRE.middlewares=compress,security-headers,rate-limit"

Middlewares configurados:

• compress: Compresión gzip
• security-headers: Headers de seguridad HTTP
• cors: Configuración CORS
• rate-limit: Límite de peticiones (100/s)
• redirect-https: Redirección forzada a HTTPS
• basic-auth-example: Autenticación básica
• strip-prefix-api: Remover /api del path

Ver dynamic/middlewares.yml para detalles.

🛠️ Personalización Avanzada

Agregar más entry points

Edita traefik/traefik.yml:

entryPoints:
  custom-port:
    address: ":9000"

Expón el puerto en docker-compose.yml:

ports:
  - "9000:9000"

Configuración TCP/UDP

Para servicios que no son HTTP (como bases de datos, SSH, etc.):

Edita traefik/traefik.yml y agrega entry points TCP:

entryPoints:
  postgres:
    address: ":5432"

Y configura routers TCP en dynamic/tcp.yml (crear archivo nuevo).

📈 Monitoreo

Métricas Prometheus

Traefik expone métricas en:

http://IP-SERVIDOR:8082/metrics

Dashboard

Acceso web completo a:

• Routers activos
• Services
• Middlewares
• Certificados TLS
• Estadísticas en tiempo real

⚠️ Notas Importantes

1. Puertos 80 y 443 deben estar libres antes de iniciar Traefik
2. Firewall: Asegúrate de que los puertos están abiertos en tu firewall
3. DNS: Los dominios deben apuntar a la IP de tu servidor
4. Backup: Haz backup regular del volumen traefik-letsencrypt
5. Let's Encrypt rate limits: Máximo 5 certificados duplicados por semana

🆘 Solución de Problemas

Traefik no inicia

# Ver logs detallados
docker compose logs traefik

# Verificar puertos ocupados
ss -tuln | grep ':80\|:443'

# Verificar permisos del socket de Docker
ls -la /var/run/docker.sock

Servicio no aparece en el dashboard

# Verificar que el contenedor está en la red correcta
docker inspect CONTENEDOR | grep -A 10 Networks

# Verificar labels
docker inspect CONTENEDOR | grep -A 20 Labels

# Ver logs de Traefik para errores
docker compose logs traefik | grep error

Certificado SSL no se genera

1. Verifica que el dominio resuelve: dig TU-DOMINIO.com
2. Verifica conectividad: curl http://TU-DOMINIO.com
3. Revisa logs de ACME: docker compose logs traefik | grep acme
4. Espera unos minutos (Let's Encrypt puede tardar)

📚 Recursos

• Documentación oficial de Traefik
• Traefik en GitHub
• Let's Encrypt

🔄 Migración desde Nginx Proxy Manager

Si vienes de NPM:

1. Exporta/documenta tus configuraciones de NPM
2. Detén NPM: docker stop npm npm-db
3. Inicia Traefik: docker compose up -d
4. Migra servicios uno por uno usando los ejemplos
5. Cuando todo funcione, elimina NPM si quieres

🎯 Próximos Pasos

1. Cambiar email, dominio y password en la configuración
2. Iniciar Traefik
3. Probar con servicio whoami
4. Migrar un servicio existente
5. Configurar backups de certificados SSL
6. Conectar métricas a Prometheus/Grafana (opcional)

---

Creado para: Servidor Nucleo002 Fecha: Octubre 2025 Versión de Traefik: v3.5