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. Verifica que existan `credentials.json` y `.env`
2. Descarga la última imagen de `cloudflare/cloudflared`
3. Detiene el stack actual
4. Levanta el stack actualizado
5. Muestra los logs del tunnel

**Setup inicial en el servidor:**

En el servidor donde corre el gitea-runner, ejecuta el setup una sola vez:

```bash
# El gitea-runner clonará el repo automáticamente
# Solo necesitas ejecutar setup.sh la primera vez
cd /ruta/donde/runner/clona/el/repo
./setup.sh
```

Una vez configurado, cada `git push` actualizará automáticamente el tunnel.

**Nota**: `credentials.json` y `.env` se generan localmente y NO se commitean al repo (están en `.gitignore`), por seguridad.

## ✅ 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/)