homelab-optimized/docs/infrastructure/cloudflare-tunnels-setup.md

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

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)

# 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 for protecting tunneled services with SSO.