Prerequisites

Loading…

Prerequisites

Relevant source files

• README.md
• docker-compose.yml

This page documents the required accounts, software, system resources, and knowledge needed before deploying the Docker MQTT Mosquitto with Cloudflare Tunnel system. Complete all prerequisites in this section before proceeding to Cloudflare Tunnel Setup.

For information about the actual setup process, see Cloudflare Tunnel Setup. For details about the system’s architectural requirements, see System Architecture.

Required Accounts

Cloudflare Account with Zero Trust Access

A Cloudflare account with Zero Trust dashboard access is required to create and manage the Cloudflare Tunnel. The tunnel connector authenticates using a token generated through this interface.

Account Requirements:

• Active Cloudflare account (free tier sufficient)
• Access to the Zero Trust dashboard at https://one.dash.cloudflare.com/
• Permission to create tunnels under the Networks → Tunnels section

Why Required: The system architecture depends on the Cloudflare Tunnel service to provide secure, outbound-only connectivity between the cloudflared container and Cloudflare’s edge network. Without Zero Trust access, you cannot generate the CLOUDFLARE_TUNNEL_TOKEN that authenticates the tunnel connection specified in docker-compose.yml14

Sources: README.md:29-31 README.md:36-51

Required Software

Docker Engine

Docker Engine is required to run the containerized services defined in docker-compose.yml The system has been tested with Docker Engine version 20.10+ but should work with any recent release supporting Compose file format version 3.8.

Installation Verification:

Expected output format: Docker version XX.XX.X, build XXXXXXX

Why Required: The system consists of two containerized services (mosquitto and cloudflared) that must run in an isolated network environment. Docker Engine provides the container runtime, networking layer, and volume management capabilities referenced in docker-compose.yml:1-18

Docker Compose

Docker Compose orchestrates the multi-container application lifecycle. The docker-compose.yml1 file uses format version 3.8, requiring Docker Compose v1.28.0+ or Docker Engine with integrated Compose v2.

Installation Verification:

Expected output format: Docker Compose version vX.XX.X or docker-compose version X.XX.X

Why Required: The system requires coordinated startup, networking, and lifecycle management of two containers: mosquitto (MQTT broker) and cloudflared (tunnel connector). Docker Compose provides service discovery via internal DNS, allowing the cloudflared container to resolve mosquitto:9001 as configured in docker-compose.yml:4-17

Git (Optional but Recommended)

Git version control is recommended for cloning the repository and tracking local configuration changes.

Installation Verification:

Why Required: While you can download the repository as a ZIP archive, Git provides version tracking for local modifications to mosquitto.conf and allows you to easily integrate updates from upstream. The .gitignore1 configuration ensures that your .env file containing secrets is never committed.

Sources: docker-compose.yml1 .gitignore1

System Requirements

Hardware Resources

The system has minimal resource requirements due to the lightweight nature of both containers.

Container-Specific Resources:

The mosquitto container (docker-compose.yml:4-9) runs Eclipse Mosquitto, a minimal MQTT broker with low memory footprint. The cloudflared container (docker-compose.yml:11-17) maintains a persistent WebSocket connection to Cloudflare’s network and proxies traffic to the Mosquitto service.

Why These Requirements:

• Mosquitto’s memory usage scales with the number of retained messages and active connections
• The cloudflared tunnel requires stable outbound connectivity to maintain the persistent connection
• No inbound ports are exposed, so firewall configuration is not required

Operating System

The system runs on any platform supporting Docker Engine:

• Linux : Native Docker support (Ubuntu, Debian, RHEL, CentOS, etc.)
• macOS : Docker Desktop for Mac
• Windows : Docker Desktop for Windows (WSL2 backend recommended)

The containers use multi-architecture images (eclipse-mosquitto:latest and cloudflare/cloudflared:latest) that support both AMD64 and ARM64 architectures.

Sources: docker-compose.yml5 docker-compose.yml12

Domain and DNS Prerequisites

Cloudflare-Managed Domain

