cloudflareTunnel/README.md

# Cloudflare Tunnel → Traefik + Authentik

Configuración de Cloudflare Tunnel para exponer servicios a través de Traefik manteniendo la autenticación de Authentik.

## 🎯 Arquitectura

```
Internet → Cloudflare Tunnel → Traefik → Authentik Forward Auth → Apps
```

El wildcard `*.nucleoriofrio.com` apunta todo el tráfico a Traefik, que se encarga de:
- Enrutamiento correcto según el hostname
- Autenticación con Authentik
- Certificados SSL/TLS
- Redirecciones HTTP → HTTPS

## 📋 Requisitos previos

- Docker y Docker Compose instalados
- Cuenta de Cloudflare con dominio configurado
- Traefik corriendo en la red `principal`
- Authentik configurado con Forward Auth en Traefik
- Gitea Runner configurado (para auto-deploy con Gitea Actions)

## 🚀 Setup Rápido (Recomendado)

### Setup Automático con Script

En una PC nueva, solo necesitas clonar el repo y ejecutar el script de setup:

```bash
# Clonar el repositorio
git clone https://gitea.nucleoriofrio.com/nucleo000/cloudflareTunnel.git
cd cloudflareTunnel

# Ejecutar setup (verifica si existe el tunnel, si no lo crea)
./setup.sh
```

El script automáticamente:
1. ✅ Instala `cloudflared` si no está instalado
2. ✅ Te autentica con Cloudflare (abre el navegador)
3. ✅ Verifica si ya existe el tunnel `nucleorio-tunnel`
4. ✅ Si no existe, lo crea
5. ✅ Genera `credentials.json` y `.env`
6. ✅ Opcionalmente configura DNS automáticamente

### Levantar el servicio

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

### Verificar logs

```bash
docker-compose logs -f
```

Deberías ver:
```
INF Connection registered connIndex=0
INF Registered tunnel connection
```

---

## 🔧 Setup Manual (Alternativo)

<details>
<summary>Click para expandir instrucciones manuales</summary>

### 1. Instalar cloudflared

```bash
# Debian/Ubuntu
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb
```

### 2. Crear/Verificar el tunnel

```bash
# Login a Cloudflare
cloudflared tunnel login

# Listar tunnels existentes
cloudflared tunnel list

# Si no existe, crear uno nuevo
cloudflared tunnel create nucleorio-tunnel

# Copiar credentials
cp ~/.cloudflared/<TUNNEL_ID>.json ./credentials.json
```

### 3. Configurar .env

```bash
cp .env.example .env
nano .env  # Agregar TUNNEL_ID
```

### 4. Configurar DNS

```bash
# Opción A: Automático
cloudflared tunnel route dns <TUNNEL_ID> *.nucleoriofrio.com
cloudflared tunnel route dns <TUNNEL_ID> nucleoriofrio.com

# Opción B: Manual en dashboard de Cloudflare
# Crea registros CNAME:
# - Name: *
#   Target: <TUNNEL_ID>.cfargotunnel.com
#   Proxy: ON
```

### 5. Levantar servicio

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

</details>

## 🔧 Configuración

### config.yml

El archivo `config.yml` usa wildcard para capturar todo `*.nucleoriofrio.com` y redirigirlo a Traefik:

```yaml
ingress:
  - hostname: "*.nucleoriofrio.com"
    service: http://traefik:80
```

Traefik recibe el tráfico y:
1. Lee el `Host` header
2. Aplica las reglas de enrutamiento
3. Ejecuta Authentik Forward Auth si está configurado
4. Redirige al servicio correcto

### docker-compose.yml

El contenedor se conecta a la red `principal` para poder comunicarse con Traefik.

## 🚀 Auto-deploy con Gitea Actions

Este repositorio incluye un workflow de Gitea Actions (`.gitea/workflows/deploy.yml`) que automáticamente despliega el tunnel cuando haces push a `main`.

**¿Qué hace el workflow?**
1. Crea `.env` y `credentials.json` desde Gitea Secrets
2. Verifica que la red Docker `principal` exista (la crea si no)
3. Descarga la última imagen de `cloudflare/cloudflared`
4. Detiene el stack actual
5. Levanta el stack actualizado
6. Muestra los logs del tunnel

### Configurar Secrets en Gitea

**Paso 1: Crear el tunnel y obtener las credenciales**

En tu PC local (o donde prefieras):

```bash
# Clonar el repo
git clone https://gitea.nucleoriofrio.com/nucleo000/cloudflareTunnel.git
cd cloudflareTunnel

# Ejecutar setup para crear el tunnel
./setup.sh
```

Esto genera:
- `credentials.json` - Contiene las credenciales del tunnel
- `.env` - Contiene el TUNNEL_ID

**Paso 2: Configurar los secrets en Gitea**

Ve a tu repositorio en Gitea:
```
Settings > Secrets > Actions
```

Agrega estos **2 secrets**:

1. **`TUNNEL_ID`** (tipo: Secret)
   ```bash
   # Obtén el valor de .env
   cat .env
   # Copia el valor después de TUNNEL_ID=
   ```

2. **`TUNNEL_CREDENTIALS`** (tipo: Secret)
   ```bash
   # Copia TODO el contenido de credentials.json
   cat credentials.json
   # Debe ser un JSON válido que empiece con { y termine con }
   ```

**Paso 3: ¡Listo!**

Ahora cada `git push` a `main` desplegará automáticamente el tunnel usando los secrets configurados.

**Importante:**
- No necesitas ejecutar nada manualmente en el servidor
- Los secrets están seguros en Gitea
- `credentials.json` y `.env` NUNCA se commitean al repo (están en `.gitignore`)

## ✅ Verificación

Prueba acceder a tus servicios:

- https://amigos.nucleoriofrio.com → Debería redirigir a Authentik
- https://wifi.nucleoriofrio.com → Debería redirigir a Authentik
- https://portainer.nucleoriofrio.com → Debería redirigir a Authentik

## 🐛 Troubleshooting

### El tunnel no conecta

```bash
# Verificar logs
docker-compose logs -f

# Verificar que credentials.json existe y es válido
cat credentials.json
```

### Traefik no recibe el tráfico

```bash
# Verificar que el contenedor está en la red correcta
docker network inspect principal

# Debería aparecer 'cloudflared-tunnel' en la lista
```

### Authentik no intercepta

Verifica que Traefik tiene configurado el middleware de Authentik Forward Auth para tus servicios.

### El wildcard no funciona

Asegúrate de que:
1. El registro DNS CNAME en Cloudflare está configurado como `*` o `*.nucleoriofrio.com`
2. El proxy (nube naranja) está activado
3. El tunnel está corriendo sin errores

## 📝 Notas importantes

- **No expongas servicios directamente**: Todo debe pasar por Traefik para mantener Authentik
- **Wildcard DNS**: Con `*.nucleoriofrio.com` no necesitas reconfigurar el tunnel para nuevos subdominios
- **Multiple WAN**: Cloudflare Tunnel maneja automáticamente las reconexiones si tu conexión se cae
- **Credenciales**: Nunca commitees `credentials.json` o `.env` al repositorio

## 🔐 Seguridad

Este setup mantiene toda la seguridad de Authentik porque:
- El tunnel termina en Traefik, no en las apps
- Traefik aplica Forward Auth antes de permitir acceso
- Las apps nunca están expuestas directamente a Internet

## 📚 Referencias

- [Cloudflare Tunnel Docs](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)
- [Wildcard DNS](https://developers.cloudflare.com/dns/manage-dns-records/reference/wildcard-dns-records/)