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):
   ```yaml
   email: TU-EMAIL@AQUI.com  # Para Let's Encrypt
   ```

2. **Dominio del dashboard en `docker-compose.yml`** (línea 47):
   ```yaml
   - "traefik.http.routers.dashboard.rule=Host(`traefik.TU-DOMINIO.com`)"
   ```

3. **Contraseña del dashboard** (línea 54):
   ```bash
   # 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

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

```yaml
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:
```bash
docker compose up -d
```

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

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

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

```bash
# Ver todos los routers activos
docker exec traefik traefik healthcheck

# Inspeccionar contenedor de Traefik
docker inspect traefik
```

### Gestión de certificados

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

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

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

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

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

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

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

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

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

```bash
# 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](https://doc.traefik.io/traefik/)
- [Traefik en GitHub](https://github.com/traefik/traefik)
- [Let's Encrypt](https://letsencrypt.org/)

## 🔄 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