You must have a domain registered with and managed by Cloudflare to configure public hostname routing.

Domain Requirements:

• Domain added to your Cloudflare account
• Nameservers pointing to Cloudflare’s DNS servers
• DNS zone active (orange-clouded or proxied)

Why Required: When configuring the public hostname in Cloudflare Tunnel Setup, you specify a subdomain (e.g., mqtt.example.com) that routes to your tunnel. Cloudflare must control the DNS zone to create the CNAME record pointing to the tunnel endpoint.

Diagram: DNS Resolution Flow Requiring Cloudflare-Managed Domain

graph LR
    subgraph "External DNS"
        CLIENT["Client"]
PUBLIC_DNS["Public DNS Resolver"]
end
    
    subgraph "Cloudflare Network"
        CF_DNS["Cloudflare DNS\n(Authoritative)"]
CF_TUNNEL["Cloudflare Tunnel\nInfrastructure"]
end
    
    subgraph "Local Docker Environment"
        CLOUDFLARED["cloudflared container"]
MOSQUITTO["mosquitto container"]
end
    
 
   CLIENT -->|1. DNS query: mqtt.example.com| PUBLIC_DNS
 
   PUBLIC_DNS -->|2. Query nameservers| CF_DNS
 
   CF_DNS -->|3. Return CNAME: tunnel-id.cfargotunnel.com| PUBLIC_DNS
 
   PUBLIC_DNS -->|4. Resolve to Cloudflare edge IP| CLIENT
 
   CLIENT -->|5. HTTPS request| CF_TUNNEL
 
   CF_TUNNEL <-->|6. Tunnel protocol| CLOUDFLARED
 
   CLOUDFLARED -->|7. HTTP proxy| MOSQUITTO

The diagram illustrates why domain management through Cloudflare is required. The tunnel’s public hostname must resolve to Cloudflare’s infrastructure, which requires authoritative DNS control.

Sources: README.md:61-67

File System Prerequisites

Working Directory Structure

The deployment requires a local directory containing the repository files with specific structure:

docker-mqtt-mosquitto-cloudflare-tunnel/
├── docker-compose.yml          # Service orchestration definition
├── mosquitto.conf              # Mosquitto broker configuration
├── .env                        # Secret environment variables (created by user)
├── .env.sample                 # Template for .env file
└── .gitignore                  # Ensures .env is not committed

Required Files:

• docker-compose.yml:1-18: Defines both container services
• mosquitto.conf:1-5: Configures MQTT and WebSocket listeners

User-Created Files:

• .env: Must contain CLOUDFLARE_TUNNEL_TOKEN=<your_token> (see .env.sample1)

Protected Files:

• .gitignore1: Ensures .env is excluded from version control

Write Permissions

The Docker Engine process requires read access to:

• docker-compose.yml
• mosquitto.conf
• .env file

The Mosquitto container requires write access to its internal directories for log files and persistence (not exposed as volumes in the base configuration).

Sources: docker-compose.yml:7-8 .env.sample1 .gitignore1

graph TB
    subgraph "Local Network"
        DOCKER_HOST["Docker Host"]
CLOUDFLARED["cloudflared Container"]
end
    
    subgraph "Firewall Rules"
        OUTBOUND_443["Allow Outbound\nTCP/443\n(HTTPS)"]
INBOUND_BLOCKED["Block All Inbound\n(No ports exposed)"]
end
    
    subgraph "Cloudflare Network"
        CF_EDGE["Cloudflare Edge\nTunnel Endpoint"]
end
    
 
   CLOUDFLARED -->|Persistent WebSocket Over HTTPS| OUTBOUND_443
 
   OUTBOUND_443 --> CF_EDGE
 
   INBOUND_BLOCKED -.->|Not required| DOCKER_HOST

Network Prerequisites

Outbound Internet Access

The cloudflared container requires persistent outbound HTTPS connectivity (port 443) to Cloudflare’s network.

Required Connectivity:

Diagram: Required Network Access Pattern

Firewall Configuration:

