# Cloudflare Tunnels Setup Guide

Step-by-step guide to create and configure Cloudflare Tunnels for the homelab.

## Prerequisites

- Cloudflare account with Zero Trust enabled (free tier works)
- Access to [Cloudflare Zero Trust Dashboard](https://one.dash.cloudflare.com/)

## Creating a Tunnel

### Step 1: Access Zero Trust Dashboard

1. Go to https://one.dash.cloudflare.com/
2. Select your account
3. Navigate to: **Networks** → **Tunnels**

### Step 2: Create New Tunnel

1. Click **Create a tunnel**
2. Select **Cloudflared** as the connector type
3. Click **Next**

### Step 3: Name Your Tunnel

- For Atlantis: `atlantis-tunnel`
- For Homelab-VM: `homelab-vm-tunnel`

### Step 4: Install Connector

1. You'll see a tunnel token (starts with `eyJ...`)
2. **Copy this token** - you'll need it for the Docker container
3. The token is your `TUNNEL_TOKEN` environment variable

### Step 5: Add Public Hostnames

Click **Add a public hostname** for each service:

#### Atlantis Tunnel Hostnames

| Subdomain | Domain | Path | Type | URL |
|-----------|--------|------|------|-----|
| pw | vish.gg | | HTTP | localhost:4080 |
| cal | vish.gg | | HTTP | localhost:12852 |
| meet | thevish.io | | HTTPS | localhost:5443 |
| joplin | thevish.io | | HTTP | localhost:22300 |
| mastodon | vish.gg | | HTTP | 192.168.0.154:3000 |
| matrix | thevish.io | | HTTP | 192.168.0.154:8081 |
| mx | vish.gg | | HTTP | 192.168.0.154:8082 |
| mm | crista.love | | HTTP | 192.168.0.154:8065 |

#### Homelab-VM Tunnel Hostnames

| Subdomain | Domain | Path | Type | URL |
|-----------|--------|------|------|-----|
| gf | vish.gg | | HTTP | localhost:3300 |
| ntfy | vish.gg | | HTTP | localhost:8081 |
| hoarder | thevish.io | | HTTP | localhost:3000 |
| binterest | thevish.io | | HTTP | localhost:21544 |

### Step 6: Configure Additional Settings (Optional)

For each hostname, you can configure:

- **TLS Settings**: Usually leave as default
- **HTTP Settings**: 
  - Enable "No TLS Verify" if backend uses self-signed cert
  - Set HTTP Host Header if needed
- **Access**: Add Cloudflare Access policies (see Authentik integration)

### Step 7: Save and Deploy

1. Click **Save tunnel**
2. Deploy the Docker container with your token

## Docker Deployment

### Atlantis (Synology)

```yaml
# Deploy via Portainer with environment variable:
# TUNNEL_TOKEN=eyJ...your-token-here...

version: '3.8'
services:
  cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: cloudflare-tunnel
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    network_mode: host
```

### Homelab-VM

Same configuration, different token for the homelab-vm tunnel.

## Verifying Tunnel Status

1. In Cloudflare Dashboard → Tunnels
2. Your tunnel should show **Healthy** status
3. Test each hostname in a browser

## DNS Changes

When tunnels are active, Cloudflare automatically manages DNS.
The DNS records will show as CNAME pointing to your tunnel.

**Before tunnel:**
```
pw.vish.gg → A → YOUR_WAN_IP
```

**After tunnel:**
```
pw.vish.gg → CNAME → <tunnel-id>.cfargotunnel.com
```

## Troubleshooting

### Tunnel Shows "Down"
- Check container is running: `docker ps | grep cloudflare`
- Check logs: `docker logs cloudflare-tunnel`
- Verify token is correct

### 502 Bad Gateway
- Backend service not running
- Wrong port number
- Network mode issue (try `network_mode: host`)

### SSL Errors
- Enable "No TLS Verify" for self-signed certs
- Or use HTTP instead of HTTPS for backend

## Security Considerations

- Tunnel token is sensitive - store securely
- Use Cloudflare Access for additional authentication
- Consider IP allowlists for sensitive services

## Integration with Authentik

See [Authentik SSO Guide](./authentik-sso.md) for protecting tunneled services with SSO.