Cloudflare Tunnel Setup

☁️ Cloudflare Tunnel Setup

Expose your media services securely to the internet without opening ports, using Cloudflare Tunnel.

---

Overview

Cloudflare Tunnel creates an encrypted connection from your server to Cloudflare's edge network, allowing external access without exposing ports to the internet.

Benefits

Feature	Description
🔒 No Port Forwarding	No inbound firewall rules needed
🌐 Global CDN	Cloudflare's worldwide network
🛡️ DDoS Protection	Built-in protection
📧 Email Auth	Optional Cloudflare Access protection
🔐 Zero Trust	Verify before connecting

---

Prerequisites

1. Cloudflare Account - Sign up free
2. Domain on Cloudflare - DNS managed by Cloudflare
3. API Token - With required permissions

---

🔑 Creating an API Token

Required Permissions

Permission	Scope	Purpose
Account:Account Settings:Read	All Accounts	Read account info
Account:Cloudflare Tunnel:Edit	All Accounts	Create/manage tunnels
Zone:DNS:Edit	All Zones	Create DNS records
Account:Zero Trust:Edit	All Accounts	VPN & Device Setup
Account:Access: Apps and Policies:Edit	All Accounts	Emails & Policies

Steps

1. Go to Cloudflare API Tokens
2. Click Create Token
3. Click Create Custom Token
4. Configure permissions as above
5. Click Continue to summary → Create Token
6. Copy the token (shown only once!)

---

🚀 Automated Setup (Recommended)

easiarr provides a fully automated Cloudflare Tunnel setup wizard.

Launch the Wizard

1. Run easiarr:

   bunx @muhammedaksam/easiarr

2. From the main menu, select:

   ☁️ Cloudflare Tunnel
   

3. Paste your API token when prompted

What the Wizard Does

1. ✅ Verifies token permissions
2. ✅ Fetches your Cloudflare zones (domains)
3. ✅ Creates a new tunnel named easiarr-{domain}
4. ✅ Configures ingress rules for all enabled apps
5. ✅ Creates DNS CNAME records for each app
6. ✅ Configures Zero Trust VPN (optional private network access)
7. ✅ Sets up Device Enrollment (if email provided)
8. ✅ Optionally sets up Cloudflare Access with email authentication
9. ✅ Saves tunnel token to .env
10. ✅ Adds cloudflared to your Docker Compose

---

🛡️ Zero Trust VPN (WARP)

easiarr enables you to access your entire private network securely from anywhere using the Cloudflare WARP client, without exposing any ports.

How It Works

1. Tunnel Route: easiarr adds a private network route (e.g., 192.168.1.0/24) to your tunnel.
2. Device Enrollment: easiarr creates a policy allowing you to enroll your devices into your Zero Trust organization.
3. WARP Client: You connect via the WARP client on your phone/laptop.
4. Result: You can access local IPs (e.g., http://192.168.1.50:8080) directly from anywhere, as if you were home.

Setting Up Clients

1. Install Cloudflare WARP on your device (Download).
2. Go to Settings → Account → Login with Cloudflare Zero Trust.
3. Enter your organization name (usually your Cloudflare account name, check One Dash).
4. Login with your email (must be one of the allowed emails from setup).
5. Connect!

---

📧 Cloudflare Access (Optional)

Protect your services with email-based authentication:

How It Works

User visits app.example.com
    → Cloudflare prompts for email
    → User receives login code
    → Verified users access the service

Setup

When running the Cloudflare Tunnel wizard:

1. Select Yes when asked about Cloudflare Access
2. Enter authorized email addresses (comma-separated)
3. Access policies are automatically created

Managing Access

1. Go to Cloudflare Zero Trust
2. Navigate to Access → Applications
3. Add/remove email addresses as needed

---

🔧 Manual Setup

If you prefer manual setup:

1. Create Tunnel

# Install cloudflared
brew install cloudflared  # macOS
# or download from https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation/

# Login to Cloudflare
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create easiarr

# Note the tunnel ID (UUID)

2. Configure Tunnel

Create ~/.cloudflared/config.yml:

tunnel: YOUR_TUNNEL_ID
credentials-file: /root/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: radarr.example.com
    service: http://traefik:80
  - hostname: sonarr.example.com
    service: http://traefik:80
  - hostname: jellyfin.example.com
    service: http://traefik:80
  # Add other services...
  - service: http_status:404

3. Create DNS Records

For each hostname, create a CNAME:

radarr.example.com → YOUR_TUNNEL_ID.cfargotunnel.com

4. Run Tunnel

cloudflared tunnel run easiarr

Or via Docker (easiarr handles this):

cloudflared:
  image: cloudflare/cloudflared:latest
  command: tunnel run
  environment:
    TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}

---

🔀 Architecture

┌──────────────────────────────────────────────────────────┐
│                        Internet                           │
└──────────────────────────────────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│               Cloudflare Edge Network                     │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐     │
│  │ DDoS Shield │   │    CDN      │   │   Access    │     │
│  └─────────────┘   └─────────────┘   └─────────────┘     │
└──────────────────────────────────────────────────────────┘
                           │
                    Encrypted Tunnel
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│                     Your Server                           │
│  ┌─────────────┐                                         │
│  │ Cloudflared │ ──► Traefik ──► Services               │
│  └─────────────┘                                         │
└──────────────────────────────────────────────────────────┘

---

🌐 Ingress Rules

easiarr configures ingress rules for all enabled apps:

Subdomain	Service
radarr.example.com	Radarr
sonarr.example.com	Sonarr
jellyfin.example.com	Jellyfin
homepage.example.com	Homepage
...	...

Catch-All

The last rule should be a catch-all 404:

- service: http_status:404

---

🔒 Security Considerations

Recommended Settings

1. Enable Cloudflare Access for sensitive services
2. Use Traefik authentication as backup
3. Disable direct port exposure on your firewall
4. Monitor Cloudflare analytics for unusual traffic

Basic Auth Fallback

If Cloudflare Access is not enabled, easiarr configures Traefik basic authentication using your GLOBAL_USERNAME and GLOBAL_PASSWORD.

---

🔧 Troubleshooting

Token Permission Errors

Error: No Cloudflare accounts found for this API token

Fix: Ensure token has Account:Account Settings:Read permission.

Tunnel Not Connecting

1. Check cloudflared logs:

   docker logs cloudflared

2. Verify tunnel token is correct
3. Test network connectivity

DNS Records Not Working

1. Verify CNAME exists in Cloudflare DNS
2. Wait for DNS propagation (up to 5 minutes)
3. Check Cloudflare proxy status (orange cloud)

Access Denying Valid Users

1. Check email is in allowed list
2. Clear browser cookies
3. Try incognito mode

---

🔗 Related

• Infrastructure#cloudflared - Cloudflared container details
• Traefik-Setup - Traefik configuration
• Environment-Variables - Cloudflare environment variables