• Outbound: Port 443 (HTTPS) must be allowed for tunnel connectivity
• Inbound: No inbound ports required; tunnel uses outbound-only connections
• Internal: Docker’s default bridge network handles inter-container routing

Why This Design: The outbound-only architecture (README.md17) eliminates the need for port forwarding, dynamic DNS, or public IP addresses. The cloudflared container (docker-compose.yml:11-17) initiates the connection to Cloudflare’s network, which then proxies inbound client traffic through the established tunnel.

Sources: docker-compose.yml:11-17 README.md17

Knowledge Prerequisites

Required Technical Knowledge

Users deploying this system should have working knowledge of:

Optional Advanced Knowledge

The following knowledge areas are optional but helpful for troubleshooting and customization:

• Linux command line: For log inspection and container debugging
• Cloudflare Zero Trust: For advanced access policies and authentication
• MQTT ACLs: For implementing user-based topic restrictions (see [protected-no-wildcard branch](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/protected-no-wildcard branch))
• Docker networking: For custom network configurations

Sources: README.md:7-13

Prerequisites Verification Checklist

Before proceeding to Cloudflare Tunnel Setup, verify all prerequisites:

Diagram: Prerequisites Verification Flow

After completing this checklist, proceed to Cloudflare Tunnel Setup to begin the deployment process.

Sources: README.md:29-78 docker-compose.yml:1-18

graph TB
    subgraph "Prerequisites"
        CF_ACCT["Cloudflare Account"]
DOCKER_ENG["Docker Engine"]
COMPOSE_CLI["Docker Compose"]
CF_DOMAIN["Cloudflare-Managed\nDomain"]
OUTBOUND_NET["Outbound Network\nAccess"]
end
    
    subgraph "Configuration Files"
        ENV_FILE[".env"]
ENV_SAMPLE[".env.sample"]
COMPOSE_YML["docker-compose.yml"]
MOSQ_CONF["mosquitto.conf"]
GITIGNORE[".gitignore"]
end
    
    subgraph "Runtime Artifacts"
        TOKEN_VAR["CLOUDFLARE_TUNNEL_TOKEN\nenvironment variable"]
MOSQ_SERVICE["mosquitto service"]
CFD_SERVICE["cloudflared service"]
MOSQ_MOUNT["mosquitto.conf\nvolume mount"]
end
    
 
   CF_ACCT -->|generates| TOKEN_VAR
 
   TOKEN_VAR -->|stored in| ENV_FILE
 
   ENV_SAMPLE -->|template for| ENV_FILE
    
 
   DOCKER_ENG -->|executes| COMPOSE_YML
 
   COMPOSE_CLI -->|orchestrates| COMPOSE_YML
    
 
   COMPOSE_YML -->|defines| MOSQ_SERVICE
 
   COMPOSE_YML -->|defines| CFD_SERVICE
 
   COMPOSE_YML -->|references| TOKEN_VAR
 
   COMPOSE_YML -->|mounts| MOSQ_MOUNT
    
 
   MOSQ_CONF -->|mounted as| MOSQ_MOUNT
 
   MOSQ_MOUNT -->|configures| MOSQ_SERVICE
    
 
   CF_DOMAIN -->|routes to| CFD_SERVICE
 
   OUTBOUND_NET -->|enables| CFD_SERVICE
    
 
   GITIGNORE -.->|protects| ENV_FILE

Relationship to System Files

The following diagram maps prerequisites to the specific files and configurations they enable:

Diagram: Prerequisites Mapping to System Files

This diagram shows how each prerequisite enables specific parts of the system configuration. For example:

• The Cloudflare account generates the token stored in .env
• Docker Engine and Compose execute docker-compose.yml:1-18
• The mosquitto.conf:1-5 file is mounted as a volume into the mosquitto container
• The domain and network prerequisites enable the cloudflared service to function

Sources: docker-compose.yml:1-18 mosquitto.conf:1-5 .env.sample1 .gitignore1

Dismiss

Refresh this wiki

Enter email to refresh