Cloudflare Tunnel Configuration

Relevant source files

• .env.sample
• README.md
• docker-compose.yml

Purpose and Scope

This page provides a detailed walkthrough of setting up a Cloudflare Tunnel through the Cloudflare Zero Trust dashboard, obtaining the tunnel token, and configuring public hostnames to route traffic to the mosquitto MQTT broker. This configuration is required before deploying the system via docker-compose.

For information about the overall system architecture and security model, see System Architecture and Security Model. For details about configuring the mosquitto broker itself, see Mosquitto Configuration. For environment variable setup, see Environment Variables.

Cloudflare Tunnel Architecture

The following diagram illustrates how the Cloudflare Tunnel configuration integrates with the codebase:

Cloudflare Tunnel Configuration Flow

graph TB
    subgraph "Cloudflare Zero Trust Dashboard"
        ZT["Zero Trust Portal"]
CreateTunnel["Create Tunnel Action"]
TunnelConfig["Tunnel Configuration\nName: user-defined"]
TokenGen["Token Generator"]
HostnameConfig["Public Hostname Config\nService: HTTP\nURL: mosquitto:9001"]
end
    
    subgraph "Local Environment"
        EnvFile[".env file"]
TokenVar["CLOUDFLARE_TUNNEL_TOKEN"]
end
    
    subgraph "docker-compose.yml"
        CloudflaredService["cloudflared service"]
Command["command: tunnel --no-autoupdate run --token"]
EnvVarRef["environment:\n- CLOUDFLARE_TUNNEL_TOKEN"]
MosquittoRef["mosquitto:9001\ncontainer_name: mosquitto"]
end
    
    subgraph "Runtime"
        CloudflaredContainer["cloudflared container"]
CFNetwork["Cloudflare Edge Network"]
MosquittoContainer["mosquitto container\nport 9001"]
end
    
 
   ZT --> CreateTunnel
 
   CreateTunnel --> TunnelConfig
 
   TunnelConfig --> TokenGen
 
   TokenGen -->|Copy token| TokenVar
 
   TunnelConfig --> HostnameConfig
    
 
   TokenVar -->|Store in| EnvFile
 
   EnvFile -->|Provides value to| EnvVarRef
    
 
   EnvVarRef --> Command
 
   Command -->|Runs in| CloudflaredService
 
   CloudflaredService -->|Creates| CloudflaredContainer
    
 
   HostnameConfig -->|Routes traffic to| MosquittoRef
 
   MosquittoRef -->|Resolves to| MosquittoContainer
    
 
   CloudflaredContainer -->|Authenticates with| CFNetwork
 
   CloudflaredContainer -->|Proxies traffic to| MosquittoContainer

Sources: README.md:23-67, docker-compose.yml:11-17, .env.sample:1

Configuration Steps

Step 1: Access Cloudflare Zero Trust Dashboard

Navigate to the Cloudflare Zero Trust portal to begin tunnel configuration. This interface manages all Cloudflare Tunnel settings.

Sources: README.md:27-29

Step 2: Create a Tunnel

The tunnel creation process generates a unique identifier and authentication token for your deployment.

Tunnel Creation Process

Sources: README.md:33-44

Step 3: Extract and Store the Tunnel Token

After tunnel creation, the dashboard displays a Docker command containing the CLOUDFLARE_TUNNEL_TOKEN. This token must be stored in the .env file for use by the cloudflared service.

Token Extraction and Storage

graph LR
    subgraph "Cloudflare Dashboard"
        DockerCmd["Docker command display\nEnvironment: Docker"]
TokenInCmd["Token embedded in command"]
end
    
    subgraph "Local Repository"
        EnvSample[".env.sample\nCLOUDFLARE_TUNNEL_TOKEN=your_token"]
EnvFile[".env\nCLOUDFLARE_TUNNEL_TOKEN=actual_token"]
end
    
    subgraph "docker-compose.yml:16-17"
        EnvDeclaration["environment:\n- CLOUDFLARE_TUNNEL_TOKEN"]
end
    
 
   DockerCmd --> TokenInCmd
 
   TokenInCmd -->|Copy token value| EnvFile
 
   EnvSample -.->|Template for| EnvFile
 
   EnvFile -->|Provides variable to| EnvDeclaration

Important: Do not execute the Docker command displayed in the dashboard. The docker-compose.yml:11-17 configuration in this repository replaces that step by running the cloudflared container with the token from the .env file.

Sources: README.md:47-53, .env.sample:1, docker-compose.yml:16-17

Step 4: Configure Public Hostname

The public hostname configuration routes external traffic through the Cloudflare edge network to the internal mosquitto service.

Hostname Configuration Parameters

Important Implementation Details:

• The URL mosquitto:9001 uses Docker's internal DNS resolution
• mosquitto resolves to the container with container_name: mosquitto from docker-compose.yml6
• Port 9001 corresponds to the WebSocket listener configured in mosquitto.conf
• The service type HTTP refers to the tunnel transport protocol; MQTT over WebSocket is carried within HTTP

Public Hostname Routing Flow

graph LR
    subgraph "Public Internet"
        Client["MQTT Client"]
PublicHostname["public-hostname.domain.com"]
end
    
    subgraph "Cloudflare Network"
        CFEdge["Cloudflare Edge"]
TunnelRoute["Tunnel Route\nService: HTTP\nURL: mosquitto:9001"]
end
    
    subgraph "Docker Network"
        CloudflaredContainer["cloudflared container\ncontainer_name: cloudflared"]
DNSResolution["Docker DNS\nmosquitto → 172.x.x.x"]
MosquittoContainer["mosquitto container\ncontainer_name: mosquitto\nport 9001 listener"]
end
    
 
   Client -->|Connect to| PublicHostname
 
   PublicHostname -->|Resolves to| CFEdge
 
   CFEdge -->|Routes via| TunnelRoute
 
   TunnelRoute -->|Proxies to| CloudflaredContainer
 
   CloudflaredContainer -->|Resolves| DNSResolution
 
   DNSResolution -->|Forwards to| MosquittoContainer

Configuration Steps:

1. Navigate to the newly created tunnel in the Zero Trust dashboard
2. Click "Next" to proceed to hostname configuration
3. Fill in the public hostname configuration form:
   • Enter your desired subdomain and domain
   • Select HTTP as the service type
   • Enter mosquitto:9001 as the URL
4. Click "Save hostname" to finalize

Sources: README.md:55-66, docker-compose.yml:4-9

Token Integration with docker-compose

The CLOUDFLARE_TUNNEL_TOKEN environment variable is consumed by the cloudflared service definition in docker-compose.yml:11-17:

cloudflared Service Configuration

Environment Variable Flow

Sources: docker-compose.yml:11-17, .env.sample:1

Configuration Verification

After completing the configuration steps, verify the setup before deployment:

Pre-Deployment Checklist

Expected State Before Deployment:

• Tunnel status in Cloudflare dashboard: "Inactive" (no connector running yet)
• .env file: Contains valid token, not tracked by git (see .gitignore)
• Public hostname: Configured but not yet accessible (no traffic can flow until containers start)

The next step is to deploy the system using docker compose up, covered in Deployment.

Sources: README.md:23-73, docker-compose.yml:1-18

Common Configuration Issues

Sources: docker-compose.yml:11-17, README.md:47-67