Sanitized mirror from private repository - 2026-04-19 08:15:48 UTC

2026-04-19 08:15:48 +00:00
commit 57b1fe47f2
1437 changed files with 363051 additions and 0 deletions
--- a/docs/infrastructure/cloudflare-tunnels-setup.md
+++ b/docs/infrastructure/cloudflare-tunnels-setup.md
@@ -0,0 +1,145 @@
+# 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.