Prerequisites

Relevant source files

• README.md
• docker-compose.yml

This document lists and explains all prerequisites required before deploying the Docker MQTT Mosquitto Cloudflare Tunnel system. These requirements must be satisfied before proceeding to tunnel configuration, mosquitto configuration, and deployment steps.

For step-by-step setup instructions after meeting these prerequisites, see Cloudflare Tunnel Configuration. For system architecture context, see System Architecture.

Purpose and Scope

This page covers the software, accounts, and knowledge required to successfully deploy and operate the system. Each prerequisite is explained with its purpose, minimum version requirements where applicable, and relationship to specific system components.

Required Software Components

The system requires several software components to be installed on the host machine where containers will run.

Docker Engine

Purpose : Docker Engine provides the container runtime environment for both the mosquitto and cloudflared services defined in docker-compose.yml:1-18

Minimum Version : Docker Engine 20.10.0 or later (supports Compose file version 3.8)

Verification :

Used By :

• docker-compose.yml:4-9 - mosquitto service definition
• docker-compose.yml:11-17 - cloudflared service definition

Sources : docker-compose.yml, README.md

Docker Compose

Purpose : Docker Compose orchestrates the multi-container application, managing service startup, networking, and configuration as defined in docker-compose.yml1

Minimum Version : Docker Compose 1.29.0 or later (supports version 3.8 specification)

Verification :

Note : Modern Docker installations include Compose V2 as a Docker CLI plugin (docker compose) rather than a standalone binary (docker-compose).

Used By :

• All service definitions in docker-compose.yml
• Deployment command referenced in README.md:70-72

Sources : docker-compose.yml, README.md

Git

Purpose : Git is required to clone the repository and maintain version control. The repository structure relies on .gitignore rules to protect secrets.

Minimum Version : Git 2.0 or later

Verification :

Used By :

• Cloning repository: git clone https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel
• Version control practices documented in Version Control Practices

Sources : README.md

Software Prerequisites Mapping

The following diagram maps software prerequisites to the specific container services and configuration files they support:

Sources : docker-compose.yml, README.md

graph TB
    subgraph "Host System Prerequisites"
        DockerEngine["Docker Engine\n(20.10.0+)"]
DockerCompose["Docker Compose\n(1.29.0+)"]
Git["Git\n(2.0+)"]
end
    
    subgraph "Repository Files"
        ComposeYML["docker-compose.yml\nversion: '3.8'"]
MosqConf["mosquitto.conf"]
EnvSample[".env.sample"]
GitIgnore[".gitignore"]
end
    
    subgraph "Container Services"
        MosqContainer["mosquitto container\neclipse-mosquitto:latest"]
CFContainer["cloudflared container\ncloudflare/cloudflared:latest"]
end
    
 
   Git -->|clones| ComposeYML
 
   Git -->|clones| MosqConf
 
   Git -->|clones| EnvSample
 
   Git -->|respects| GitIgnore
    
 
   DockerCompose -->|parses| ComposeYML
 
   DockerCompose -->|orchestrates| MosqContainer
 
   DockerCompose -->|orchestrates| CFContainer
    
 
   DockerEngine -->|runs| MosqContainer
 
   DockerEngine -->|runs| CFContainer
    
 
   ComposeYML -->|defines service| MosqContainer
 
   ComposeYML -->|defines service| CFContainer

Required Accounts and Access

Cloudflare Account

Purpose : A Cloudflare account with Zero Trust access is required to create tunnels and obtain the CLOUDFLARE_TUNNEL_TOKEN used by the cloudflared service.

Registration : Free account available at https://dash.cloudflare.com/sign-up

Required Access :

• Cloudflare Zero Trust dashboard access
• Ability to create and configure tunnels
• Ability to configure public hostnames

Used For :

• Creating Cloudflare Tunnel (documented in README.md:27-54)
• Generating CLOUDFLARE_TUNNEL_TOKEN for docker-compose.yml:13-17
• Configuring public hostname routing to mosquitto:9001

Sources : README.md

Zero Trust Portal Access

Purpose : The Zero Trust portal is where Cloudflare Tunnels are created and managed.

Access Path : Cloudflare Dashboard → Zero Trust → Networks → Tunnels

Required Permissions :

• Create new tunnels
• Configure tunnel connectors
• Set up public hostnames

Navigation Steps (detailed in Cloudflare Tunnel Configuration):

1. Zero Trust dashboard access README.md:27-29
2. Tunnel creation README.md:34-45
3. Public hostname configuration README.md:55-66

Sources : README.md

graph LR
    subgraph "External Services"
        CFDashboard["Cloudflare Dashboard\ndash.cloudflare.com"]
ZeroTrust["Zero Trust Portal\nTunnel Management"]
end
    
    subgraph "Local Environment"
        Developer["Developer/Operator"]
EnvFile[".env file\nCLOUDFLARE_TUNNEL_TOKEN=..."]
end
    
    subgraph "Docker Compose Configuration"
        ComposeFile["docker-compose.yml\nline 14: command with token\nline 17: environment var"]
end
    
    subgraph "Running Container"
        CFDContainer["cloudflared container\ntunnel run --token"]
end
    
 
   Developer -->|logs into| CFDashboard
 
   CFDashboard -->|navigates to| ZeroTrust
 
   ZeroTrust -->|creates tunnel, generates| Developer
 
   Developer -->|creates and populates| EnvFile
 
   EnvFile -->|provides ${CLOUDFLARE_TUNNEL_TOKEN}| ComposeFile
 
   ComposeFile -->|passes to| CFDContainer
 
   CFDContainer -->|authenticates with| ZeroTrust

Account and Token Flow

This diagram shows how Cloudflare account credentials and tunnel tokens flow from external services to the deployed containers:

Sources : docker-compose.yml, README.md

Knowledge Prerequisites

While not strictly required for deployment, familiarity with the following concepts will aid in understanding, configuring, and troubleshooting the system:

Sources : README.md, docker-compose.yml

System Requirements

Hardware Requirements

The system has minimal hardware requirements suitable for most modern systems:

Sources : docker-compose.yml

Operating System Compatibility

The system is platform-agnostic due to containerization. Docker Engine must be supported by the host OS:

Sources : docker-compose.yml

Network Requirements

Sources : docker-compose.yml, README.md

Prerequisites Verification Checklist

Before proceeding to Cloudflare Tunnel Configuration, verify all prerequisites are met:

Sources : docker-compose.yml, README.md

File Structure Prerequisites

After cloning the repository, verify the following files are present:

Note : The .env file does not exist in the repository and must be created manually from .env.sample after obtaining the Cloudflare tunnel token. This is documented in Environment Variables.

Sources : docker-compose.yml, README.md

Next Steps

After verifying all prerequisites are met:

1. Proceed to Cloudflare Tunnel Configuration to create a tunnel and obtain your CLOUDFLARE_TUNNEL_TOKEN
2. Then configure environment variables as documented in Environment Variables
3. Review Mosquitto Configuration to understand broker settings
4. Finally, deploy the system following Deployment instructions

For advanced configuration options available in other branches, see Topic Access Control (ACL)) and Encrypted Retained Messages.

Sources : README.md, docker-compose.yml