Overview

Loading…

Overview

Relevant source files

• README.md

Purpose and Scope

This document provides a comprehensive introduction to the Docker MQTT Mosquitto with Cloudflare Tunnel system, explaining its architecture, components, and operational model. This system deploys a containerized Eclipse Mosquitto MQTT broker and securely exposes it to the internet via Cloudflare Tunnel, eliminating the need for publicly exposed ports or inbound firewall rules.

For detailed architectural diagrams and component interactions, see System Architecture. For security principles and Zero Trust implementation details, see Security Model. For step-by-step deployment instructions, see Getting Started.

Sources: README.md:1-23

What is This System?

The Docker MQTT Mosquitto with Cloudflare Tunnel system is a production-ready deployment pattern that combines:

• Eclipse Mosquitto : An open-source MQTT message broker that facilitates publish/subscribe messaging between IoT devices and applications
• Cloudflare Tunnel : A secure tunneling service that exposes local services to the internet without opening inbound ports
• Docker Compose : Container orchestration for reproducible, multi-container deployments

The system implements a Zero Trust security model where the MQTT broker has no internet-facing attack surface. All external traffic is routed through Cloudflare’s global edge network, which provides DDoS protection, SSL termination, and geographic distribution.

Sources: README.md:17-23

Key Features

The system provides the following capabilities:

Sources: README.md:1-23 .github/workflows/ci.yml:1-41 .github/workflows/build-docs.yml:1-84

Core Components

The system consists of three primary components orchestrated by Docker Compose:

Component Summary

Supporting Configuration Files

Sources: docker-compose.yml:1-19 mosquitto.conf:1-5 .env.sample1 .gitignore:1-2

graph TB
    subgraph Internet["Internet / Public Network"]
Client["External MQTT Clients\n(IoT Devices, Applications)"]
end
    
    subgraph CF["Cloudflare Network"]
Edge["Cloudflare Edge\nTLS Termination\nPort 443"]
Tunnel["Cloudflare Tunnel Service"]
end
    
    subgraph DockerHost["Docker Host"]
Compose["docker-compose.yml\nServices Orchestration"]
subgraph Network["Docker Network (Bridge)"]
MosqContainer["Container: mosquitto\neclipse-mosquitto:latest\ncontainer_name: mosquitto"]
CFDContainer["Container: cloudflared\ncloudflare/cloudflared:latest\ncontainer_name: cloudflared"]
end
        
        MosqConf["mosquitto.conf\nVolume Mount\n/mosquitto/config/mosquitto.conf"]
EnvFile[".env\nCLOUDFLARE_TUNNEL_TOKEN"]
end
    
 
   Client -->|HTTPS/WSS Port 443| Edge
 
   Edge -->|Secure Tunnel| Tunnel
 
   Tunnel <-->|Outbound Connection Token Authentication| CFDContainer
    
 
   Compose -->|manages| MosqContainer
 
   Compose -->|manages| CFDContainer
    
 
   MosqConf -->|volumes: ./mosquitto.conf| MosqContainer
 
   EnvFile -->|environment: CLOUDFLARE_TUNNEL_TOKEN| CFDContainer
    
 
   CFDContainer -->|HTTP to mosquitto:9001| MosqContainer
    
 
   MosqContainer -->|listener 1883 protocol mqtt| ListenerMQTT["MQTT Protocol\nInternal Port 1883"]
MosqContainer -->|listener 9001 protocol websockets| ListenerWS["WebSocket Protocol\nInternal Port 9001"]

System Topology

The following diagram illustrates the complete system architecture, mapping high-level concepts to specific code entities and configuration elements:

Container and Network Topology

Key Code Entities:

• Service Name : mosquitto in docker-compose.yml4 - used for Docker internal DNS resolution
• Container Name : mosquitto in docker-compose.yml5 - named container instance
• Container Name : cloudflared in docker-compose.yml12 - tunnel connector instance
• Volume Mount : ./mosquitto.conf:/mosquitto/config/mosquitto.conf in docker-compose.yml:8-9
• Environment Variable : CLOUDFLARE_TUNNEL_TOKEN referenced in docker-compose.yml:16-17
• Listener Directives : listener 1883 and listener 9001 in mosquitto.conf:1-5
• Command : tunnel run in docker-compose.yml13 - starts tunnel connector with token authentication

Sources: docker-compose.yml:1-19 mosquitto.conf:1-5 README.md:64-67

sequenceDiagram
    participant Client as "External Client\n(MQTT/WebSocket)"
    participant CFEdge as "Cloudflare Edge\nPort 443 HTTPS"
    participant CFTunnel as "Cloudflare Tunnel\nInfrastructure"
    participant CloudflaredContainer as "Container: cloudflared\nCommand: tunnel run"
    participant DockerDNS as "Docker Internal DNS\nmosquitto:9001"
    participant MosquittoContainer as "Container: mosquitto\nPort 9001 Listener"
    
    Note over Client,MosquittoContainer: Initial Connection Phase
    CloudflaredContainer->>CFTunnel: Establish tunnel using\nCLOUDFLARE_TUNNEL_TOKEN
    CFTunnel-->>CloudflaredContainer: Tunnel authenticated and ready
    
    Note over Client,MosquittoContainer: Client CONNECT Request
    Client->>CFEdge: CONNECT to https://subdomain.domain:443
    CFEdge->>CFTunnel: Route via tunnel config\nPublic Hostname mapping
    CFTunnel->>CloudflaredContainer: Forward through secure tunnel
    CloudflaredContainer->>DockerDNS: Resolve "mosquitto:9001"
    DockerDNS-->>CloudflaredContainer: Return container IP
    CloudflaredContainer->>MosquittoContainer: HTTP request to port 9001\nprotocol websockets
    MosquittoContainer-->>CloudflaredContainer: WebSocket upgrade response
    CloudflaredContainer-->>CFTunnel: Return response
    CFTunnel-->>CFEdge: Return response
    CFEdge-->>Client: HTTPS/WSS connection established
    
    Note over Client,MosquittoContainer: Client PUBLISH Message
    Client->>CFEdge: PUBLISH to topic
    CFEdge->>CFTunnel: Forward
    CFTunnel->>CloudflaredContainer: Via tunnel
    CloudflaredContainer->>MosquittoContainer: HTTP POST to mosquitto:9001
    MosquittoContainer->>MosquittoContainer: Process message\nRoute to subscribers
    MosquittoContainer-->>CloudflaredContainer: PUBACK
    CloudflaredContainer-->>CFTunnel: Return
    CFTunnel-->>CFEdge: Return
    CFEdge-->>Client: PUBACK confirmation

Request Flow Architecture

This diagram traces a complete MQTT message flow from external client to broker, mapping each step to specific code entities and configuration elements:

End-to-End Message Flow

Key Code References in Flow:

1. Tunnel Authentication : CLOUDFLARE_TUNNEL_TOKEN from docker-compose.yml:16-17 passed to cloudflared container
2. Tunnel Command : tunnel run in docker-compose.yml13 establishes outbound connection
3. DNS Resolution : Service name mosquitto defined in docker-compose.yml4 resolved by Docker’s internal DNS
4. Port Configuration : 9001 listener defined in mosquitto.conf:4-5 handles WebSocket connections
5. Protocol Setting : protocol websockets in mosquitto.conf5 enables WebSocket support
6. Public Hostname : Configured in Cloudflare dashboard (Step 3 of README.md:57-72) maps public URL to internal mosquitto:9001

Sources: docker-compose.yml:1-19 mosquitto.conf:1-5 README.md:57-72

Deployment Model

The system uses a two-phase deployment model that separates cloud configuration from local execution:

Phase 1: Cloud Configuration (One-Time Setup)

Sources: README.md:29-72

Phase 2: Local Deployment (Repeatable)

Sources: README.md:53-78 .env.sample1 .gitignore:1-2

Security Architecture

The system implements defense-in-depth security through multiple layers:

Security Layers

Key Security Implementations:

1. No Inbound Ports : docker-compose.yml:1-19 defines no ports: sections, preventing host exposure
2. Outbound-Only Connection : tunnel run command in docker-compose.yml13 establishes connection from origin to Cloudflare
3. Secret Exclusion : .env pattern in .gitignore1 prevents accidental token commits
4. Anonymous Access : Currently configured as allow_anonymous true in mosquitto.conf3 - see Authentication and Access Control for implications

For comprehensive security documentation, see Security Model.

Sources: docker-compose.yml:1-19 mosquitto.conf:1-5 .gitignore:1-2

Advanced Features

The repository includes an alternative branch with additional security features:

Protected Branch Features

The protected-no-wildcard branch implements:

See Protected Branch Features for detailed documentation.

Sources: README.md:7-13

CI/CD Integration

The system includes automated quality assurance through GitHub Actions:

Continuous Integration Workflow

The .github/workflows/ci.yml:1-41 workflow performs:

1. Service Provisioning : Starts mosquitto container via docker-compose up -d mosquitto
2. Health Check Loop : Polls container status up to 10 times with 10-second intervals
3. Verification : Ensures docker ps | grep mosquitto | grep "Up" succeeds
4. Cleanup : Executes docker-compose down regardless of test outcome

Documentation Pipeline

The .github/workflows/build-docs.yml:1-84 workflow:

1. Generates documentation using DeepWiki integration
2. Builds mdBook static site
3. Deploys to GitHub Pages on weekly schedule or manual trigger

For complete CI/CD documentation, see CI/CD and Automation.

Sources: .github/workflows/ci.yml:1-41 .github/workflows/build-docs.yml:1-84

Quick Start Reference

To deploy this system:

1. Prerequisites : Docker, Docker Compose, Cloudflare account (see Prerequisites)
2. Cloudflare Setup : Create tunnel and obtain token (see Cloudflare Tunnel Setup)
3. Local Configuration : Create .env file with token (see Local Configuration)
4. Deployment : Run docker compose up (see Deployment)

Your MQTT broker will be accessible at https://<subdomain>.<domain>:443 as configured in the Cloudflare Public Hostname settings.

Important : The URL mosquitto:9001 referenced in README.md64 is internal to Docker and resolved via the service name in docker-compose.yml4 The public URL is configured separately in the Cloudflare dashboard and uses HTTPS on port 443, not HTTP on port 9001.

For complete deployment instructions, see Getting Started.

Sources: README.md:25-84 docker-compose.yml:1-19

Dismiss

Refresh this wiki

Enter email to refresh

Getting Started

Loading…

Getting Started

Relevant source files

• README.md

This page guides you through the complete deployment process for the Docker MQTT Mosquitto Cloudflare Tunnel system. The setup consists of four phases: verifying prerequisites, configuring Cloudflare Tunnel, setting up local configuration files, and deploying containers.

Related Pages:

• Prerequisites (page 2.1): System requirements and account setup
• Cloudflare Tunnel Setup (page 2.2): Detailed tunnel creation steps
• Local Configuration (page 2.3): Environment and configuration file setup
• Deployment (page 2.4): Container deployment and verification

Deployment Workflow

The deployment process follows a linear sequence of configuration and initialization steps:

Diagram: Deployment Phase Sequence

stateDiagram-v2
    [*] --> Prerequisites
    Prerequisites --> CloudflareTunnel : Accounts verified
    CloudflareTunnel --> LocalConfig : CLOUDFLARE_TUNNEL_TOKEN obtained
    LocalConfig --> Deployment : .env file created
    Deployment --> [*] : Containers running
    
    state CloudflareTunnel {
        [*] --> CreateTunnel
        CreateTunnel --> ConfigureHostname
        ConfigureHostname --> [*]
    }
    
    state LocalConfig {
        [*] --> CreateEnvFile
        CreateEnvFile --> PopulateToken
        PopulateToken --> [*]
    }
    
    state Deployment {
        [*] --> DockerComposeUp
        DockerComposeUp --> VerifyContainers
        VerifyContainers --> [*]
    }

Sources : README.md:29-78

Deployment Phases Summary

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

Configuration File Flow

Diagram: File-to-Container Mapping

Sources : docker-compose.yml:1-18 .env.sample:1-3 .gitignore:1-2

Configuration File Purposes

Sources : docker-compose.yml:1-18 mosquitto.conf:1-5 .env.sample:1-3 .gitignore:1-2

Quick Start Summary

This section provides an abbreviated setup sequence. For detailed instructions, see the child pages (2.1 through 2.4).

Step 1: Cloudflare Tunnel Configuration

Create a tunnel in the Cloudflare Zero Trust dashboard and obtain the CLOUDFLARE_TUNNEL_TOKEN. Configure a public hostname that routes to mosquitto:9001.

Detailed instructions : See page 2.2 (Cloudflare Tunnel Setup)

Key outputs :

• Tunnel token string (begins with eyJ...)
• Public hostname (e.g., mqtt.example.com)

Sources : README.md:29-73

Step 2: Local Environment Setup

Create .env file from template and populate with tunnel token:

Edit .env:

CLOUDFLARE_TUNNEL_TOKEN=<token_from_step_1>

Detailed instructions : See page 2.3 (Local Configuration)

File locations :

• Template: .env.sample:1-3
• Configuration to create: .env (excluded by .gitignore1)

Sources : .env.sample:1-3 README.md53

Step 3: Container Deployment

Execute Docker Compose to start both services:

Detailed instructions : See page 2.4 (Deployment)

Services started :

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

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

Container Initialization

Diagram: Docker Compose Service Startup Sequence

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

Post-Deployment Verification

Verify both containers are operational:

Expected output shows two running containers:

Check cloudflared logs for tunnel establishment confirmation:

Check mosquitto logs for listener initialization:

Sources : docker-compose.yml:4-9 docker-compose.yml:11-17

Docker Compose Service Configuration

Diagram: Service Definition to Runtime Mapping

Sources : docker-compose.yml:1-18

Service Configuration Parameters

mosquitto Service

File reference : docker-compose.yml:4-9

cloudflared Service

File reference : docker-compose.yml:11-17

Sources : docker-compose.yml:1-18

Connection Flow After Deployment

Once both containers are operational, the request flow follows this path:

1. External clients connect to public hostname (e.g., https://mqtt.example.com:443)
2. Cloudflare edge network receives connection
3. Traffic routes through tunnel to cloudflared container
4. cloudflared proxies to mosquitto:9001 via Docker internal DNS
5. mosquitto container handles connection on WebSocket listener (port 9001)

Diagram: Client-to-Broker Request Path

graph LR
    Client["MQTT Client"]
CFEdge["Cloudflare Edge\n(Port 443)"]
Tunnel["Tunnel Infrastructure"]
CFDContainer["cloudflared container"]
MosqContainer["mosquitto container\n(Port 9001)"]
Client -->|HTTPS/WSS| CFEdge
 
   CFEdge -->|Tunnel protocol| Tunnel
 
   Tunnel -->|Encrypted tunnel| CFDContainer
 
   CFDContainer -->|HTTP to mosquitto:9001| MosqContainer

Sources : README.md:64-67 README.md82

System Management Commands

Sources : docker-compose.yml:1-18

Next Steps

For detailed setup instructions , refer to child pages:

For advanced topics , see:

• Component details : Pages 3.1 (Mosquitto), 3.2 (Cloudflared), 3.3 (Docker Compose)
• Configuration reference : Pages 4.1, 4.2, 4.3
• Production deployment : Page 6.2
• Advanced security features : Page 6.1 (see protected-no-wildcard branch for ACL and encryption)

Sources : README.md:7-13 (protected branch reference)

Common Initial Setup Issues

For comprehensive troubleshooting, see Troubleshooting.

Sources : README.md:23-73 docker-compose.yml:1-18 .env.sample:1-3

Dismiss

Refresh this wiki

Enter email to refresh

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

System Architecture

Loading…

System Architecture

Relevant source files

• README.md
• docker-compose.yml

Purpose and Scope

This page provides a detailed technical explanation of the system architecture for the Docker MQTT Mosquitto with Cloudflare Tunnel deployment. It covers container topology, network routing, external access patterns, and configuration mechanisms. For information about security principles and threat models, see Security Model. For step-by-step deployment instructions, see Getting Started.

The architecture implements a Zero Trust access pattern where the MQTT broker remains completely unexposed to the public internet, with all external access routed through Cloudflare’s network via an outbound-only tunnel connection.

Sources: README.md:1-93

Container Topology

Service Definitions

The system consists of two containerized services orchestrated by Docker Compose:

Both services are defined in docker-compose.yml:3-17 and run on Docker Compose’s default bridge network, enabling service-to-service communication via Docker’s internal DNS resolver.

graph TB
    subgraph DockerComposeOrchestration["Docker Compose (version 3.8)"]
subgraph MosquittoService["mosquitto service"]
MosquittoContainer["mosquitto container\n(eclipse-mosquitto:latest)"]
MosquittoVolume["Volume Mount:\n./mosquitto.conf\n→\n/mosquitto/config/mosquitto.conf"]
MosquittoRestart["restart: unless-stopped"]
end
        
        subgraph CloudflaredService["cloudflared service"]
CloudflaredContainer["cloudflared container\n(cloudflare/cloudflared:latest)"]
CloudflaredCommand["command:\ntunnel --no-autoupdate run --token"]
CloudflaredEnv["environment:\nCLOUDFLARE_TUNNEL_TOKEN"]
CloudflaredRestart["restart: unless-stopped"]
end
        
        DockerDNS["Docker Internal DNS"]
end
    
 
   MosquittoVolume -->|configures| MosquittoContainer
 
   MosquittoRestart -.->|lifecycle policy| MosquittoContainer
 
   CloudflaredEnv -->|authenticates| CloudflaredCommand
 
   CloudflaredCommand -->|runs in| CloudflaredContainer
 
   CloudflaredRestart -.->|lifecycle policy| CloudflaredContainer
    
 
   CloudflaredContainer -->|resolves 'mosquitto:9001'| DockerDNS
 
   DockerDNS -->|maps to container IP| MosquittoContainer

Container Dependency Graph

Sources: docker-compose.yml:1-18

Network Architecture

Internal Docker Networking

Docker Compose creates an isolated bridge network where containers communicate using service names as hostnames. The cloudflared service connects to the Mosquitto broker using the internal hostname mosquitto:9001, which Docker’s DNS resolver maps to the mosquitto container’s IP address on the bridge network.

Key Architectural Properties:

graph LR
    subgraph DockerBridgeNetwork["Docker Bridge Network"]
CloudflaredProc["cloudflared process\n(cloudflared container)"]
MosquittoProc["mosquitto process\n(mosquitto container)"]
CloudflaredProc -->|HTTP request to mosquitto:9001| DockerInternalDNS["Docker DNS Resolver"]
DockerInternalDNS -->|resolves to container IP| MosquittoProc
        
        subgraph MosquittoListeners["Mosquitto Listeners"]
Port1883["Port 1883\n(MQTT protocol)"]
Port9001["Port 9001\n(WebSocket/HTTP)"]
end
        
 
       MosquittoProc -->|binds| Port1883
 
       MosquittoProc -->|binds| Port9001
    end
    
    HostMachine["Host Machine\n(NO port exposure)"]
DockerBridgeNetwork -.->|isolated from| HostMachine

• No Port Exposure: Neither service exposes ports to the host machine via the ports directive in docker-compose.yml
• Service Discovery: The cloudflared container resolves mosquitto via Docker’s internal DNS without IP address configuration
• Network Isolation: All inter-service communication occurs within the Docker bridge network

Sources: docker-compose.yml:4-17 README.md:64-67

External Access Flow

Cloudflare Tunnel Architecture

External clients connect to the MQTT broker through Cloudflare’s infrastructure, never directly accessing the origin server. This inverted connection model eliminates the need for inbound firewall rules or public IP addresses.

sequenceDiagram
    participant ExtClient as "External MQTT Client"
    participant CFEdge as "Cloudflare Edge Network\n(Global PoPs)"
    participant CFTunnel as "Cloudflare Tunnel Infrastructure"
    participant CloudflaredContainer as "cloudflared container"
    participant MosquittoContainer as "mosquitto container"
    
    Note over CloudflaredContainer,CFTunnel: Tunnel Establishment (Startup)
    CloudflaredContainer->>CFTunnel: Outbound connection with token
    CFTunnel-->>CloudflaredContainer: Tunnel established
    
    Note over ExtClient,MosquittoContainer: Client Connection Flow
    ExtClient->>CFEdge: Connect to subdomain.domain.com:443
    CFEdge->>CFTunnel: Route via tunnel infrastructure
    CFTunnel->>CloudflaredContainer: Forward through encrypted tunnel
    CloudflaredContainer->>MosquittoContainer: HTTP request to mosquitto:9001
    MosquittoContainer-->>CloudflaredContainer: HTTP response
    CloudflaredContainer-->>CFTunnel: Return
    CFTunnel-->>CFEdge: Return
    CFEdge-->>ExtClient: HTTPS response on port 443
    
    Note over CloudflaredContainer,MosquittoContainer: Protocol Transformation\nExternal: HTTPS/WSS (port 443)\nInternal: HTTP/WS (port 9001)

Access Pattern

1. Outbound-Only Connection: The cloudflared container initiates a persistent outbound connection to Cloudflare’s network using the command tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN} docker-compose.yml14
2. Token Authentication: The CLOUDFLARE_TUNNEL_TOKEN environment variable docker-compose.yml17 authenticates the tunnel to Cloudflare’s infrastructure
3. Protocol Transformation: Cloudflare receives external HTTPS/WSS connections on port 443 and forwards them as HTTP to mosquitto:9001 README.md:63-67
4. DNS Routing: The public hostname configured in Cloudflare’s dashboard (e.g., subdomain.domain.com) routes to the tunnel, which forwards to the internal mosquitto:9001 service endpoint

Sources: docker-compose.yml:11-17 README.md:57-82

Configuration Mechanisms

Configuration Injection Points

The system employs two distinct configuration injection mechanisms:

Configuration Details

Token Injection: The CLOUDFLARE_TUNNEL_TOKEN is read from the .env file on the host system docker-compose.yml17 and passed to the cloudflared container as an environment variable. The token is referenced in the container’s command via shell variable substitution: --token ${CLOUDFLARE_TUNNEL_TOKEN} docker-compose.yml14

Configuration File Mounting: The mosquitto.conf file is mounted from the host filesystem into the container at /mosquitto/config/mosquitto.conf docker-compose.yml8 This allows the Mosquitto process to read its configuration without rebuilding the container image.

Sources: docker-compose.yml:7-17 README.md53

Service Restart Policies

Both services implement the restart: unless-stopped policy docker-compose.yml:9-15 which provides automatic recovery from failures:

• Automatic Restart: Containers restart automatically if they crash or exit unexpectedly
• Manual Control: Containers do not restart if explicitly stopped by docker-compose stop or docker-compose down
• System Reboot: Containers automatically start when the Docker daemon starts (unless manually stopped)

This policy ensures high availability while allowing manual intervention for maintenance operations.

Sources: docker-compose.yml:9-15

Container Lifecycle

Sources: docker-compose.yml:1-18

Communication Protocol Stack

The system implements a multi-layer protocol transformation:

Security Boundary: TLS termination occurs at Cloudflare’s edge network. The internal Docker network segment is trusted and does not require encryption, as it is isolated from external access.

Sources: README.md:63-82

Dismiss

Refresh this wiki

Enter email to refresh

Cloudflare Tunnel Setup

Loading…

Cloudflare Tunnel Configuration

Relevant source files

• .env.sample
• README.md

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

Dismiss

Refresh this wiki

Enter email to refresh

Security Model

Loading…

Security Model

Relevant source files

• .env.sample
• .gitignore
• README.md

Purpose and Scope

This document explains the security architecture of the Docker MQTT Mosquitto Cloudflare Tunnel system, including threat model, attack surface reduction, secret management, and network isolation mechanisms. It covers the security principles embedded in the system design and the trade-offs involved in the default configuration.

For operational deployment considerations including production hardening and monitoring, see Production Deployment Considerations. For authentication and access control configuration specifics, see Authentication and Access Control.

Core Security Principles

The system implements three foundational security principles:

Zero Trust Architecture

The system inverts the traditional client-server model. Instead of the MQTT broker accepting inbound connections from the internet, the cloudflared container establishes a persistent outbound connection to Cloudflare’s network. External clients never connect directly to the origin server.

Sources : README.md:17, README.md:22, README.md:67

Attack Surface Analysis

Traditional MQTT Deployment vs. Cloudflare Tunnel Deployment

Eliminated Attack Vectors

The Cloudflare Tunnel architecture eliminates entire categories of attacks:

Sources : README.md:17, Diagram 1 (High-Level System Architecture), Diagram 3 (External Access and Security Flow)

Secret Management Model

Token-Based Authentication

The CLOUDFLARE_TUNNEL_TOKEN serves as the cryptographic secret that authenticates the cloudflared container to Cloudflare’s network. This token grants the right to route traffic for the configured tunnel.

stateDiagram-v2
    [*] --> Generated : User creates tunnel in Cloudflare Dashboard
    Generated --> Copied : Token displayed in UI
    Copied --> Local : User creates .env file
    
    state Local {
        [*] --> FileCreated
        FileCreated --> TokenAdded : Paste CLOUDFLARE_TUNNEL_TOKEN=...
        TokenAdded --> GitignoreProtected : .gitignore prevents commit
    }
    
    Local --> Runtime : docker-compose reads .env
    
    state Runtime {
        [*] --> EnvLoaded
        EnvLoaded --> ContainerStarted : Environment variable injected
        ContainerStarted --> TunnelAuth : cloudflared authenticates
    }
    
    Runtime --> Operational : Tunnel established
    
    state GitignoreProtected {
        [*] --> CheckGitStatus
        CheckGitStatus --> NotTracked : .env excluded
        NotTracked --> [*]
    }
    
    Operational --> Rotated : Token rotation (manual)
    Rotated --> Generated
    
    note right of GitignoreProtected
        Critical security boundary:
        .env file must never be
        committed to version control
    end note

Secret Lifecycle

Version Control Protection

The repository implements multiple layers of protection against credential leakage:

The .gitignore file explicitly excludes the .env file containing the tunnel token:

.env
data/*

The .env.sample template provides structure without exposing actual credentials:

CLOUDFLARE_TUNNEL_TOKEN=your_token

Important : The .env.sample file is committed to version control as documentation. Operators must create their own .env file locally and populate it with their actual token.

Sources : .gitignore:1-2 .env.sample1 README.md53

Network Security Boundaries

Container Network Isolation

Security Boundaries Defined

Port Exposure Analysis

The docker-compose.yml configuration deliberately omits port mappings to the host system. Neither container exposes any ports outside the Docker bridge network:

This architectural decision ensures that:

1. The Mosquitto broker is not accessible via the host’s network interfaces
2. Port scanning of the host reveals no MQTT services
3. Firewall rules on the host are irrelevant to MQTT access
4. The only route to the broker is through the authenticated Cloudflare Tunnel

Sources : docker-compose.yml:1-19 mosquitto.conf:1-5 Diagram 2 (Docker Container Network Topology)

Authentication and Authorization

Default Configuration: Anonymous Access Allowed

The default mosquitto.conf configuration permits anonymous connections and does not enforce authentication:

listener 1883
protocol mqtt

listener 9001
protocol websockets

Security Implication : Any client that can reach the broker (via the Cloudflare Tunnel) can publish and subscribe to any topic without authentication.

graph LR
    Client["Client with URL"]
subgraph CloudflareLayer["Cloudflare Layer - Transport Security"]
TLS["TLS Termination\nCertificate validation"]
WAF["Web Application Firewall\nOptional rules"]
end
    
    subgraph MQTTLayer["MQTT Layer - Application Security"]
Anonymous["Anonymous access permitted\nNo username/password required"]
NoACL["No topic-level restrictions\nFull pub/sub access"]
end
    
 
   Client -->|HTTPS connection| TLS
 
   TLS -->|Decrypted, inspected| WAF
 
   WAF -->|Forwarded if allowed| Anonymous
 
   Anonymous -->|All operations permitted| NoACL
    
 
   NoACL -->|Can publish to any topic| Topics["All MQTT Topics"]
NoACL -->|Can subscribe to any topic| Topics

Access Control Model

Security Trade-offs

Enhanced Security Branch

The repository includes an alternate configuration branch (protected-no-wildcard) that implements:

1. Topic-based Access Control : ACL file restricts wildcard subscriptions and enforces username-based topic prefixes
2. Encrypted Retained Messages : Uses gocryptfs to encrypt persistent message storage
3. Auto-save retained messages : Ensures message persistence

This branch demonstrates production-grade security hardening. See Protected Branch Features for details.

Sources : mosquitto.conf:1-5 README.md:7-13

TLS and Encryption

Multi-layer Encryption Architecture

Encryption Scope

Rationale for unencrypted internal segment : The traffic between cloudflared and mosquitto occurs entirely within the Docker bridge network, which is isolated from external networks. Adding TLS to this segment would:

• Increase CPU overhead without security benefit
• Require certificate management for internal services
• Complicate debugging and troubleshooting

Sources : README.md:67-68 docker-compose.yml13 Diagram 3 (External Access and Security Flow)

Operational Security Considerations

Token Rotation

The CLOUDFLARE_TUNNEL_TOKEN does not automatically expire. Best practices for production deployments:

1. Periodic rotation : Rotate tokens on a scheduled basis (e.g., quarterly)
2. Incident response : Immediately rotate if token exposure is suspected
3. Access logging : Monitor Cloudflare logs for tunnel usage patterns

Secret Storage in Production

The .env file approach is suitable for development but should be replaced in production:

Container Image Security

Both containers use official images from trusted registries:

• eclipse-mosquitto:latest - Official Eclipse Foundation image
• cloudflare/cloudflared:latest - Official Cloudflare image

Recommendation : Pin specific image versions rather than using latest to ensure reproducible deployments and controlled updates:

Sources : docker-compose.yml:3-4 docker-compose.yml:11-12

Threat Model Summary

Mitigated Threats

Residual Risks

Defense-in-Depth Layers

The system implements multiple independent security layers. An attacker must bypass all layers to compromise the system:

1. Layer 1 - Cloudflare Edge : DDoS protection, rate limiting, WAF rules
2. Layer 2 - Tunnel Authentication : Valid tunnel token required
3. Layer 3 - Network Isolation : No direct route to containers from external networks
4. Layer 4 - Application Security : Mosquitto’s internal security (minimal in default config)
5. Layer 5 - Secret Management : .gitignore prevents token leakage through version control

Sources : .gitignore:1-2 README.md82 Diagram 1 (High-Level System Architecture), Diagram 6 (Data and Secret Flow)

Dismiss

Refresh this wiki

Enter email to refresh

Local Configuration

Loading…

Local Configuration

Relevant source files

• .env.sample
• .gitignore
• mosquitto.conf

Purpose and Scope

This document guides you through setting up the local configuration files required to deploy the Docker MQTT Mosquitto with Cloudflare Tunnel system. This includes creating the environment variable file (.env) and understanding the Mosquitto broker configuration (mosquitto.conf).

This page assumes you have already completed the Cloudflare Tunnel Setup and obtained your CLOUDFLARE_TUNNEL_TOKEN. For deployment instructions after configuration is complete, see Deployment.

Configuration Files Overview

The system requires two primary configuration files:

Diagram: Configuration File Relationships

Sources: .env.sample1 .gitignore:1-2 mosquitto.conf:1-6

Environment Variable Configuration

Creating the .env File

The .env file stores sensitive configuration that must never be committed to version control. The repository includes .env.sample1 as a template.

Step 1: Copy the template

Step 2: Populate the token

Edit the .env file and replace your_token with the actual CLOUDFLARE_TUNNEL_TOKEN obtained from the Cloudflare dashboard during Cloudflare Tunnel Setup:

CLOUDFLARE_TUNNEL_TOKEN=eyJhIjoiYWJjMTIzLi4uLnJlYWxfdG9rZW5faGVyZSJ9

Environment Variable Reference

Diagram: Environment Variable Flow to Containers

Sources: .env.sample1

Security Verification

The .gitignore1 file explicitly excludes .env from version control:

.env
data/*

Verify.env is excluded:

If .env appears in git status output, verify that .gitignore1 is present and contains the correct exclusion rule.

Sources: .gitignore:1-2

Mosquitto Broker Configuration

The mosquitto.conf file configures the Eclipse Mosquitto MQTT broker. This file is committed to version control as it contains no secrets.

Listener Configuration

The mosquitto.conf:1-6 file defines two protocol listeners:

Diagram: Mosquitto Listener Configuration

graph TB
    mosq_conf["mosquitto.conf"]
listener_1883["listener 1883\nStandard MQTT protocol"]
listener_9001["listener 9001\nWebSocket protocol"]
allow_anon["allow_anonymous true\nNo authentication required"]
mosq_conf -->|Line 1| listener_1883
 
   mosq_conf -->|Line 2| allow_anon
 
   mosq_conf -->|Lines 4-5| listener_9001
    
 
   listener_1883 -.->|Used by| mqtt_clients["Native MQTT clients\nIoT devices"]
listener_9001 -.->|Used by| ws_clients["WebSocket clients\nBrowsers, web apps"]

Sources: mosquitto.conf:1-6

Configuration Directives

Protocol Explanation

Port 1883: Native MQTT

• Binary MQTT protocol (MQTT v3.1.1 / v5.0)
• Used by: IoT devices, MQTT client libraries, native applications
• Routed through Cloudflare Tunnel as-is (protocol preservation)

Port 9001: MQTT over WebSockets

• MQTT protocol encapsulated in WebSocket frames
• Used by: Browser-based clients, web applications
• Required for environments without raw TCP socket support
• Cloudflare routes this as standard HTTP/WebSocket traffic

Diagram: Configuration File to Container Mount

graph LR
    host_fs["Host Filesystem\n./mosquitto.conf"]
compose_volume["docker-compose.yml\nvolumes:\n./mosquitto.conf:/mosquitto/config/mosquitto.conf"]
container_fs["mosquitto container\n/mosquitto/config/mosquitto.conf"]
mosq_process["Mosquitto process\nreads config on startup"]
host_fs -->|1. Volume mount defined| compose_volume
 
   compose_volume -->|2. Bind mounted| container_fs
 
   container_fs -->|3. Loaded by| mosq_process
 
   mosq_process -->|4. Opens listeners| ports["Port 1883\nPort 9001"]

Sources: mosquitto.conf:1-6

graph TB
    subgraph "Host System"
        env_file[".env\nCLOUDFLARE_TUNNEL_TOKEN=..."]
mosq_conf["mosquitto.conf\nlistener 1883\nlistener 9001"]
end
    
    subgraph "docker-compose.yml"
        compose_env["environment:\nCLOUDFLARE_TUNNEL_TOKEN"]
compose_volume["volumes:\n./mosquitto.conf:/mosquitto/config/mosquitto.conf"]
end
    
    subgraph "Containers"
        cloudflared_container["cloudflared\nEnvironment: CLOUDFLARE_TUNNEL_TOKEN\nCommand: tunnel run"]
mosquitto_container["mosquitto\nMounted: /mosquitto/config/mosquitto.conf\nReads config on startup"]
end
    
 
   env_file -->|Loaded by Docker Compose| compose_env
 
   mosq_conf -->|Volume definition| compose_volume
    
 
   compose_env -->|Injected as env var| cloudflared_container
 
   compose_volume -->|Bind mounted| mosquitto_container
    
 
   cloudflared_container -->|Authenticates with| cf_network["Cloudflare Network"]
mosquitto_container -->|Opens listeners| listeners["1883: MQTT\n9001: WebSocket"]

Configuration Flow to Containers

When Docker Compose starts the system, configuration is injected into containers through two mechanisms:

Diagram: Complete Configuration Injection Flow

Sources: .env.sample1 mosquitto.conf:1-6

Security Best Practices

Secret Management Checklist

Before proceeding to Deployment, verify the following security measures:

Common Configuration Mistakes

Mistake 1: Committing.env to Git

The .gitignore1 file prevents this, but if you modify .gitignore, ensure .env remains excluded:

Mistake 2: Missing Token in.env

If .env.sample1 placeholder remains:

CLOUDFLARE_TUNNEL_TOKEN=your_token  # WRONG - must be actual token

The cloudflared container will fail to authenticate. Verify token format (JWT-like structure starting with eyJ).

Mistake 3: Incorrect File Permissions

The .env file should be readable by the Docker daemon but protected from other users:

Sources: .gitignore:1-2 .env.sample1

Configuration Validation

Before proceeding to deployment, validate your configuration:

1. Environment Variables

2. Mosquitto Configuration Syntax

The Mosquitto configuration syntax can be pre-validated (requires mosquitto installed locally):

If mosquitto is not installed locally, syntax validation will occur during container startup in Deployment.

3. File Structure Verification

Expected repository structure after configuration:

docker-mqtt-mosquitto-cloudflare-tunnel/
├── .env                    # Created by you, contains token
├── .env.sample             # Repository template
├── .gitignore              # Excludes .env
├── docker-compose.yml      # Orchestration configuration
├── mosquitto.conf          # MQTT broker configuration
└── README.md

Sources: .env.sample1 mosquitto.conf:1-6 .gitignore:1-2

Next Steps

With local configuration complete:

1. Environment Variables : .env file created with valid CLOUDFLARE_TUNNEL_TOKEN
2. Mosquitto Configuration : mosquitto.conf defines listeners on ports 1883 and 9001
3. Security : .env excluded from version control via .gitignore1

Proceed to Deployment to start the containerized services using Docker Compose.

For detailed configuration reference, see Configuration Reference.

For understanding how these configurations map to Docker containers, see Docker Compose Orchestration.

Sources: .env.sample1 mosquitto.conf:1-6 .gitignore:1-2

Dismiss

Refresh this wiki

Enter email to refresh

Deployment

Loading…

Deployment

Relevant source files

• README.md
• docker-compose.yml

This page covers the process of deploying the Docker MQTT Mosquitto with Cloudflare Tunnel system using Docker Compose. It assumes you have completed the Cloudflare Tunnel setup (see Cloudflare Tunnel Setup) and local configuration (see Local Configuration). For production deployment considerations, see Production Deployment Considerations. For detailed troubleshooting, see Troubleshooting.

Starting the System

With the .env file configured and mosquitto.conf in place, deploy the system using Docker Compose:

This command starts both the mosquitto and cloudflared containers as defined in docker-compose.yml:3-17 The command runs in the foreground, displaying logs from both containers in real-time.

Deployment Modes

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

Deployment Sequence

The following sequence diagram shows the complete deployment lifecycle from command execution to operational state:

Deployment Initialization Flow

sequenceDiagram
    participant User
    participant DockerCompose as "docker-compose\n(Orchestrator)"
    participant DockerEngine as "Docker Engine"
    participant MosqContainer as "mosquitto\n(Container)"
    participant CFDContainer as "cloudflared\n(Container)"
    participant CFTunnel as "Cloudflare Tunnel\n(Service)"
    participant MosqProcess as "Mosquitto Process\n(MQTT Broker)"
    
    User->>DockerCompose: docker compose up
    DockerCompose->>DockerEngine: Parse docker-compose.yml
    DockerEngine->>DockerEngine: Create bridge network
    
    Note over DockerEngine,MosqContainer: Start mosquitto service
    DockerEngine->>MosqContainer: Pull eclipse-mosquitto:latest
    DockerEngine->>MosqContainer: Create container
    DockerEngine->>MosqContainer: Mount ./mosquitto.conf to /mosquitto/config/
    MosqContainer->>MosqProcess: Start mosquitto daemon
    MosqProcess->>MosqProcess: Read /mosquitto/config/mosquitto.conf
    MosqProcess->>MosqProcess: Bind listener on port 1883
    MosqProcess->>MosqProcess: Bind listener on port 9001 (websockets)
    MosqProcess-->>DockerEngine: Container running
    
    Note over DockerEngine,CFDContainer: Start cloudflared service
    DockerEngine->>CFDContainer: Pull cloudflare/cloudflared:latest
    DockerEngine->>CFDContainer: Create container
    DockerEngine->>CFDContainer: Inject CLOUDFLARE_TUNNEL_TOKEN from .env
    CFDContainer->>CFDContainer: Execute: tunnel --no-autoupdate run --token
    CFDContainer->>CFTunnel: Establish tunnel connection
    CFTunnel-->>CFDContainer: Tunnel established
    CFDContainer->>CFDContainer: Resolve mosquitto via DNS
    CFDContainer-->>DockerEngine: Container running
    
    DockerEngine-->>DockerCompose: Both services started
    DockerCompose-->>User: Display container logs
    
    Note over User,MosqProcess: System operational

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

Container Startup Behavior

Each service defined in docker-compose.yml:3-17 has specific startup characteristics:

mosquitto Container

The mosquitto container starts with the following configuration:

• Image: eclipse-mosquitto:latest (docker-compose.yml5)
• Container Name: mosquitto (docker-compose.yml6)
• Volume Mount: ./mosquitto.conf → /mosquitto/config/mosquitto.conf (docker-compose.yml:7-8)
• Restart Policy: unless-stopped (docker-compose.yml9)

Upon startup, the Mosquitto process reads the mounted configuration file and initializes two listeners as specified in mosquitto.conf.

cloudflared Container

The cloudflared container starts with the following configuration:

• Image: cloudflare/cloudflared:latest (docker-compose.yml12)
• Container Name: cloudflared (docker-compose.yml13)
• Command: tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN} (docker-compose.yml14)
• Environment: CLOUDFLARE_TUNNEL_TOKEN injected from .env (docker-compose.yml:16-17)
• Restart Policy: unless-stopped (docker-compose.yml15)

The --no-autoupdate flag prevents the container from attempting to update itself, maintaining version consistency with the Docker image.

Sources: docker-compose.yml:3-18

Verifying Deployment

After starting the system, verify that both containers are running and the tunnel is operational.

Container Status Verification Flow

graph TD
    Start["Deployment Started"]
CheckContainers["docker compose ps"]
VerifyStatus{"Both containers\nSTATUS=Up?"}
CheckLogs["docker compose logs"]
VerifyMosquitto{"Mosquitto logs show\nlisteners bound?"}
VerifyCloudflared{"Cloudflared logs show\ntunnel registered?"}
TestConnection["Test MQTT connection\nto public hostname"]
Success["Deployment Verified"]
Failure["Deployment Failed"]
Start --> CheckContainers
 
   CheckContainers --> VerifyStatus
 
   VerifyStatus -->|No| Failure
 
   VerifyStatus -->|Yes| CheckLogs
 
   CheckLogs --> VerifyMosquitto
 
   VerifyMosquitto -->|No| Failure
 
   VerifyMosquitto -->|Yes| VerifyCloudflared
 
   VerifyCloudflared -->|No| Failure
 
   VerifyCloudflared -->|Yes| TestConnection
 
   TestConnection -->|Connection successful| Success
 
   TestConnection -->|Connection failed| Failure

Sources: README.md:82-84

Check Container Status

List running containers and their status:

Expected output should show both containers with STATUS as Up:

Sources: docker-compose.yml:4-17

View Container Logs

View logs from all services:

View logs from a specific service:

Follow logs in real-time:

Expected Mosquitto Logs

Successful Mosquitto startup logs include:

mosquitto    | 1234567890: mosquitto version X.X.X starting
mosquitto    | 1234567890: Config loaded from /mosquitto/config/mosquitto.conf
mosquitto    | 1234567890: Opening ipv4 listen socket on port 1883.
mosquitto    | 1234567890: Opening websockets listen socket on port 9001.
mosquitto    | 1234567890: mosquitto version X.X.X running

Expected Cloudflared Logs

Successful tunnel connection logs include:

cloudflared  | Registered tunnel connection
cloudflared  | Connection <UUID> registered connIndex=0
cloudflared  | Route propagating

Sources: docker-compose.yml:1-18

Verify Public Accessibility

After deployment, the MQTT broker is accessible at https://<subdomain>.<domain>:443, where the subdomain and domain are configured in the Cloudflare Tunnel public hostname settings (see Cloudflare Tunnel Setup).

Important: The broker is not directly accessible on ports 1883 or 9001 from the public internet. All traffic is routed through Cloudflare’s network on port 443 using HTTPS/WSS protocols. Internal container communication uses HTTP on port 9001.

Sources: README.md:82-84

Container Lifecycle Management

Container State Transitions

Sources: docker-compose.yml:9-15

Stopping the System

Stop all containers while preserving their state:

This sends a SIGTERM signal to each container, allowing graceful shutdown. Containers can be restarted with docker compose start.

Sources: docker-compose.yml:1-18

Removing the Deployment

Stop and remove all containers, networks, and anonymous volumes:

This completely tears down the deployment. The next docker compose up will create fresh containers.

To also remove named volumes (use with caution):

Sources: docker-compose.yml:1-18

Restarting Services

Restart all services:

Restart a specific service:

Sources: docker-compose.yml:4-17

Viewing Live Container Processes

Inspect running processes inside containers:

This displays process information for each running container.

Executing Commands in Containers

Execute a command in a running container:

This opens an interactive shell inside the specified container. Useful for debugging and inspecting the container’s filesystem.

Sources: docker-compose.yml:6-13

Deployment Verification Checklist

Use this checklist to confirm successful deployment:

• .env file exists with valid CLOUDFLARE_TUNNEL_TOKEN
• mosquitto.conf file exists in the project root
• docker compose ps shows both containers with STATUS: Up
• docker compose logs mosquitto shows listeners bound on ports 1883 and 9001
• docker compose logs cloudflared shows tunnel registered and connection established
• Public hostname resolves to Cloudflare’s network
• MQTT client can connect to https://<subdomain>.<domain>:443

Sources: README.md:74-84 docker-compose.yml:1-18

Common Deployment Issues

This section provides brief guidance on common deployment failures. For comprehensive troubleshooting, see Troubleshooting.

Sources: README.md84 docker-compose.yml:1-18

Restart Policy Behavior

Both containers are configured with restart: unless-stopped (docker-compose.yml:9-15), which provides automatic recovery:

• Container Crash: Automatically restarts
• Docker Daemon Restart: Automatically restarts (unless manually stopped)
• Manual Stop: Does not automatically restart until explicitly started

This policy ensures high availability without manual intervention after transient failures or system reboots.

Sources: docker-compose.yml:9-15

Next Steps

After successful deployment:

1. Test MQTT connectivity using an MQTT client (see Testing Connection)
2. Review component documentation (see Components)
3. Implement monitoring (see Monitoring and Health Checks)
4. Consider production hardening (see Production Deployment Considerations)

Sources: README.md:82-84

Dismiss

Refresh this wiki

Enter email to refresh

Components

Loading…

Components

Relevant source files

• docker-compose.yml

This document provides detailed technical documentation of the major components that constitute the Docker MQTT Mosquitto Cloudflare Tunnel system. Each component is examined in terms of its Docker service configuration, runtime behavior, and integration with other system components.

For architectural overview and how these components interact at a system level, see System Architecture. For deployment instructions, see Deployment. For advanced branch-specific features like ACLs and encryption, see Advanced Topics.

Component Overview

The system consists of three primary components orchestrated by Docker Compose:

Component Interaction Diagram

Sources : docker-compose.yml, README.md, mosquitto.conf

Mosquitto MQTT Broker

The Mosquitto service provides MQTT protocol brokering functionality. This component runs the Eclipse Mosquitto broker inside a Docker container, configured for WebSocket and TCP connections with anonymous access enabled.

Service Definition

The Mosquitto service is defined in docker-compose.yml:4-9 with the following configuration:

The container name mosquitto is critical as it serves as the internal DNS hostname that cloudflared uses to proxy traffic (referenced in Cloudflare tunnel configuration as mosquitto:9001).

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

graph LR
    subgraph MosquittoContainer["mosquitto Container"]
subgraph ListenerConfig["mosquitto.conf Configuration"]
Listener1["listener 1883\nprotocol mqtt"]
Listener2["listener 9001\nprotocol websockets"]
end
        
        subgraph BrokerCore["Mosquitto Broker Process"]
MQTTEngine["MQTT Protocol Engine"]
end
        
 
       Listener1 -->|standard TCP/IP| MQTTEngine
 
       Listener2 -->|WebSocket framing| MQTTEngine
    end
    
    subgraph ExternalAccess["External Access Paths"]
TCPClient["TCP MQTT Clients\n(port 1883)"]
WSClient["WebSocket Clients\n(via cloudflared proxy)"]
end
    
 
   TCPClient -.->|internal network only not exposed via tunnel| Listener1
 
   WSClient -->|proxied through cloudflared:mosquitto:9001| Listener2

MQTT Listeners

The Mosquitto broker is configured with two distinct listeners, each serving different client connection patterns:

Listener Configuration Overview

Sources : mosquitto.conf, README.md:62, docker-compose.yml:4-9

Standard TCP Listener (Port 1883)

Configured in mosquitto.conf as:

listener 1883
protocol mqtt

This listener provides standard MQTT-over-TCP connectivity on the default MQTT port. It is accessible within the Docker internal network but is not exposed through the Cloudflare tunnel in the default configuration.

Use cases :

• Direct connections from other Docker containers on the same network
• Internal service-to-service MQTT communication
• Local development and testing

WebSocket Listener (Port 9001)

Configured in mosquitto.conf as:

listener 9001
protocol websockets

This listener provides MQTT-over-WebSocket connectivity, which is the primary listener exposed through the Cloudflare tunnel. The cloudflared service proxies external traffic to mosquitto:9001 as configured in the Cloudflare Zero Trust dashboard.

Use cases :

• Browser-based MQTT clients
• Web applications requiring MQTT connectivity
• Clients behind restrictive firewalls that block non-HTTP protocols
• The primary access method for external clients via Cloudflare tunnel

Sources : mosquitto.conf, README.md:55-66

Anonymous Access

The Mosquitto broker is configured with anonymous access enabled, meaning no authentication is required to connect or publish/subscribe to topics.

Configuration :

allow_anonymous true

This setting in mosquitto.conf permits any client that can reach the broker to perform MQTT operations without credentials.

Security implications :

The security model assumes that network-level access control (via Cloudflare tunnel) provides sufficient protection. For environments requiring topic-level access control, see Topic Access Control (ACL) which documents the protected-no-wildcard branch implementation.

Sources : mosquitto.conf, README.md:5-11

Cloudflared Tunnel Service

The cloudflared service establishes a secure, outbound-only connection to Cloudflare’s network, enabling external MQTT clients to reach the internal Mosquitto broker without exposing inbound ports on the host.

Service Definition

The cloudflared service is defined in docker-compose.yml:11-17:

Sources : docker-compose.yml:11-17

Tunnel Authentication and Establishment

Tunnel Connection Flow

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

Command Line Arguments

The command directive in docker-compose.yml14 specifies:

tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}

The token is obtained during tunnel creation in the Cloudflare Zero Trust dashboard (see Cloudflare Tunnel Configuration) and stored in the .env file as documented in .env.sample

Sources : docker-compose.yml:14, .env.sample, README.md:47-53

Traffic Proxying

Once the tunnel is established, cloudflared proxies incoming traffic from Cloudflare’s edge to the internal Mosquitto broker. The routing configuration is managed in the Cloudflare Zero Trust dashboard, not in local configuration files.

The public hostname configuration in Cloudflare maps to the service URL mosquitto:9001, where:

• mosquitto resolves via Docker’s internal DNS to the container with container_name: mosquitto
• Port 9001 corresponds to the WebSocket listener configured in mosquitto.conf

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

Docker Compose Orchestration

Docker Compose provides service orchestration, dependency management, and configuration binding for the system.

Service Orchestration Model

Docker Compose Component Relationships

Sources : docker-compose.yml

Network Configuration

Docker Compose creates a default bridge network for service communication. The network configuration is implicit (no explicit networks section in docker-compose.yml).

Network characteristics :

The internal DNS resolution is critical: when the Cloudflare tunnel configuration specifies mosquitto:9001, Docker’s embedded DNS server resolves mosquitto to the IP address of the container with container_name: mosquitto.

Sources : docker-compose.yml, README.md:62

Volume Management

The Mosquitto service uses a bind mount to inject configuration:

Volume mapping details :

The configuration file is read by the Mosquitto broker on startup. Changes to mosquitto.conf require container restart to take effect:

No data persistence volumes are configured in the default setup. For persistent message storage, see Advanced Topics and the protected-no-wildcard branch documentation.

Sources : docker-compose.yml:7-8, mosquitto.conf

Environment Variable Injection

The cloudflared service receives environment variables via docker-compose.yml:16-17:

This syntax instructs Docker Compose to:

1. Read CLOUDFLARE_TUNNEL_TOKEN from the .env file in the same directory
2. Pass it as an environment variable to the cloudflared container
3. Make it available for substitution in the command directive via ${CLOUDFLARE_TUNNEL_TOKEN}

The .env file is not version-controlled (excluded via .gitignore). Developers create it from .env.sample as documented in Environment Variables.

Sources : docker-compose.yml:16-17, .env.sample

Restart Policies

Both services use restart: unless-stopped:

Restart behavior :

This policy ensures service availability while allowing manual control via docker compose down or docker stop.

Sources : docker-compose.yml:9,15

Service Lifecycle Management

Common Docker Compose Commands :

For detailed deployment procedures, see Deployment.

Sources : docker-compose.yml, README.md:68-72

Dismiss

Refresh this wiki

Enter email to refresh

MQTT Protocol Listeners

Loading…

MQTT Protocol Listeners

Relevant source files

• mosquitto.conf

Purpose and Scope

This document describes the MQTT listener configuration in the Mosquitto broker, specifically the two listeners defined in mosquitto.conf:1-6 It explains the purpose, protocol, and routing behavior of each listener. For broader Mosquitto broker configuration, see Mosquitto Configuration. For access control settings, see Anonymous Access. For Cloudflare tunnel routing configuration, see Cloudflared Tunnel Service.

Sources : mosquitto.conf, README.md

Listener Configuration Overview

The Mosquitto broker is configured with two distinct listeners, each serving different transport protocols and use cases. Both listeners are defined in mosquitto.conf:1-6 and operate simultaneously within the mosquitto container.

<old_str>

TCP Listener"] end 
    
    
    subgraph external["External Network"]
        Internet["Public Internet"]
    end
    
    OtherContainer -->|"Direct MQTT/TCP"| MosquittoPort1883
    Internet -.->|"Not Accessible"| MosquittoPort1883
    
    
    
    **Listener Configuration Structure**
    
    | Listener | Port | Protocol | Anonymous Access | Primary Use Case |
    |----------|------|----------|------------------|------------------|
    | <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef> | 1883 | Standard MQTT/TCP | Enabled globally <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef> | Direct MQTT client connections |
    | <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5" min=4 max=5 file-path="mosquitto.conf">Hii</FileRef> | 9001 | MQTT over WebSockets | Enabled globally <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef> | Browser-based clients, Cloudflare tunnel |
    
    **Sources**: mosquitto.conf
    
    ---
    
    ## Listener 1883: Standard MQTT TCP
    
    The first listener, configured at <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef> binds to port 1883 and provides standard MQTT protocol over TCP. This is the default MQTT port and is used by most native MQTT client libraries.
    
    ### Configuration Directives
    
    

listener 1883 allow_anonymous true
    
    
    **Directive Breakdown**:
    - `listener 1883` <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1" min=1  file-path="mosquitto.conf">Hii</FileRef>: Binds the Mosquitto broker to TCP port 1883
    - `allow_anonymous true` <FileRef file-url="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2" min=2  file-path="mosquitto.conf">Hii</FileRef>: Applies globally to all listeners, allowing clients to connect without authentication
    
    ### Protocol Characteristics
    
    This listener implements the standard MQTT 3.1.1 and MQTT 5.0 protocols over raw TCP connections. It supports:
    - Binary MQTT protocol framing
    - Persistent TCP connections
    - Quality of Service (QoS) levels 0, 1, and 2
    - Last Will and Testament (LWT) messages
    - Retained messages
    
    ### Network Accessibility
    
    The 1883 listener is **not** directly exposed through the Cloudflare tunnel in the current configuration. It operates only within Docker's internal network, accessible to other containers in the same Docker Compose stack.
    
    ```mermaid
    graph LR
        subgraph "Docker Internal Network"
            OtherContainer["Other Docker Container"]
            MosquittoPort1883["mosquitto:1883<br/>TCP Listener"]
        end
        
        subgraph "External Network"
            Internet["Public Internet"]
        end
        
        OtherContainer -->|"Direct MQTT/TCP"| MosquittoPort1883
        Internet -.->|"Not Accessible"| MosquittoPort1883
    

**Sources** : mosquitto.conf, README.md

* * *

## Listener 9001: MQTT over WebSockets

The second listener, configured at [mosquitto.conf:4-5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5) binds to port 9001 and provides MQTT protocol encapsulated over WebSockets. This is the primary listener exposed to external clients via the Cloudflare tunnel.

### Configuration Directives
    
    
    listener 9001
    protocol websockets
    

**Directive Breakdown** :

  * `listener 9001` [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4): Binds the Mosquitto broker to TCP port 9001
  * `protocol websockets` [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5): Configures this listener to accept WebSocket connections with MQTT payloads



### Protocol Characteristics

This listener encapsulates MQTT protocol messages within WebSocket frames, enabling:

  * HTTP/WebSocket upgrade handshake
  * Browser-based MQTT clients (JavaScript)
  * Compatibility with web proxies and CDNs
  * TLS/SSL termination at the proxy layer (Cloudflare)



The WebSocket protocol wrapper does not alter the MQTT protocol itself; it only provides an HTTP-compatible transport layer.

### Cloudflare Tunnel Routing

The 9001 listener is configured as the target for the Cloudflare tunnel in the Zero Trust dashboard. The tunnel configuration specifies `mosquitto:9001` as the service URL [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62) routing external MQTT WebSocket connections through the `cloudflared` container to this listener.


### Network Accessibility

Unlike the 1883 listener, the 9001 listener is indirectly exposed to the public internet through the Cloudflare tunnel. The routing path is:

  1. External client connects to Cloudflare public hostname
  2. Cloudflare Edge routes to `cloudflared` container via tunnel
  3. `cloudflared` proxies HTTP traffic to `mosquitto:9001`
  4. Mosquitto 9001 listener accepts WebSocket connection



**Sources** : mosquitto.conf, README.md

* * *

## Traffic Routing Architecture

The following diagram illustrates how traffic is routed to each listener based on the source and transport protocol:


**Routing Configuration References** :

  * Cloudflare tunnel target: `mosquitto:9001` [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62)
  * WebSocket listener: [mosquitto.conf:4-5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L5)
  * TCP listener: [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1)
  * Container name resolution: `mosquitto` from `docker-compose.yml`



**Sources** : mosquitto.conf, README.md

* * *

## Configuration Reference

### Listener Directive Syntax

The `listener` directive defines a network interface and port for the broker to bind to:
    
    
    listener <port> [bind_address]
    

**Current Configuration** :

  * [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1): `listener 1883` \- Binds to port 1883 on all interfaces (no bind_address specified)
  * [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4): `listener 9001` \- Binds to port 9001 on all interfaces



### Protocol Directive

The `protocol` directive specifies the transport protocol for a listener:
    
    
    protocol <mqtt|websockets>
    

**Current Configuration** :

  * Listener 1883: No protocol directive (defaults to `mqtt`)
  * [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5): `protocol websockets` \- Configures listener 9001 for WebSocket transport



### Anonymous Access Directive

The `allow_anonymous` directive controls whether clients can connect without authentication:
    
    
    allow_anonymous <true|false>
    

**Current Configuration** :

  * [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2): `allow_anonymous true` \- Applies globally to all listeners



This directive appears once and affects both listeners. For production deployments requiring authentication, this should be set to `false` and appropriate authentication mechanisms configured. See [Anonymous Access](2-1-2-authentication-and-access-control.md) for detailed security implications.

### Configuration Interaction Matrix

Configuration Aspect| Listener 1883| Listener 9001  
---|---|---  
**Port**|  1883 [mosquitto.conf1](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L1-L1)| 9001 [mosquitto.conf4](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L4-L4)  
**Protocol**|  MQTT/TCP (implicit default)| WebSockets [mosquitto.conf5](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L5-L5)  
**Anonymous Access**|  Enabled [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2)| Enabled [mosquitto.conf2](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/mosquitto.conf#L2-L2)  
**Cloudflare Routing**|  Not configured| Configured [README.md62](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L62-L62)  
**External Accessibility**|  Docker internal only| Via Cloudflare tunnel  
  
**Sources** : mosquitto.conf, README.md

* * *

## Use Case Selection

### When to Use Listener 1883 (TCP)

  * **Native MQTT client libraries** : Python Paho, Mosquitto C library, MQTT.js with TCP
  * **High-performance IoT devices** : Minimal protocol overhead
  * **Internal Docker services** : Direct container-to-container communication
  * **Legacy MQTT applications** : Standard MQTT port compatibility



### When to Use Listener 9001 (WebSockets)

  * **Browser-based clients** : JavaScript MQTT clients in web applications
  * **Cloudflare tunnel access** : External clients connecting via the public hostname
  * **Firewall-restricted networks** : HTTP/WebSocket traffic often allowed through corporate firewalls
  * **CDN/proxy compatibility** : Works with HTTP-based reverse proxies



### Current System Configuration

The current deployment configures the Cloudflare tunnel to route exclusively to listener 9001. This means:

  * External clients **must** use MQTT over WebSockets
  * The public hostname [README.md60](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/README.md#L60-L60) resolves to listener 9001
  * Listener 1883 remains available only for internal Docker network access



To expose listener 1883 externally, additional Cloudflare tunnel configuration would be required, though this is uncommon since WebSocket transport provides broader compatibility.

**Sources** : mosquitto.conf, README.md

Dismiss

Refresh this wiki

Enter email to refresh
<hr style="margin-top: 3rem; border: none; border-top: 1px solid #e0e0e0;">

<div class="doc-footer" style="text-align: center; padding: 1.5rem 0; color: #666">
  <p style="margin: 0;">Documentation generated on January 04, 2026 at 00:40 UTC</p>
  
  <p style="margin: 0.5rem 0 0 0;">
    <a href="https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel" rel="noopener noreferrer" style="color: #667eea; text-decoration: none;">jzombie/docker-mqtt-mosquitto-cloudflare-tunnel</a>
  </p>
  
</div>

Authentication and Access Control

Loading…

Authentication and Access Control

Relevant source files

• README.md
• mosquitto.conf

This document explains the authentication and access control mechanisms available for the Mosquitto MQTT broker. The current configuration uses anonymous access, allowing any client that can reach the broker to connect without credentials. This page covers the implementation details, security implications, and alternative authentication strategies.

The Mosquitto broker supports multiple authentication methods:

• Anonymous Access : No credentials required (current configuration)
• Username/Password Authentication : Credential-based access control with password files
• Access Control Lists (ACLs) : Topic-level permissions based on usernames
• Plugin-Based Authentication : Custom authentication mechanisms via plugins

For the complete system security architecture, see Security Model. For advanced authentication configurations, see Protected Branch Features.

Current Configuration: Anonymous Access

The Mosquitto broker in this repository is configured for anonymous access, meaning no authentication is required for client connections. This is controlled by a single directive in the configuration file.

Configuration Location

The anonymous access setting is defined in mosquitto.conf2:

allow_anonymous true

This directive applies globally to all listeners defined in the configuration file. In this system, anonymous access affects both the standard MQTT listener on port 1883 and the WebSocket listener on port 9001 (see MQTT Protocol Listeners for details on these listeners).

Whatallow_anonymous true Means

Sources: mosquitto.conf

Anonymous Access Connection Flow

Connection Flow Diagram

When allow_anonymous true is set in mosquitto.conf2 the Mosquitto broker accepts MQTT CONNECT packets regardless of whether they contain username/password credentials. The broker does not perform any authentication checks and immediately grants access to all MQTT operations.

Authentication Decision Logic

Sources: mosquitto.conf, README.md

Access Permissions with Anonymous Access

Unrestricted Topic Access

With allow_anonymous true and no ACL file configured in mosquitto.conf clients have unrestricted access:

Authentication Check Flow

Sources: mosquitto.conf

Security Implications

Trust Boundary Analysis

The security model for this configuration relies entirely on network-level access control rather than application-level authentication:

Sources: mosquitto.conf, README.md

Threat Model Considerations

What Anonymous Access Protects Against:

• Direct internet exposure (mitigated by Cloudflare Tunnel)
• Port scanning and direct connection attempts (no inbound firewall rules required)
• DDoS attacks at the network level (handled by Cloudflare Edge)

What Anonymous Access Does NOT Protect Against:

• Unauthorized message publication by any client that reaches the broker
• Eavesdropping on topics by any connected client
• Malicious clients subscribing to all topics using # wildcard
• Topic flooding or message spam from authenticated clients
• Multi-tenant isolation (all clients can access all topics)

Sources: README.md

Appropriate Use Cases

When Anonymous Access Is Suitable

Anonymous access is appropriate in the following scenarios:

When Authentication Is Required

Authentication should be implemented when:

• Multiple users need isolated topic spaces
• Different clients require different permission levels
• Production deployments with untrusted client access
• Compliance or audit requirements mandate access control
• Topic-level security policies need enforcement
• Multi-tenant systems require user isolation

For these scenarios, see the alternative implementation in the [protected-no-wildcard branch](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/protected-no-wildcard branch) which provides username/password authentication and ACL-based topic restrictions. Detailed documentation is available at Protected Branch Features.

Sources: README.md

Configuration File Structure

The complete Mosquitto configuration from mosquitto.conf:1-5:

listener 1883
allow_anonymous true

listener 9001
protocol websockets

Configuration Analysis

Key Observations

• The allow_anonymous true directive applies globally to both listeners
• No password_file directive is present
• No acl_file directive is present
• No allow_anonymous override on individual listeners
• This creates a uniform anonymous access policy across MQTT and WebSocket protocols

Sources: mosquitto.conf

graph TB
    ComposeFile["docker-compose.yml"]
MosqConf["mosquitto.conf"]
MosqContainer["mosquitto Container\n(eclipse-mosquitto:latest)"]
subgraph "Configuration Flow"
 
       ComposeFile -->|Defines service| MosqContainer
 
       MosqConf -->|Volume mount ./mosquitto.conf:/mosquitto/config/mosquitto.conf| MosqContainer
    end
    
    subgraph "Anonymous Access Config"
        Line2["Line 2: allow_anonymous true"]
NoACL["No aclfile directive"]
NoPwdFile["No password_file directive"]
end
    
 
   MosqConf --> Line2
 
   MosqConf --> NoACL
 
   MosqConf --> NoPwdFile
    
    subgraph "Runtime Behavior"
        AllowAll["All connections accepted"]
NoCredCheck["No credential validation"]
FullTopicAccess["Full topic access for all clients"]
end
    
 
   Line2 --> AllowAll
 
   NoACL --> FullTopicAccess
 
   NoPwdFile --> NoCredCheck

Relationship to System Components

Container Configuration

The mosquitto service in docker-compose.yml mounts the configuration file as a volume:

This volume mount makes the allow_anonymous true setting effective when the container starts. The Mosquitto process reads this configuration file on startup and applies the anonymous access policy to all listeners.

Sources: mosquitto.conf, docker-compose.yml (referenced in diagrams)

Alternative Authentication Configurations

Username/Password Authentication

To enable credential-based authentication, modify mosquitto.conf to include:

allow_anonymous false
password_file /mosquitto/config/passwordfile

Create the password file using the mosquitto_passwd utility:

Authentication Flow with Credentials

Access Control Lists (ACLs)

ACLs provide topic-level permission control based on usernames. Add to mosquitto.conf:

acl_file /mosquitto/config/aclfile

ACL File Example

# User 'alice' can read/write to alice/* topics
user alice
topic readwrite alice/#

# User 'bob' can only read bob/* topics  
user bob
topic read bob/#

Protected Branch Example

The [protected-no-wildcard branch](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/protected-no-wildcard branch) demonstrates a complete authentication implementation:

For implementation details, see Protected Branch Features.

Sources: README.md

Testing Anonymous Access

The CI/CD pipeline validates that the Mosquitto broker starts successfully with anonymous access enabled. The health check in .github/workflows/ci.yml verifies the container reaches a running state but does not test authentication behavior since none is required.

Testing Approach

To manually verify anonymous access behavior:

1. Start the services: docker compose up
2. Connect any MQTT client to the public hostname configured in Cloudflare
3. Attempt to connect without providing credentials
4. Verify successful connection and message publication

No username or password should be required for successful connection and full MQTT operation.

Sources: .github/workflows/ci.yml (referenced), README.md

Migration Path to Authentication

If anonymous access proves insufficient for security requirements, the system can be migrated to authenticated access by:

1. Creating a password file with mosquitto_passwd command
2. Adding password_file /path/to/password_file directive to mosquitto.conf
3. Removing or changing allow_anonymous true to allow_anonymous false
4. Optionally adding an ACL file for topic-level restrictions
5. Updating client code to provide credentials in CONNECT packets

The [protected-no-wildcard branch](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/protected-no-wildcard branch) provides a complete reference implementation. View the [configuration differences](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/configuration differences) to understand required changes.

For production deployments requiring authentication, see Production Considerations and Topic Access Control (ACL).

Sources: README.md

Dismiss

Refresh this wiki

Enter email to refresh

Mosquitto MQTT Broker

Loading…

Mosquitto MQTT Broker

Relevant source files

• README.md
• docker-compose.yml
• mosquitto.conf

Purpose and Scope

This document provides in-depth technical documentation of the mosquitto service within the Docker MQTT Mosquitto Cloudflare Tunnel system. It covers the Docker service configuration, container image specification, volume mount strategy, network integration, and runtime characteristics of the MQTT broker component.

For detailed information about the specific MQTT listener configurations (ports 1883 and 9001), see MQTT Listeners. For security implications and configuration of anonymous client access, see Anonymous Access. For the cloudflared service that proxies external traffic to this broker, see Cloudflared Tunnel Service.

Sources: README.md15 docker-compose.yml:4-9

Overview

The mosquitto service is the core MQTT message broker in this system, responsible for accepting MQTT client connections, routing published messages to subscribers, and maintaining message state. It runs as a containerized instance of Eclipse Mosquitto, an open-source implementation of the MQTT protocol versions 5.0, 3.1.1, and 3.1.

Within the system architecture, the broker receives traffic exclusively through the cloudflared container, which proxies external MQTT connections from Cloudflare’s tunnel to the broker’s WebSocket listener on port 9001. The broker is never directly exposed to the internet, relying on Cloudflare Tunnel for secure external access.

Sources: README.md15 docker-compose.yml:4-9 Diagram 1 from system overview

Docker Service Configuration

Service Definition

The mosquitto service is defined in docker-compose.yml:4-9 as follows:

The service definition is minimal by design, relying on external configuration through the volume-mounted mosquitto.conf file rather than environment variables or command-line arguments.

Sources: docker-compose.yml:4-9

Container Image Strategy

The service uses the eclipse-mosquitto:latest image tag from Docker Hub’s official Eclipse Mosquitto repository. This tag automatically pulls the most recent stable version of Mosquitto when the container is created or updated. The latest tag strategy means:

• New deployments receive the current stable version
• Existing deployments remain on their pulled version until explicitly updated
• No version pinning provides automatic access to bug fixes and features
• Manual intervention required to pull updated images (docker compose pull)

For production deployments where version stability is critical, consider pinning to a specific version tag (e.g., eclipse-mosquitto:2.0.18) instead of latest.

Sources: docker-compose.yml5

Configuration File Management

Volume Mount Architecture

Diagram: Configuration File Volume Mount Flow

The configuration file is mounted from the host filesystem into the container at /mosquitto/config/mosquitto.conf. The Mosquitto process reads this file during container startup to determine listener configurations, authentication settings, and protocol options.

Sources: docker-compose.yml:7-8 mosquitto.conf:1-6

Configuration File Contents

The mosquitto.conf:1-6 file defines the broker’s operational parameters:

listener 1883
allow_anonymous true

listener 9001
protocol websockets

This configuration establishes two distinct listeners with different protocols and purposes. The configuration is intentionally minimal, containing only the essential settings for listener setup and anonymous access control. The file is version-controlled and identical across all deployments, with no host-specific or secret values.

Changes to mosquitto.conf require a container restart to take effect, as Mosquitto reads the configuration only during startup.

Sources: mosquitto.conf:1-6 docker-compose.yml:7-8

Network Architecture

Docker Network Integration

Diagram: Service Network Connectivity

The mosquitto service participates in Docker Compose’s default bridge network, which provides automatic DNS resolution. The fixed container_name: mosquitto enables the cloudflared container to reference it by hostname when configuring the tunnel’s backend service (configured in Cloudflare Dashboard as mosquitto:9001).

No ports are exposed to the host machine in docker-compose.yml:4-9 meaning:

• Port 1883 is accessible only within the Docker network
• Port 9001 is accessible only within the Docker network
• External access occurs exclusively through the cloudflared tunnel proxy
• No inbound firewall rules are required on the host

Sources: docker-compose.yml:4-9 README.md62

Service-to-Service Communication

Diagram: Internal Service Communication Flow

The cloudflared container resolves the mosquitto hostname using Docker’s internal DNS, which maps the container_name to the container’s IP address on the bridge network. This DNS-based service discovery eliminates the need for hardcoded IP addresses or external service registries.

Sources: README.md62 docker-compose.yml:4-9

Runtime Characteristics

Container Lifecycle

The restart: unless-stopped policy in docker-compose.yml9 configures automatic container restart behavior:

This policy ensures high availability while allowing manual intervention when needed. The broker restarts automatically after transient failures but respects explicit stop commands from administrators.

Sources: docker-compose.yml9

Data Persistence

The main branch configuration does not define any volume mounts for persistent data storage. This means:

• Message persistence is disabled (all messages are in-memory only)
• Retained messages are lost on container restart
• Client session state is not persisted
• QoS 1 and QoS 2 message queues are cleared on restart

For persistent message storage, the [protected-no-wildcard branch](https://github.com/jzombie/docker-mqtt-mosquitto-cloudflare-tunnel/blob/59f1274c/protected-no-wildcard branch) implements encrypted retained message storage. See Encrypted Retained Messages for details on that advanced configuration.

Sources: docker-compose.yml:4-9 README.md:5-11

Process Architecture

Diagram: Container Process Architecture

The Mosquitto broker runs as PID 1 within its container, reading configuration from the mounted mosquitto.conf file and establishing both listener sockets. The process handles all MQTT client connections, message routing, and protocol state management as a single-threaded event loop.

Sources: docker-compose.yml:4-9 mosquitto.conf:1-6

Integration with System Components

Relationship to Cloudflared Service

The mosquitto service operates in coordination with the cloudflared service defined in docker-compose.yml:11-17 The cloudflared tunnel configuration (managed in the Cloudflare Dashboard) specifies mosquitto:9001 as the backend service URL, establishing the proxy relationship:

1. Cloudflared container resolves mosquitto hostname via Docker DNS
2. Cloudflared establishes HTTP connection to mosquitto container port 9001
3. Cloudflared proxies WebSocket upgrade requests to mosquitto
4. Mosquitto accepts WebSocket connection and initiates MQTT protocol

This architecture keeps the mosquitto container completely isolated from direct internet access while maintaining full MQTT functionality through the tunnel proxy.

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

CI/CD Testing Integration

The GitHub Actions workflow in .github/workflows/ci.yml tests the mosquitto service health during continuous integration:

The CI pipeline verifies that the mosquitto container reaches a running state, validating that:

• The eclipse-mosquitto:latest image can be pulled
• The container starts without configuration errors
• The mosquitto process initializes successfully
• The mounted configuration file is valid

For complete CI/CD pipeline documentation, see CI/CD Pipeline.

Sources: .github/workflows/ci.yml docker-compose.yml:4-9

Configuration Reference Summary

Sources: docker-compose.yml:4-9 mosquitto.conf:1-6

Dismiss

Refresh this wiki

Enter email to refresh

Cloudflared Tunnel Connector

Loading…

Cloudflared Tunnel Connector

Relevant source files

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

Purpose and Scope

This document details the cloudflared container component, which acts as the secure tunnel connector between the Cloudflare network and the local Mosquitto MQTT broker. It explains the container’s configuration, how it authenticates with Cloudflare’s infrastructure, how it establishes and maintains the tunnel connection, and how it routes incoming traffic to the Mosquitto service.

For broader system architecture context, see System Architecture. For Docker Compose orchestration details, see Docker Compose Orchestration. For environment variable configuration, see Environment Variables.

Container Overview

The cloudflared service is defined in docker-compose.yml:11-17 and runs the official Cloudflare Tunnel connector image. This container establishes an outbound-only persistent connection to Cloudflare’s network, eliminating the need for open inbound ports on the host system.

Container Specification

Sources: docker-compose.yml:11-17

Container Configuration Architecture

The following diagram maps the Docker Compose configuration elements to their runtime purposes:

Sources: docker-compose.yml:11-17

graph TB
    subgraph "docker-compose.yml Definition"
        SERVICE["services.cloudflared"]
IMAGE["image: cloudflare/cloudflared:latest"]
CONTAINER["container_name: cloudflared"]
COMMAND["command: tunnel --no-autoupdate run --token"]
RESTART["restart: unless-stopped"]
ENV_SECTION["environment:\n- CLOUDFLARE_TUNNEL_TOKEN"]
end
    
    subgraph "Runtime Configuration"
        TOKEN_VAR["${CLOUDFLARE_TUNNEL_TOKEN}\nfrom .env file"]
CMD_EXEC["Executed Command:\ntunnel --no-autoupdate run --token <actual_token>"]
end
    
    subgraph "Operational Behavior"
        CONTAINER_PROC["cloudflared Process"]
AUTO_RESTART["Automatic Restart\non Failure"]
NO_UPDATE["Update Mechanism\nDisabled"]
end
    
 
   SERVICE --> IMAGE
 
   SERVICE --> CONTAINER
 
   SERVICE --> COMMAND
 
   SERVICE --> RESTART
 
   SERVICE --> ENV_SECTION
    
 
   ENV_SECTION --> TOKEN_VAR
 
   COMMAND --> TOKEN_VAR
 
   TOKEN_VAR --> CMD_EXEC
    
 
   CMD_EXEC --> CONTAINER_PROC
 
   RESTART --> AUTO_RESTART
 
   COMMAND --> NO_UPDATE
    
 
   CONTAINER_PROC --> NO_UPDATE
 
   CONTAINER_PROC --> AUTO_RESTART

Tunnel Authentication

The cloudflared connector authenticates with Cloudflare’s infrastructure using a cryptographically secure tunnel token. This token is generated during the Cloudflare Tunnel creation process and links the local connector to a specific tunnel configuration on Cloudflare’s network.

sequenceDiagram
    participant User as "Administrator"
    participant CF_UI as "Cloudflare Dashboard"
    participant Env as ".env File"
    participant Compose as "docker-compose"
    participant CFD as "cloudflared Container"
    participant CF_Net as "Cloudflare Network"
    
    User->>CF_UI: Create tunnel via Zero Trust dashboard
    CF_UI->>CF_UI: Generate CLOUDFLARE_TUNNEL_TOKEN
    CF_UI-->>User: Display token in connector setup
    
    User->>Env: Create .env file with token
    Note over Env: CLOUDFLARE_TUNNEL_TOKEN=eyJh...
    
    User->>Compose: docker compose up
    Compose->>Env: Read CLOUDFLARE_TUNNEL_TOKEN
    Compose->>CFD: Start container with token in command
    Note over CFD: tunnel run --token <token>
    
    CFD->>CF_Net: Initiate tunnel connection with token
    CF_Net->>CF_Net: Validate token signature
    CF_Net->>CF_Net: Retrieve tunnel configuration
    CF_Net-->>CFD: Tunnel established
    
    Note over CFD,CF_Net: Persistent connection maintained

Token Lifecycle

Token Security Properties

• Single-Use Binding: Each token is bound to a specific tunnel UUID in Cloudflare’s infrastructure
• Environment Injection: Token is injected via environment variable substitution at container start
• Never Logged: The --token flag ensures the token does not appear in process listings
• Git Exclusion: The .env file containing the token is excluded via .gitignore

Sources: docker-compose.yml14 docker-compose.yml:16-17 .env.sample1 README.md53

Connection Establishment

The cloudflared container establishes an outbound-only connection to Cloudflare’s edge network. This inverted architecture eliminates the need for inbound firewall rules or public IP addresses.

Tunnel Command Structure

The command executed by the container is:

tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}

Sources: docker-compose.yml14

Connection Flow

Sources: docker-compose.yml14 README.md64 README.md67

Traffic Routing Mechanism

The cloudflared container acts as a local reverse proxy, receiving traffic from the Cloudflare tunnel and forwarding it to the mosquitto service using Docker’s internal DNS resolution.

graph LR
    subgraph "Cloudflare Configuration"
        CF_HOST["Public Hostname:\nmqtt.example.com"]
CF_SERVICE["Service Type: HTTP"]
CF_URL["URL: mosquitto:9001"]
end
    
    subgraph "Docker Network"
        DNS["Docker Internal DNS"]
MOSQ_NAME["Container Name:\nmosquitto"]
MOSQ_IP["Container IP:\n172.x.x.x"]
end
    
    subgraph "cloudflared Container"
        CFD_PROC["cloudflared Process"]
RESOLVER["DNS Resolver"]
HTTP_CLIENT["HTTP Client"]
end
    
 
   CF_HOST --> CF_SERVICE
 
   CF_SERVICE --> CF_URL
    
 
   CF_URL -.->|'mosquitto' hostname configured in tunnel| CFD_PROC
 
   CFD_PROC --> RESOLVER
 
   RESOLVER --> DNS
 
   DNS --> MOSQ_NAME
 
   MOSQ_NAME --> MOSQ_IP
 
   MOSQ_IP -.-> HTTP_CLIENT
    
 
   HTTP_CLIENT -->|HTTP to 172.x.x.x:9001| MOSQ_IP

Internal DNS Resolution

Routing Configuration

The routing is configured in the Cloudflare Dashboard during tunnel setup:

• Public Hostname: User-defined subdomain (e.g., mqtt.example.com)
• Service Type: HTTP (internal protocol between cloudflared and mosquitto)
• Service URL: mosquitto:9001 (Docker service name and port)

The mosquitto hostname in the service URL is resolved by Docker’s internal DNS to the IP address of the container named mosquitto as defined in docker-compose.yml6

Sources: README.md:62-67 docker-compose.yml:4-6

Protocol Translation

The cloudflared container performs protocol translation between external HTTPS/WSS connections and internal HTTP/WebSocket connections.

External vs Internal Protocols

The external connection is encrypted end-to-end from client to Cloudflare’s edge, while the internal connection between cloudflared and mosquitto is unencrypted but isolated within Docker’s private bridge network.

Sources: README.md67 README.md82

Operational Characteristics

No Exposed Ports

The cloudflared container exposes no ports to the host system. All communication occurs via:

1. Outbound tunnel connection to Cloudflare’s network
2. Internal Docker network for communication with the mosquitto container

This design eliminates attack surface by ensuring no listening ports on the host machine.

Sources: docker-compose.yml:11-17

Restart Behavior

The container uses the unless-stopped restart policy defined in docker-compose.yml15 This ensures:

• Automatic recovery: Container restarts on crashes or Docker daemon restarts
• Persistent operation: Container continues running across reboots
• Manual control: Container only stops when explicitly commanded via docker compose down or docker stop

Update Management

The --no-autoupdate flag in docker-compose.yml14 disables cloudflared’s built-in automatic update mechanism. This ensures:

• Version pinning: Updates are controlled via Docker image version
• Predictable behavior: No unexpected binary changes during operation
• Image-based updates: Updates occur through docker compose pull and container recreation

Sources: docker-compose.yml:14-15

Connection State Diagram

Sources: docker-compose.yml:14-15

Environment Variable Configuration

The cloudflared container requires exactly one environment variable:

CLOUDFLARE_TUNNEL_TOKEN

• Source: Defined in .env file (see .env.sample1)
• Injection Method: Environment variable substitution in docker-compose.yml14
• Format: Base64-encoded JSON containing tunnel credentials
• Scope: Container-level environment variable
• Security: Must not be committed to version control

The token is referenced twice in the configuration:

1. In the command field via shell substitution: ${CLOUDFLARE_TUNNEL_TOKEN}
2. In the environment section for explicit passing to the container

Sources: docker-compose.yml14 docker-compose.yml:16-17 .env.sample1

Security Model

Zero Inbound Exposure

The cloudflared container implements a security model where:

• No listening ports: Container binds no ports to the host interface
• Outbound-only connections: All connections are initiated from inside the network
• Tunnel-based access: External access is only possible through the authenticated tunnel
• No direct routes: No firewall rules or port forwarding required

Authentication Flow

Sources: docker-compose.yml14 docker-compose.yml:16-17 README.md53

Common Configuration Reference

Minimal Configuration

The cloudflared service requires minimal configuration:

Configuration Dependencies

Sources: docker-compose.yml:11-17

Integration with Mosquitto

The cloudflared container integrates with the mosquitto container through Docker’s internal networking:

Service Discovery

• DNS Name: mosquitto (from docker-compose.yml4)
• Container Name: mosquitto (from docker-compose.yml6)
• Target Port: 9001 (WebSocket listener)
• Resolution: Automatic via Docker’s embedded DNS server

graph TB
    subgraph "Host System"
        HOST["No Exposed Ports"]
end
    
    subgraph "Docker Bridge Network"
        CFD_CONTAINER["cloudflared Container\nNo EXPOSE directive"]
MOSQ_CONTAINER["mosquitto Container\nNo EXPOSE directive"]
DOCKER_DNS["Docker DNS Server"]
end
    
    subgraph "External Network"
        CF_EDGE["Cloudflare Edge\nPublic HTTPS:443"]
end
    
 
   CF_EDGE <-->|Outbound tunnel connection| CFD_CONTAINER
 
   CFD_CONTAINER <-->|DNS query: mosquitto| DOCKER_DNS
 
   DOCKER_DNS -->|Resolves to container IP| MOSQ_CONTAINER
 
   CFD_CONTAINER -->|HTTP:9001| MOSQ_CONTAINER
    
 
   HOST -.->|No direct connection| CFD_CONTAINER
 
   HOST -.->|No direct connection| MOSQ_CONTAINER

Network Isolation

Both containers run on the same Docker bridge network without exposing ports to the host:

Sources: docker-compose.yml:4-6 docker-compose.yml:11-17 README.md64

Troubleshooting Connection Issues

Token Validation Failures

If the cloudflared container fails to establish a tunnel:

1. Verify token format: Token should be a long base64-encoded string
2. Check.env file: Ensure CLOUDFLARE_TUNNEL_TOKEN=<token> with no extra spaces
3. Confirm tunnel exists: Verify the tunnel is active in Cloudflare Dashboard
4. Review logs: docker logs cloudflared will show authentication errors

DNS Resolution Failures

If cloudflared cannot reach the mosquitto container:

1. Verify container names: Both containers must use the names defined in docker-compose.yml
2. Check network: Both containers must be on the same Docker network (default bridge)
3. Confirm mosquitto is running: docker ps should show both containers as “Up”
4. Test DNS resolution: docker exec cloudflared nslookup mosquitto should resolve

Service URL Configuration

The service URL in Cloudflare Dashboard must match the Docker configuration:

• Correct: mosquitto:9001 or http://mosquitto:9001
• Incorrect: localhost:9001, 127.0.0.1:9001, mqtt:9001

Sources: docker-compose.yml:4-6 README.md64 README.md84

Dismiss

Refresh this wiki

Enter email to refresh

Docker Compose Orchestration

Loading…

Docker Compose Orchestration

Relevant source files

• docker-compose.yml

Purpose and Scope

This document provides detailed documentation of the docker-compose.yml:1-18 file, which serves as the primary orchestration configuration for the MQTT Mosquitto Cloudflare Tunnel system. It explains how the file defines, configures, and coordinates the two core services (mosquitto and cloudflared), including their Docker images, network connectivity, volume mounts, environment variables, and lifecycle management.

For information about configuring the Mosquitto broker itself, see Mosquitto Configuration. For details about setting up the Cloudflare Tunnel token, see Environment Variables. For deployment procedures, see Deployment.

Service Composition Overview

The docker-compose.yml:1-18 file defines a minimal two-service architecture. Both services run as separate Docker containers but share a common Docker network, enabling seamless inter-container communication.

graph TB
    subgraph "docker-compose.yml"
        ComposeFile["version: '3.8'"]
ServicesBlock["services:]
    end
    
    subgraph Service Definitions"
        MosquittoService["mosquitto"]
CloudflaredService["cloudflared"]
end
    
    subgraph "mosquitto Service Configuration"
        MosquittoImage["image: eclipse-mosquitto:latest"]
MosquittoContainer["container_name: mosquitto"]
MosquittoVolumes["volumes:\n./mosquitto.conf mapped to\n/mosquitto/config/mosquitto.conf"]
MosquittoRestart["restart: unless-stopped"]
end
    
    subgraph "cloudflared Service Configuration"
        CloudflaredImage["image: cloudflare/cloudflared:latest"]
CloudflaredContainer["container_name: cloudflared"]
CloudflaredCommand["command: tunnel --no-autoupdate run\n--token ${CLOUDFLARE_TUNNEL_TOKEN}"]
CloudflaredEnv["environment:\nCLOUDFLARE_TUNNEL_TOKEN"]
CloudflaredRestart["restart: unless-stopped"]
end
    
    subgraph "Docker Runtime"
        DockerNetwork["Default Docker Network\nAuto-created"]
MosquittoRuntime["mosquitto container\nHostname: mosquitto"]
CloudflaredRuntime["cloudflared container\nHostname: cloudflared"]
end
    
 
   ComposeFile --> ServicesBlock
 
   ServicesBlock --> MosquittoService
 
   ServicesBlock --> CloudflaredService
    
 
   MosquittoService --> MosquittoImage
 
   MosquittoService --> MosquittoContainer
 
   MosquittoService --> MosquittoVolumes
 
   MosquittoService --> MosquittoRestart
    
 
   CloudflaredService --> CloudflaredImage
 
   CloudflaredService --> CloudflaredContainer
 
   CloudflaredService --> CloudflaredCommand
 
   CloudflaredService --> CloudflaredEnv
 
   CloudflaredService --> CloudflaredRestart
    
 
   MosquittoService -.->|Creates| MosquittoRuntime
 
   CloudflaredService -.->|Creates| CloudflaredRuntime
    
 
   MosquittoRuntime --> DockerNetwork
 
   CloudflaredRuntime --> DockerNetwork
    
 
   CloudflaredRuntime -.->|Proxies to mosquitto:9001| MosquittoRuntime

Service Topology

Sources : docker-compose.yml:1-18

Service Definitions

mosquitto Service

The mosquitto service definition docker-compose.yml:4-9 configures the Eclipse Mosquitto MQTT broker container.

Configuration File Mount : The volume mapping docker-compose.yml8 ensures that the local mosquitto.conf file is available to the broker at runtime. The Mosquitto container automatically reads configuration from /mosquitto/config/mosquitto.conf on startup.

Image Version Strategy : The use of the latest tag docker-compose.yml5 means the system will pull the most recent stable Mosquitto release. For production deployments, consider pinning to a specific version tag (e.g., eclipse-mosquitto:2.0.18).

Sources : docker-compose.yml:4-9

cloudflared Service

The cloudflared service definition docker-compose.yml:11-18 configures the Cloudflare Tunnel client container.

Command Structure : The command directive docker-compose.yml14 breaks down as follows:

tunnel                           # cloudflared subcommand
--no-autoupdate                 # Prevents automatic updates that could disrupt service
run                             # Executes the tunnel in persistent mode
--token ${CLOUDFLARE_TUNNEL_TOKEN}  # Authenticates using the token from environment variable

Environment Variable Injection : The environment section docker-compose.yml:16-17 instructs Docker Compose to read CLOUDFLARE_TUNNEL_TOKEN from the .env file (not committed to version control) and inject it into the container’s environment. The variable is then referenced in the command using standard shell variable syntax.

Sources : docker-compose.yml:11-18

graph LR
    subgraph "Docker Host"
        subgraph "Default Compose Network"
            MosquittoContainer["mosquitto\ncontainer_name: mosquitto\nAccessible as: mosquitto"]
CloudflaredContainer["cloudflared\ncontainer_name: cloudflared\nAccessible as: cloudflared"]
end
        
        HostInterface["Host Network Interface\nNot directly accessible\nfrom containers"]
end
    
    subgraph "External Network"
        CloudflareEdge["Cloudflare Edge Network"]
end
    
 
   CloudflaredContainer -->|DNS resolution: mosquitto resolves to mosquitto container IP| MosquittoContainer
 
   CloudflaredContainer -->|Outbound connection to Cloudflare| CloudflareEdge
    
 
   MosquittoContainer -.->|No direct external connectivity| HostInterface

Docker Compose Networking

Docker Compose automatically creates a default bridge network for all services defined in the same compose file. This network enables service-to-service communication using container names as hostnames.

Hostname Resolution : Because the mosquitto service has container_name: mosquitto docker-compose.yml6 the container is accessible within the Docker network using the hostname mosquitto. The Cloudflare Tunnel configuration (configured through the Cloudflare Dashboard) references mosquitto:9001 as the backend service URL, which Docker resolves to the mosquitto container’s internal IP address.

Network Isolation : Neither container exposes ports to the host network. All communication flows through:

1. External → cloudflared : Inbound traffic arrives via the Cloudflare Tunnel (outbound-initiated connection)
2. cloudflared → mosquitto : Internal Docker network communication on port 9001
3. mosquitto → External : Not applicable; the broker only receives proxied traffic

No Explicit Network Declaration : The compose file does not include a networks: section, so Docker Compose uses its default behavior of creating a network named <project_name>_default (where <project_name> is typically the directory name).

Sources : docker-compose.yml:1-18

graph LR
    subgraph "Docker Host Filesystem"
        HostMosquittoConf["./mosquitto.conf\nLine: listener 1883\nLine: listener 9001\nLine: protocol websockets\nLine: allow_anonymous true"]
end
    
    subgraph "mosquitto Container"
        ContainerPath["/mosquitto/config/mosquitto.conf"]
MosquittoProcess["mosquitto process\nReads config on startup"]
end
    
 
   HostMosquittoConf -.->|Volume mount Read-only access| ContainerPath
 
   ContainerPath --> MosquittoProcess

Volume Mounts

The system uses a single volume mount to inject the Mosquitto configuration into the broker container.

Mount Specification : The volume directive docker-compose.yml:7-8 uses the syntax:

This creates a bind mount where:

• Host path : ./mosquitto.conf (relative to the directory containing docker-compose.yml)
• Container path : /mosquitto/config/mosquitto.conf (the default configuration location for Eclipse Mosquitto)
• Mount type : Bind mount (inferred from the ./ prefix)
• Read/Write mode : Read-only (implicit default for configuration files)

Configuration Reloading : Mosquitto does not automatically reload configuration changes. To apply modifications to mosquitto.conf:

1. Edit the file on the host filesystem
2. Restart the mosquitto container: docker compose restart mosquitto

No Data Persistence : The configuration does not define any volumes for persisting MQTT retained messages or other runtime data. If data persistence is required, additional volume mounts should be configured for /mosquitto/data.

Sources : docker-compose.yml:7-8

Restart Policies

Both services use the unless-stopped restart policy docker-compose.yml:9-15 which ensures high availability and automatic recovery from failures.

Restart Policy Behavior Matrix

Alternative Restart Policies

The unless-stopped policy is appropriate for production services. Other available policies include:

• no : Never automatically restart (requires manual intervention for failures)
• always : Restart even after manual stop (aggressive auto-recovery)
• on-failure : Restart only on non-zero exit codes (useful for debugging)

Configuration Example : To change the restart policy, modify docker-compose.yml9 or docker-compose.yml15:

Sources : docker-compose.yml:9-15

sequenceDiagram
    participant User
    participant DockerCompose as "docker compose"
    participant DockerEngine as "Docker Engine"
    participant EnvFile as ".env File"
    participant MosquittoConf as "mosquitto.conf File"
    participant MosquittoContainer as "mosquitto Container"
    participant CloudflaredContainer as "cloudflared Container"
    
    User->>DockerCompose: docker compose up
    DockerCompose->>EnvFile: Read environment variables
    EnvFile-->>DockerCompose: CLOUDFLARE_TUNNEL_TOKEN=xxx
    
    DockerCompose->>DockerEngine: Create network (if not exists)
    DockerEngine-->>DockerCompose: Network ready
    
    DockerCompose->>DockerEngine: Pull eclipse-mosquitto:latest
    DockerEngine-->>DockerCompose: Image ready
    
    DockerCompose->>DockerEngine: Pull cloudflare/cloudflared:latest
    DockerEngine-->>DockerCompose: Image ready
    
    DockerCompose->>DockerEngine: Create mosquitto container
    Note over DockerEngine,MosquittoConf: Volume mount ./mosquitto.conf
    DockerEngine->>MosquittoContainer: Start with mounted config
    MosquittoContainer->>MosquittoConf: Read configuration
    MosquittoContainer-->>DockerEngine: Listening on ports 1883, 9001
    
    DockerCompose->>DockerEngine: Create cloudflared container
    Note over DockerEngine,CloudflaredContainer: Inject CLOUDFLARE_TUNNEL_TOKEN
    DockerEngine->>CloudflaredContainer: Start with command:\ntunnel --no-autoupdate run --token
    CloudflaredContainer-->>DockerEngine: Tunnel established
    
    CloudflaredContainer->>MosquittoContainer: Verify mosquitto:9001 reachable
    MosquittoContainer-->>CloudflaredContainer: Connection successful
    
    DockerCompose-->>User: Services running

Service Orchestration Flow

The following diagram illustrates the complete lifecycle from docker compose up to running services.

Startup Order : Docker Compose does not guarantee a specific startup order between the two services. However, this is acceptable because:

• The mosquitto service can start independently
• The cloudflared service will retry connections to mosquitto:9001 if the broker is not yet ready

Dependency Management : For strict startup ordering, Docker Compose supports depends_on directives. This system does not use them because the cloudflared tunnel client includes built-in retry logic.

Sources : docker-compose.yml:1-18

Command-Line Operations

Common Docker Compose commands for managing the service stack:

Graceful Shutdown : The docker compose down command sends SIGTERM to both containers, allowing them to shut down gracefully before forcing termination.

Sources : docker-compose.yml:1-18

Service Dependency Graph

External Dependencies : The system requires:

1. Docker Engine (to run containers)
2. Active internet connection (for cloudflared to reach Cloudflare’s network)
3. Valid Cloudflare Tunnel token (from Cloudflare Zero Trust dashboard)

Configuration Dependencies :

• mosquitto service depends on the existence of ./mosquitto.conf docker-compose.yml8
• cloudflared service depends on CLOUDFLARE_TUNNEL_TOKEN being set in .env docker-compose.yml:16-17

Sources : docker-compose.yml:1-18

Version Specification

The compose file uses version 3.8 docker-compose.yml1 which corresponds to Docker Compose file format 3.8, compatible with Docker Engine 19.03.0+.

Version 3.8 Features :

• Support for init flag (not used in this configuration)
• Enhanced credential helper support (not used in this configuration)
• Improved service dependency controls (not used in this configuration)

Backward Compatibility : The configuration uses only basic features that are compatible with earlier 3.x versions. The version could be lowered to 3.0 without affecting functionality.

Docker Compose V2 : This configuration is compatible with both Docker Compose V1 (docker-compose) and Docker Compose V2 (docker compose). The modern V2 syntax uses docker compose (space, not hyphen).

Sources : docker-compose.yml1

Dismiss

Refresh this wiki

Enter email to refresh

Configuration Reference

Loading…

Configuration Reference

Relevant source files

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

This page provides comprehensive reference documentation for all configuration files and settings in the Docker MQTT Mosquitto Cloudflare Tunnel system. Each configuration file is documented with complete syntax specifications, available directives, default values, and behavioral implications.

The system uses three configuration files:

• docker-compose.yml - service orchestration and container definitions
• mosquitto.conf - MQTT broker listener and access control configuration
• .env - runtime environment variables containing sensitive credentials

For architectural context, see page 1.1. For security implications of configuration choices, see page 1.2. For setup instructions, see page 2.

Configuration Files Overview

The system uses three primary configuration files:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3 .gitignore1

Configuration File Relationships

Configuration Directive Mapping to Runtime Behavior

The following diagram maps natural language concepts to specific configuration directives and code symbols used in the system:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

graph TB
    subgraph "docker-compose.yml Directives"
        Version["version: '3.8'"]
MosqService["services.mosquitto"]
MosqImage["image: eclipse-mosquitto:latest"]
MosqContainer["container_name: mosquitto"]
MosqVolume["volumes:\n./mosquitto.conf:/mosquitto/config/mosquitto.conf"]
MosqRestart["restart: unless-stopped"]
CFService["services.cloudflared"]
CFImage["image: cloudflare/cloudflared:latest"]
CFContainer["container_name: cloudflared"]
CFCommand["command: tunnel --no-autoupdate run --token"]
CFEnv["environment:\nCLOUDFLARE_TUNNEL_TOKEN"]
CFRestart["restart: unless-stopped"]
end
    
    subgraph "mosquitto.conf Directives"
        Listener1883["listener 1883"]
AllowAnon["allow_anonymous true"]
Listener9001["listener 9001"]
ProtocolWS["protocol websockets"]
end
    
    subgraph ".env Variables"
        TunnelToken["CLOUDFLARE_TUNNEL_TOKEN=<value>"]
end
    
    subgraph "Runtime Behavior"
        TCPPort["TCP MQTT on port 1883"]
WSPort["WebSocket MQTT on port 9001"]
NoAuth["No authentication required"]
TunnelAuth["Tunnel authentication to Cloudflare"]
end
    
 
   Listener1883 --> TCPPort
 
   Listener9001 --> WSPort
 
   ProtocolWS --> WSPort
 
   AllowAnon --> NoAuth
    
 
   TunnelToken --> CFEnv
 
   CFEnv --> TunnelAuth
    
 
   MosqVolume -.->|mounts| Listener1883
 
   MosqVolume -.->|mounts| AllowAnon
 
   MosqVolume -.->|mounts| Listener9001
 
   MosqVolume -.->|mounts| ProtocolWS

docker-compose.yml Reference

The docker-compose.yml file defines the multi-container application using Docker Compose specification version 3.8. It orchestrates two services: mosquitto (MQTT broker) and cloudflared (tunnel connector).

graph TB
    Root["docker-compose.yml"]
Version["version: '3.8'\n(line 1)"]
Services["services:\n(line 3)"]
MosqService["mosquitto:\n(line 4)"]
MosqImage["image: eclipse-mosquitto:latest\n(line 5)"]
MosqContainer["container_name: mosquitto\n(line 6)"]
MosqVolumes["volumes:\n(line 7)"]
MosqVolMount["./mosquitto.conf:/mosquitto/config/mosquitto.conf\n(line 8)"]
MosqRestart["restart: unless-stopped\n(line 9)"]
CFService["cloudflared:\n(line 11)"]
CFImage["image: cloudflare/cloudflared:latest\n(line 12)"]
CFContainer["container_name: cloudflared\n(line 13)"]
CFCommand["command: tunnel --no-autoupdate run --token $CLOUDFLARE_TUNNEL_TOKEN\n(line 14)"]
CFRestart["restart: unless-stopped\n(line 15)"]
CFEnv["environment:\n(line 16)"]
CFEnvToken["- CLOUDFLARE_TUNNEL_TOKEN\n(line 17)"]
Root --> Version
 
   Root --> Services
 
   Services --> MosqService
 
   Services --> CFService
    
 
   MosqService --> MosqImage
 
   MosqService --> MosqContainer
 
   MosqService --> MosqVolumes
 
   MosqService --> MosqRestart
 
   MosqVolumes --> MosqVolMount
    
 
   CFService --> CFImage
 
   CFService --> CFContainer
 
   CFService --> CFCommand
 
   CFService --> CFRestart
 
   CFService --> CFEnv
 
   CFEnv --> CFEnvToken

File Structure

Sources: docker-compose.yml:1-18

Service: mosquitto

Directives

Sources: docker-compose.yml:4-9

Volume Mount Behavior

The volume directive at docker-compose.yml8 creates a bind mount from the host filesystem:

• Host path: ./mosquitto.conf (relative to the directory containing docker-compose.yml)
• Container path: /mosquitto/config/mosquitto.conf
• Mount type: Bind mount (read-only by default in this configuration)
• Effect: Overrides the default Mosquitto configuration with custom listener definitions

The Mosquitto process reads this file at startup. Changes to the host file require container restart to take effect.

Sources: docker-compose.yml:7-8

Service: cloudflared

Directives

Sources: docker-compose.yml:11-18

Command Breakdown

The command directive at docker-compose.yml14 constructs the following runtime command:

tunnel --no-autoupdate run --token <token_value>

Command components:

• tunnel - The cloudflared subcommand for tunnel operations
• --no-autoupdate - Disables automatic updates of the cloudflared binary (recommended in containerized environments)
• run - Starts the tunnel in persistent connection mode
• --token - Authentication token for the tunnel (required for cloudflared tunnel connectivity)
• ${CLOUDFLARE_TUNNEL_TOKEN} - Environment variable substitution performed by Docker Compose

Sources: docker-compose.yml14

Network Configuration

Docker Compose automatically creates a bridge network for inter-service communication. The default network name follows the pattern <project-name>_default.

Service Discovery:

• The mosquitto service is resolvable via DNS at hostname mosquitto
• The cloudflared service references this hostname when configured in the Cloudflare dashboard
• No explicit networks section is required; services communicate on the default bridge network

Port Exposure:

• Neither service exposes ports to the host (ports directive not used)
• All external access routes through the Cloudflare Tunnel
• Internal communication occurs on Docker’s isolated network

Sources: docker-compose.yml:1-18

graph TB
    Conf["mosquitto.conf"]
Block1["Listener Configuration 1"]
L1Port["listener 1883\n(line 1)"]
L1Anon["allow_anonymous true\n(line 2)"]
Block2["Listener Configuration 2"]
L2Port["listener 9001\n(line 4)"]
L2Proto["protocol websockets\n(line 5)"]
Conf --> Block1
 
   Conf --> Block2
    
 
   Block1 --> L1Port
 
   Block1 --> L1Anon
    
 
   Block2 --> L2Port
 
   Block2 --> L2Proto
    
    Runtime1["Runtime Effect:\nTCP MQTT on 0.0.0.0:1883\nNo authentication required"]
Runtime2["Runtime Effect:\nWebSocket MQTT on 0.0.0.0:9001\nUses same allow_anonymous setting"]
L1Port --> Runtime1
 
   L1Anon --> Runtime1
 
   L2Port --> Runtime2
 
   L2Proto --> Runtime2

mosquitto.conf Reference

The mosquitto.conf file configures the Eclipse Mosquitto MQTT broker. It defines two listeners with different protocols.

File Structure

Sources: mosquitto.conf:1-6

Listener Directives

Listener 1: TCP MQTT (Port 1883)

Protocol: Native MQTT (TCP-based)
Bind address: 0.0.0.0 (all interfaces, default when not specified)
Authentication: None (anonymous access enabled)
Encryption: None (plaintext). Encryption is handled by Cloudflare Tunnel at the edge.

Sources: mosquitto.conf:1-2

Listener 2: WebSocket MQTT (Port 9001)

Protocol: MQTT over WebSockets
Bind address: 0.0.0.0 (default)
Authentication: Inherits allow_anonymous true from line 2
Encryption: None at broker level (handled by Cloudflare Tunnel)

Sources: mosquitto.conf:4-5

Directive Scope and Inheritance

The allow_anonymous true directive at mosquitto.conf2 has global scope and applies to all subsequent listeners. The configuration does not explicitly set allow_anonymous for the second listener, so it inherits the global setting.

Scope hierarchy:

1. Global directives apply to all listeners
2. Per-listener directives override global settings
3. Subsequent global directives override previous global directives

In this configuration:

• Line 2 sets global anonymous access to true
• Both listeners (lines 1 and 4) permit anonymous connections

Sources: mosquitto.conf:1-5

graph LR
    Client["MQTT Client\n(Browser or Native)"]
CFEdge["Cloudflare Edge\n(TLS termination)"]
Tunnel["Cloudflare Tunnel\n(cloudflared container)"]
Mosq9001["mosquitto:9001\n(WebSocket listener)"]
Mosq1883["mosquitto:1883\n(TCP listener)"]
Client -->|WSS/HTTPS| CFEdge
 
   CFEdge -->|Encrypted tunnel| Tunnel
 
   Tunnel -->|HTTP to mosquitto:9001| Mosq9001
    
 
   Mosq9001 -.->|Not directly accessible| Mosq1883
    
    Note1["listener 9001\nprotocol websockets\n(mosquitto.conf:4-5)"]
Note2["listener 1883\n(mosquitto.conf:1)"]
Mosq9001 --- Note1
    Mosq1883 --- Note2

Protocol Mapping to Cloudflare Tunnel

The Cloudflare Tunnel must be configured to route traffic to http://mosquitto:9001:

Critical configuration requirement: The Cloudflare Tunnel public hostname must route to http://mosquitto:9001 (the WebSocket listener), not port 1883. Port 1883 is the native MQTT protocol and cannot be proxied through HTTP-based Cloudflare Tunnels.

Sources: mosquitto.conf:1-5 docker-compose.yml:6-13

Security Implications

The allow_anonymous true directive at mosquitto.conf2 disables authentication:

Recommended for: Development, testing, or trusted environments where the Cloudflare Tunnel provides sufficient access control.

Not recommended for: Production environments with multiple tenants or sensitive data without additional access controls.

For authentication and ACL configuration, see page 6.1.

Sources: mosquitto.conf2

Environment Variables Reference

Environment variables provide runtime configuration, particularly for sensitive credentials that must not be committed to version control.

CLOUDFLARE_TUNNEL_TOKEN

Variable name: CLOUDFLARE_TUNNEL_TOKEN
Defined in: .env (user-created, not version controlled)
Template in: .env.sample:1
Referenced in: docker-compose.yml:14,17
Used by: cloudflared service

Purpose

This variable contains the authentication token for the Cloudflare Tunnel. The token is a long-lived credential that authorizes the cloudflared container to establish an outbound connection to Cloudflare’s network and receive inbound traffic routed through the tunnel.

Token format: Base64-encoded JSON Web Token (JWT) with tunnel metadata and credentials.

Sources: .env.sample1 docker-compose.yml:14-17

Token Lifecycle

Sources: .env.sample1 docker-compose.yml:14-17

Configuration Method

The token is injected into the cloudflared container via two mechanisms:

1. Environment variable declaration at docker-compose.yml:16-17:

This instructs Docker Compose to pass the variable from the host environment to the container.

2. Command substitution at docker-compose.yml14:

Docker Compose performs variable substitution before starting the container, replacing ${CLOUDFLARE_TUNNEL_TOKEN} with the actual token value.

Sources: docker-compose.yml:14-17

Security Best Practices

Sources: .env.sample1 .gitignore1

Validation and Troubleshooting

Token validation:

• Token is validated when cloudflared attempts to connect to Cloudflare
• Invalid tokens result in authentication failures logged in container output
• No local validation occurs before container startup

Common issues:

Sources: docker-compose.yml:14-17 .env.sample1

sequenceDiagram
    participant DC as docker-compose
    participant Env as .env file
    participant DCFile as docker-compose.yml
    participant MConf as mosquitto.conf
    participant MosqC as mosquitto container
    participant CFC as cloudflared container
    
    Note over DC,CFC: Configuration Loading Phase
    
    DC->>Env: Read CLOUDFLARE_TUNNEL_TOKEN
    DC->>DCFile: Parse service definitions
    
    Note over DCFile: services.mosquitto (lines 4-9)
    Note over DCFile: services.cloudflared (lines 11-17)
    
    DC->>MosqC: Create container from eclipse-mosquitto:latest
    DC->>MosqC: Mount ./mosquitto.conf to /mosquitto/config/mosquitto.conf
    
    DC->>CFC: Create container from cloudflare/cloudflared:latest
    DC->>CFC: Set environment variable CLOUDFLARE_TUNNEL_TOKEN
    DC->>CFC: Set command with --token flag
    
    Note over MosqC,CFC: Container Startup Phase
    
    MosqC->>MConf: Read configuration file
    Note over MConf: listener 1883 (line 1)
    Note over MConf: allow_anonymous true (line 2)
    Note over MConf: listener 9001 (line 4)
    Note over MConf: protocol websockets (line 5)
    
    MosqC->>MosqC: Initialize listeners 1883 and 9001
    
    CFC->>CFC: Execute tunnel run with token
    CFC->>CFC: Establish connection to Cloudflare

Configuration Loading Sequence

The following diagram shows the order in which configuration is loaded and applied during system startup:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

Service Configuration Matrix

The following table maps configuration sources to their effects on each service:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

graph TB
    Root["docker-compose.yml root"]
Version["version: '3.8'"]
Services["services:] MosqService[mosquitto:] MosqProps[Properties:\n- image\n- container_name\n- volumes\n- restart"]
CFService["cloudflared:] CFProps[Properties:\n- image\n- container_name\n- command\n- restart\n- environment"]
Root --> Version
 
   Root --> Services
 
   Services --> MosqService
 
   Services --> CFService
 
   MosqService --> MosqProps
 
   CFService --> CFProps

Configuration File Syntax

docker-compose.yml Syntax

The docker-compose.yml file follows Docker Compose version 3.8 specification. Key structural elements:

Sources: docker-compose.yml:1-18

graph LR
    Conf["mosquitto.conf"]
Block1["Listener Block 1:\nlistener 1883\nallow_anonymous true"]
Block2["Listener Block 2:\nlistener 9001\nprotocol websockets"]
Conf --> Block1
 
   Conf --> Block2
    
 
   Block1 --> Port1["Port: 1883"]
Block1 --> Anon["Anonymous: true"]
Block2 --> Port2["Port: 9001"]
Block2 --> Proto["Protocol: websockets"]

mosquitto.conf Syntax

The mosquitto.conf file uses the Mosquitto broker configuration format. Each directive appears on its own line:

Sources: mosquitto.conf:1-6

.env File Syntax

The .env file uses simple KEY=value syntax, one variable per line:

CLOUDFLARE_TUNNEL_TOKEN=your_token_here

Sources: .env.sample:1-3

Configuration Validation

The system validates configuration at multiple stages:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

Configuration Override Hierarchy

When configuration values can be specified in multiple locations, the following precedence applies:

1. Command-line arguments to docker-compose (highest precedence)
2. Environment variables in the shell running docker-compose
3. .env file in the project directory
4. Default values in docker-compose.yml
5. Container defaults from images (lowest precedence)

For the mosquitto service, the configuration file mosquitto.conf:1-6 is mounted as a volume and overrides all default Mosquitto configurations.

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

Cross-Reference Index

The following table provides a quick reference for locating configuration settings:

Sources: docker-compose.yml:1-18 mosquitto.conf:1-6 .env.sample:1-3

Dismiss

Refresh this wiki

Enter email to refresh

docker-compose.yml

Loading…

docker-compose.yml Reference

Relevant source files

• docker-compose.yml

Purpose and Scope

This document provides a complete technical reference for the docker-compose.yml file, which orchestrates both the mosquitto MQTT broker and cloudflared tunnel services. It covers all configuration properties, service definitions, volume mounts, environment variables, and restart policies used in the system.

For conceptual information about how Docker Compose orchestrates the services, see page 3.3. For deployment procedures, see page 2.4. For environment variable setup, see page 4.3.

Sources: docker-compose.yml:1-18

File Location and Structure

The docker-compose.yml file is located in the repository root directory and uses Docker Compose file format version 3.8. The file defines a multi-container application with two services that work together to provide secure, externally-accessible MQTT brokering.

graph TB
    subgraph "docker-compose.yml Structure"
        Root["version: '3.8'"]
Services["services:]
        
        subgraph Service Definitions"
            Mosquitto["mosquitto:]
            Cloudflared[cloudflared:]
        end
        
        subgraph Mosquitto Properties"
            MQ_Image["image: eclipse-mosquitto:latest"]
MQ_Container["container_name: mosquitto"]
MQ_Volumes["volumes: [./mosquitto.conf mount]"]
MQ_Restart["restart: unless-stopped"]
end
        
        subgraph "Cloudflared Properties"
            CF_Image["image: cloudflare/cloudflared:latest"]
CF_Container["container_name: cloudflared"]
CF_Command["command: tunnel ... run --token"]
CF_Restart["restart: unless-stopped"]
CF_Env["environment: [CLOUDFLARE_TUNNEL_TOKEN]"]
end
    end
    
 
   Root --> Services
 
   Services --> Mosquitto
 
   Services --> Cloudflared
    
 
   Mosquitto --> MQ_Image
 
   Mosquitto --> MQ_Container
 
   Mosquitto --> MQ_Volumes
 
   Mosquitto --> MQ_Restart
    
 
   Cloudflared --> CF_Image
 
   Cloudflared --> CF_Container
 
   Cloudflared --> CF_Command
 
   Cloudflared --> CF_Restart
 
   Cloudflared --> CF_Env

High-Level Structure

Sources: docker-compose.yml:1-18

Version Specification

The file uses Docker Compose file format version 3.8, which supports all features required by this system including service definitions, volume mounts, environment variables, and restart policies. Version 3.8 is compatible with Docker Engine 19.03.0+ and provides the necessary capabilities for container orchestration.

Sources: docker-compose.yml1

Services Overview

The services section defines two containerized services that comprise the complete system. Both services run continuously and restart automatically on failure.

graph LR
    subgraph "Docker Compose Services"
        subgraph "mosquitto Service"
            MQ_Runtime["Container: mosquitto"]
MQ_Base["Base Image: eclipse-mosquitto:latest"]
MQ_Config["Config Volume Mount"]
MQ_Policy["Restart: unless-stopped"]
end
        
        subgraph "cloudflared Service"
            CF_Runtime["Container: cloudflared"]
CF_Base["Base Image: cloudflare/cloudflared:latest"]
CF_Token["Environment: CLOUDFLARE_TUNNEL_TOKEN"]
CF_Cmd["Command: tunnel run"]
CF_Policy["Restart: unless-stopped"]
end
    end
    
    subgraph "External Resources"
        MosqConf["./mosquitto.conf"]
EnvFile[".env File"]
end
    
 
   MosqConf -.-> MQ_Config
 
   EnvFile -.-> CF_Token
    
 
   CF_Runtime -->|Proxies to| MQ_Runtime

Service Composition Diagram

Sources: docker-compose.yml:3-18

Mosquitto Service Configuration

The mosquitto service runs the Eclipse Mosquitto MQTT broker. It is defined starting at line 4 and includes image specification, container naming, volume configuration, and restart policy.

Service Properties

Image Specification

docker-compose.yml5 specifies eclipse-mosquitto:latest as the base image. This pulls the official Mosquitto image from Docker Hub. The latest tag ensures the most recent stable version is used, though this can be pinned to a specific version for production deployments.

Container Name

docker-compose.yml6 sets a fixed container name mosquitto. This serves two purposes:

1. Provides predictable DNS resolution within Docker’s internal network
2. Enables the cloudflared service to reference the broker at mosquitto:9001

Volume Mount Configuration

docker-compose.yml:7-8 configures a bind mount that makes the broker configuration available to the container:

volumes:
  - ./mosquitto.conf:/mosquitto/config/mosquitto.conf

graph LR
    HostFS["Host Filesystem\n./mosquitto.conf"]
Mount["Volume Mount\nBind Type"]
ContainerFS["Container Filesystem\n/mosquitto/config/mosquitto.conf"]
Process["mosquitto Process\nReads Config"]
HostFS -->|Mounted by Docker| Mount
 
   Mount -->|Accessible at| ContainerFS
 
   ContainerFS -->|Read by| Process

This mount allows configuration changes without rebuilding the container image. The mosquitto process reads this configuration on startup.

Volume Mount Flow

Sources: docker-compose.yml:4-9

Cloudflared Service Configuration

The cloudflared service establishes a secure tunnel to Cloudflare’s network. It is defined starting at line 11 and includes image specification, container naming, command configuration, environment variables, and restart policy.

Service Properties

Image Specification

docker-compose.yml12 specifies cloudflare/cloudflared:latest as the base image. This is the official Cloudflare Tunnel client maintained by Cloudflare.

Command Override

docker-compose.yml14 overrides the default container command with:

tunnel --no-autoupdate run --token ${CLOUDFLARE_TUNNEL_TOKEN}

Environment Variables

docker-compose.yml:16-17 declares the environment variable section:

graph TB
    EnvFile[".env File\nCLOUDFLARE_TUNNEL_TOKEN=xxx"]
Compose["docker-compose.yml\nEnvironment Declaration"]
Runtime["Container Runtime Environment\nCLOUDFLARE_TUNNEL_TOKEN=xxx"]
Command["Command Execution\ntunnel run --token xxx"]
EnvFile -->|Read by docker-compose| Compose
 
   Compose -->|Passes to container| Runtime
 
   Runtime -->|Interpolated in| Command

environment:
  - CLOUDFLARE_TUNNEL_TOKEN

This configuration tells Docker Compose to pass the CLOUDFLARE_TUNNEL_TOKEN environment variable from the host (typically loaded from .env file) into the container. The variable’s value is then used in the command string via ${CLOUDFLARE_TUNNEL_TOKEN} interpolation.

Environment Variable Flow

Sources: docker-compose.yml:11-17

Restart Policy Configuration

Both services use restart: unless-stopped docker-compose.yml:9-15 This restart policy ensures containers automatically restart under most failure conditions but respect explicit stop commands.

Restart Policy Behavior

Alternative Restart Policies

While this system uses unless-stopped, Docker Compose supports other policies:

Sources: docker-compose.yml:9-15

graph TB
    subgraph "Docker Default Bridge Network"
        subgraph "cloudflared Container"
            CF_Process["cloudflared process"]
CF_DNS["DNS Resolution:\nmosquitto resolves to container IP"]
end
        
        subgraph "mosquitto Container"
            MQ_Process["mosquitto process"]
MQ_Listener["Listener: 0.0.0.0:9001"]
end
        
 
       CF_Process -->|HTTP Proxy to mosquitto:9001| CF_DNS
 
       CF_DNS -->|Resolves via Docker DNS| MQ_Listener
    end
    
    External["External Traffic\nfrom Cloudflare"]
External -.->|Via Tunnel| CF_Process

Service-to-Service Communication

Although not explicitly defined in the compose file, Docker Compose creates a default network for all services, enabling internal communication.

Internal Networking Model

The cloudflared service proxies traffic to mosquitto:9001, where mosquitto is resolved via Docker’s internal DNS to the mosquitto container’s IP address. This is made possible by the fixed container_name properties.

Sources: docker-compose.yml:6-13

Complete Property Reference

Top-Level Properties

Mosquitto Service Properties

Cloudflared Service Properties

Sources: docker-compose.yml:1-18

Deployment Commands

The following commands operate on this docker-compose.yml file:

Sources: docker-compose.yml:1-18

File Modification Considerations

When modifying docker-compose.yml, consider the following:

Image Version Pinning

The current configuration uses latest tags docker-compose.yml:5-12 For production environments, consider pinning specific versions:

Network Isolation

To add explicit network configuration:

Port Exposure

The current configuration does not expose ports to the host, which is intentional (all traffic goes through Cloudflare Tunnel). To expose ports for testing:

⚠️ Security Warning: Exposing ports bypasses the Cloudflare Tunnel security layer and should only be done in controlled environments.

Sources: docker-compose.yml:1-18

Configuration Validation

To validate the docker-compose.yml syntax:

This command parses the file, interpolates environment variables, and displays the resolved configuration. It will report syntax errors and missing environment variables.

Sources: docker-compose.yml:1-18

Dismiss

Refresh this wiki

Enter email to refresh

mosquitto.conf

Loading…

mosquitto.conf Reference

Relevant source files

• mosquitto.conf

Purpose and Scope

This page provides complete technical reference documentation for the mosquitto.conf configuration file used in this system. The file defines the MQTT broker’s runtime behavior, including network listeners, protocol support, and access control settings.

For conceptual information about Mosquitto configuration and setup procedures, see Mosquitto Configuration. For detailed documentation of the Mosquitto broker component itself, see Mosquitto MQTT Broker. For listener-specific implementation details, see MQTT Listeners and Anonymous Access.

Sources: mosquitto.conf:1-6

File Location and Integration

The mosquitto.conf file resides in the project root directory and is mounted as a read-only volume into the mosquitto container at runtime. The file is version-controlled and contains no secrets.

graph TB
    subgraph "Version Control"
        MosqConf["mosquitto.conf\n(Project Root)"]
end
    
    subgraph "Docker Compose"
        ComposeYML["docker-compose.yml"]
VolumeMount["Volume Mount Definition\n./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"]
end
    
    subgraph "Container Runtime"
        MosqContainer["mosquitto Container\n(eclipse-mosquitto:latest)"]
MosqProcess["mosquitto Process\nReads Config at Startup"]
end
    
 
   MosqConf --> ComposeYML
 
   ComposeYML --> VolumeMount
 
   VolumeMount --> MosqContainer
 
   MosqContainer --> MosqProcess

Docker Compose Integration

Diagram: mosquitto.conf Mount and Load Path

The configuration is mounted read-only (:ro flag) to prevent the container from modifying the configuration file. The mosquitto process reads this configuration file during container initialization.

Sources: mosquitto.conf:1-6 docker-compose.yml

Configuration Overview

The current mosquitto.conf implements a minimal configuration optimized for accessibility and simplicity. It defines two network listeners with different protocols and enables anonymous client connections.

graph TB
    subgraph "mosquitto.conf"
        RootConfig["Configuration Root"]
subgraph "First Listener Block"
            Listener1["listener 1883"]
Anonymous["allow_anonymous true"]
end
        
        subgraph "Second Listener Block"
            Listener2["listener 9001"]
Protocol["protocol websockets"]
end
        
 
       RootConfig --> Listener1
 
       Listener1 --> Anonymous
        
 
       RootConfig --> Listener2
 
       Listener2 --> Protocol
    end
    
    subgraph "Runtime Behavior"
        Port1883["TCP Port 1883\nStandard MQTT Protocol"]
Port9001["TCP Port 9001\nMQTT over WebSockets"]
AnonymousAccess["All Clients Accepted\nNo Authentication Required"]
end
    
 
   Listener1 --> Port1883
 
   Listener2 --> Port9001
 
   Anonymous --> AnonymousAccess

Active Configuration Structure

Diagram: Configuration Structure and Runtime Mapping

Sources: mosquitto.conf:1-6

Directive Reference

listener

Syntax: listener <port> [<bind_address>]

Purpose: Defines a network listener that accepts incoming MQTT client connections.

Parameters:

Behavior:

• Multiple listener directives create multiple independent listeners
• Each listener can be configured with different protocols and security settings
• Configuration directives following a listener apply to that specific listener until the next listener directive
• When no bind address is specified, the listener binds to all available network interfaces (0.0.0.0)

Current Usage:

mosquitto.conf1 defines the first listener:

listener 1883

This creates a listener on port 1883 (the IANA-registered standard MQTT port) bound to all interfaces.

mosquitto.conf4 defines the second listener:

listener 9001

This creates a listener on port 9001 (commonly used for MQTT WebSockets) bound to all interfaces.

Sources: mosquitto.conf1 mosquitto.conf4

allow_anonymous

Syntax: allow_anonymous <true|false>

Purpose: Controls whether clients can connect without providing authentication credentials.

Parameters:

Behavior:

• When set to true: Clients may connect without providing a username or password
• When set to false: All clients must authenticate using username/password or certificate-based authentication
• This setting applies to all listeners unless overridden by listener-specific configuration
• Default value: false (as of Mosquitto 2.0+)

Security Implications:

• Anonymous access is appropriate for trusted networks or development environments
• Production deployments should typically disable anonymous access and implement authentication
• When anonymous access is enabled, no per-client authorization checks occur unless ACLs are configured

Current Usage:

mosquitto.conf2 enables anonymous access:

allow_anonymous true

This configuration allows any client to connect to either listener (port 1883 or port 9001) without authentication.

Sources: mosquitto.conf2

protocol

Syntax: protocol <protocol_type>

Purpose: Specifies the MQTT protocol variant for a specific listener.

Parameters:

Behavior:

• Must be specified within a listener block (after a listener directive)
• Applies only to the immediately preceding listener
• When set to mqtt: Standard MQTT protocol over TCP (default behavior)
• When set to websockets: MQTT protocol encapsulated in WebSocket frames

Protocol Variants:

WebSocket Protocol Details:

• Enables MQTT communication from browser-based JavaScript clients
• WebSocket frames provide HTTP-compatible upgrade mechanism
• Allows MQTT traffic to traverse HTTP proxies and firewalls
• Implements RFC 6455 (WebSocket Protocol)

Current Usage:

mosquitto.conf5 configures the 9001 listener for WebSockets:

protocol websockets

This enables MQTT-over-WebSocket support on port 9001, while port 1883 uses standard MQTT (default when protocol is not specified).

Sources: mosquitto.conf5

graph LR
    subgraph "mosquitto.conf Directives"
        Line1["listener 1883\n(Line 1)"]
Line2["allow_anonymous true\n(Line 2)"]
Line4["listener 9001\n(Line 4)"]
Line5["protocol websockets\n(Line 5)"]
end
    
    subgraph "Listener 1 Runtime Config"
        L1Port["Bind Port: 1883"]
L1Protocol["Protocol: mqtt (default)"]
L1Auth["Auth: Anonymous Allowed"]
end
    
    subgraph "Listener 2 Runtime Config"
        L2Port["Bind Port: 9001"]
L2Protocol["Protocol: websockets"]
L2Auth["Auth: Anonymous Allowed (inherited)"]
end
    
 
   Line1 --> L1Port
 
   Line1 --> L1Protocol
 
   Line2 --> L1Auth
 
   Line2 --> L2Auth
    
 
   Line4 --> L2Port
 
   Line5 --> L2Protocol

Complete Configuration Map

The following diagram shows how each directive in mosquitto.conf maps to runtime broker behavior:

Diagram: Directive-to-Runtime Configuration Mapping

Sources: mosquitto.conf:1-6

Configuration Directives Not Present

The current configuration uses only three directives. Mosquitto supports numerous additional directives for advanced functionality. Common directives not present in this configuration include:

Authentication and Authorization

TLS/SSL Configuration

Persistence and Logging

Connection Limits

For advanced configuration including ACL-based access control, see the protected-no-wildcard branch documentation at Topic Access Control (ACL).

Sources: mosquitto.conf:1-6

graph TB
    subgraph "Configuration Layer"
        MosqConf["mosquitto.conf"]
ComposeYML["docker-compose.yml"]
EnvFile[".env"]
end
    
    subgraph "Container Layer"
        MosqContainer["mosquitto container\n(eclipse-mosquitto:latest)"]
CFDContainer["cloudflared container"]
end
    
    subgraph "Mosquitto Configuration Application"
        Listener1883["Listener: Port 1883\nProtocol: mqtt\nFrom: mosquitto.conf:1"]
Listener9001["Listener: Port 9001\nProtocol: websockets\nFrom: mosquitto.conf:4-5"]
AuthPolicy["Anonymous Access: Enabled\nFrom: mosquitto.conf:2"]
end
    
    subgraph "Traffic Flow"
        CFProxy["cloudflared proxies to\nmosquitto:9001"]
ExternalClients["External MQTT Clients\n(via Cloudflare Tunnel)"]
InternalClients["Internal MQTT Clients\n(direct to port 1883)"]
end
    
 
   MosqConf -->|Volume Mount| MosqContainer
 
   ComposeYML -->|Orchestrates| MosqContainer
 
   ComposeYML -->|Orchestrates| CFDContainer
 
   EnvFile -->|Provides Token to| CFDContainer
    
 
   MosqContainer --> Listener1883
 
   MosqContainer --> Listener9001
 
   MosqContainer --> AuthPolicy
    
 
   CFProxy -->|WebSocket Connection| Listener9001
 
   ExternalClients -->|Through Cloudflare| CFProxy
 
   InternalClients -->|Direct TCP| Listener1883
    
 
   AuthPolicy -.->|Applies to| Listener1883
 
   AuthPolicy -.->|Applies to| Listener9001

Relationship to System Architecture

The mosquitto.conf file configures the MQTT broker component within the larger system architecture:

Diagram: mosquitto.conf in System Context

The configuration file directly controls broker behavior, while Docker Compose handles orchestration and the Cloudflare tunnel handles external routing. Note that cloudflared proxies specifically to port 9001 (WebSocket listener), making this the primary entry point for external clients.

Sources: mosquitto.conf:1-6 docker-compose.yml

Configuration Modification Guidelines

Modifying the Configuration

1. Edit mosquitto.conf in the project root directory

2. Restart the mosquitto container to apply changes:

3. Verify configuration by checking container logs:

Common Configuration Changes

Disabling Anonymous Access:

allow_anonymous false
password_file /mosquitto/config/password.txt

Enabling TLS on WebSocket Listener:

listener 9001
protocol websockets
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Adding Standard MQTT over TLS:

listener 8883
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Note that any additional files (passwords, certificates, ACLs) must be mounted into the container via additional volume mounts in docker-compose.yml.

Sources: mosquitto.conf:1-6 docker-compose.yml

Validation and Testing

After modifying mosquitto.conf, validate the configuration before deployment:

Syntax Validation

The mosquitto process validates configuration on startup. Invalid configurations will prevent container startup. Check logs for validation errors:

Configuration errors appear in startup logs with the format:

Error: <description of error>

Testing Listener Configuration

Test each configured listener independently:

Port 1883 (Standard MQTT):

Port 9001 (WebSockets): Requires a WebSocket-capable MQTT client. Browser-based clients can connect to:

ws://localhost:9001

For testing WebSocket connectivity through the Cloudflare tunnel, use the public hostname configured in the Cloudflare dashboard.

Sources: mosquitto.conf:1-6

File Format Specifications

Syntax Rules

Directive Scope

Configuration directives fall into two categories:

Global Directives:

• Apply to the entire broker instance
• Examples: allow_anonymous, persistence, log_dest
• Typically appear before any listener directives

Listener-Specific Directives:

• Apply only to the immediately preceding listener
• Examples: protocol, cafile, certfile
• Must follow a listener directive

In mosquitto.conf:1-6 allow_anonymous is a global directive (line 2) that applies to all listeners, while protocol is listener-specific (line 5) and applies only to the port 9001 listener.

Sources: mosquitto.conf:1-6

Dismiss

Refresh this wiki

Enter email to refresh

Environment Variables

Loading…

Environment Variables

Relevant source files

• .env.sample
• .gitignore

Purpose and Scope

This document provides a comprehensive reference for all environment variables used in the Docker MQTT Mosquitto with Cloudflare Tunnel system. It covers the .env file structure, the .env.sample template, and security practices for managing sensitive credentials.

For information about the Docker Compose configuration that consumes these variables, see docker-compose.yml. For the initial setup process of configuring environment variables, see Local Configuration. For version control practices related to secret management, see Version Control Best Practices.

Environment Variable System Overview

The system uses a file-based environment variable pattern where secrets are stored in a .env file that is explicitly excluded from version control. A template file, .env.sample, is committed to the repository to document the required variables without exposing actual values.

File Structure

project-root/
├── .env                  # Actual secrets (gitignored)
├── .env.sample           # Template (version controlled)
├── .gitignore           # Excludes .env
└── docker-compose.yml   # Consumes environment variables

Sources : .env.sample1 .gitignore1

Environment Variable File Relationship

Analysis : This diagram shows the critical separation between template and actual secrets. The .env.sample file serves as documentation in version control, while .env contains actual credentials and is explicitly excluded by .gitignore. Developers copy the template and populate it with real values obtained from the Cloudflare dashboard.

Sources : .env.sample1 .gitignore1

CLOUDFLARE_TUNNEL_TOKEN

The system uses a single environment variable for authentication and configuration.

Variable Specification

Sources : .env.sample1

Purpose and Function

The CLOUDFLARE_TUNNEL_TOKEN is a JSON Web Token (JWT) that contains:

• Tunnel identification information
• Authentication credentials
• Routing configuration
• Cryptographic signatures

This token authorizes the cloudflared container to establish an outbound connection to Cloudflare’s network and route traffic to the local Mosquitto broker.

Token Format

The token is a base64-encoded JWT string with the following characteristics:

• Length: Approximately 500-800 characters
• Format: eyJ... (standard JWT prefix)
• Components: Header, payload, and signature concatenated with dots

Example from template :

CLOUDFLARE_TUNNEL_TOKEN=your_token

Sources : .env.sample1

Obtaining the Token

The token is generated through the Cloudflare Zero Trust dashboard during tunnel creation. See Cloudflare Tunnel Setup for detailed instructions. The token should be copied from the dashboard and placed in the .env file.

sequenceDiagram
    participant User as "User"
    participant Dashboard as "Cloudflare Dashboard"
    participant EnvSample as ".env.sample"
    participant EnvFile as ".env (local)"
    participant Compose as "docker-compose.yml"
    participant Container as "cloudflared container"
    participant Tunnel as "Cloudflare Tunnel Service"
    
    User->>Dashboard: 1. Create tunnel
    Dashboard-->>User: 2. Generate CLOUDFLARE_TUNNEL_TOKEN
    
    User->>EnvSample: 3. Read template
    EnvSample-->>User: CLOUDFLARE_TUNNEL_TOKEN=your_token
    
    User->>EnvFile: 4. Create .env file
    User->>EnvFile: 5. Paste actual token
    
    Note over Compose: docker-compose up
    
    Compose->>EnvFile: 6. Read environment variables
    EnvFile-->>Compose: CLOUDFLARE_TUNNEL_TOKEN=eyJh...
    
    Compose->>Container: 7. Start container with env var
    Container->>Container: 8. cloudflared tunnel run
    Container->>Tunnel: 9. Authenticate with token
    Tunnel-->>Container: 10. Tunnel established
    
    Note over Container,Tunnel: Persistent outbound connection\nmaintained for traffic routing

Token Lifecycle and Usage

Analysis : The token is generated once during tunnel creation and remains valid until the tunnel is deleted or the token is rotated. The token is read from .env at container startup and used by the cloudflared tunnel run command to authenticate with Cloudflare’s network.

Sources : .env.sample1

Security Architecture

graph LR
    subgraph "Files That Can Be Committed"
        SAMPLE[".env.sample\nTemplate only"]
README["README.md"]
COMPOSE["docker-compose.yml"]
MOSQUITTO["mosquitto.conf"]
GITIGNORE_FILE[".gitignore"]
end
    
    subgraph "Files That Must Not Be Committed"
        ENV[".env\nContains actual token"]
DATA["data/*\nMosquitto persistence"]
end
    
    subgraph ".gitignore Rules"
        RULE1["Line 1: .env"]
RULE2["Line 2: data/*"]
end
    
 
   RULE1 -.->|excludes| ENV
 
   RULE2 -.->|excludes| DATA
    
 
   SAMPLE -.->|safe to commit| README
 
   ENV -.->|blocked by gitignore| SAMPLE

The .gitignore Boundary

The .gitignore file establishes a security boundary that prevents accidental exposure of secrets to version control.

Analysis : The .gitignore file contains two critical rules. Line 1 excludes .env to prevent token exposure. Line 2 excludes data/* to prevent committing Mosquitto’s persistence data, which may contain message history or subscriber information.

Sources : .gitignore:1-2

File Contents and Security Model

.env.sample (Template File)

Located at .env.sample1 this file provides:

• Documentation of required variables

• Example structure (not functional values)

• Onboarding guide for new developers

  CLOUDFLARE_TUNNEL_TOKEN=your_token

The value your_token is a placeholder and will not work for authentication. Developers must replace it with an actual token from the Cloudflare dashboard.

Security Properties :

• Safe to commit to public repositories
• Contains no sensitive information
• Serves as self-documenting configuration reference

.env (Actual Secrets File)

Not present in the repository; created locally by developers. Contains:

• Real CLOUDFLARE_TUNNEL_TOKEN value
• Full JWT string with authentication credentials

Security Properties :

• Excluded from version control via .gitignore1
• Should have restrictive file permissions (chmod 600 .env)
• Must never be shared publicly or committed to Git

Sources : .env.sample1 .gitignore1

graph TB
    subgraph "Filesystem"
        ENV_FILE[".env file"]
end
    
    subgraph "Docker Compose Process"
        COMPOSE_CMD["docker-compose up"]
COMPOSE_PARSER["YAML Parser"]
COMPOSE_ENGINE["Docker Engine API"]
end
    
    subgraph "docker-compose.yml"
        SERVICE_DEF["cloudflared service definition"]
ENV_REF["environment:\n - CLOUDFLARE_TUNNEL_TOKEN"]
end
    
    subgraph "Container Runtime"
        CONTAINER["cloudflared container"]
PROCESS["cloudflared tunnel run"]
ENV_VAR["CLOUDFLARE_TUNNEL_TOKEN\nenvironment variable"]
end
    
 
   ENV_FILE -->|1. read automatically| COMPOSE_CMD
 
   COMPOSE_CMD --> COMPOSE_PARSER
 
   COMPOSE_PARSER -->|2. parse service config| SERVICE_DEF
 
   SERVICE_DEF --> ENV_REF
 
   ENV_REF -->|3. resolve variable| ENV_FILE
 
   ENV_FILE -->|4. substitute value| COMPOSE_ENGINE
 
   COMPOSE_ENGINE -->|5. create container with env| CONTAINER
 
   CONTAINER -->|6. start process| PROCESS
 
   PROCESS -->|7. read env var| ENV_VAR

Integration with Docker Compose

The docker-compose.yml file consumes environment variables from the .env file automatically through Docker Compose’s built-in environment file support.

Environment Variable Injection Flow

Analysis : Docker Compose automatically loads the .env file from the project root directory. When it encounters environment variable references in docker-compose.yml, it substitutes values from the .env file before passing them to the Docker Engine. The cloudflared process can then access CLOUDFLARE_TUNNEL_TOKEN as a standard environment variable.

Sources : .env.sample1

graph LR
    subgraph "Environment Variables"
        TOKEN["CLOUDFLARE_TUNNEL_TOKEN"]
end
    
    subgraph "Containers"
        CFD["cloudflared\n✓ Has access"]
MOSQ["mosquitto\n✗ No access"]
end
    
 
   TOKEN -->|injected via environment| CFD
 
   TOKEN -.->|not available| MOSQ

Variable Scoping

The CLOUDFLARE_TUNNEL_TOKEN is only available to the cloudflared container. The mosquitto container does not have access to this variable, demonstrating principle of least privilege.

Sources : .env.sample1

Best Practices

Local Development

1. Initial Setup :

   • Copy .env.sample1 to .env
   • Obtain token from Cloudflare dashboard (see Cloudflare Tunnel Setup)
   • Replace your_token with actual JWT token
   • Verify .env is listed in .gitignore1

2. File Permissions :

Restricts read/write access to the file owner only.

3. Verification : Before starting containers, verify the token is populated:

If this returns empty, the token has not been configured.

Production Deployment

For production environments, consider alternatives to file-based secrets:

Production deployments should:

• Use secrets management systems instead of .env files
• Implement automatic token rotation
• Enable audit logging for secret access
• Use read-only access where possible

graph TB
    subgraph "Common Mistakes (DO NOT DO)"
        COMMIT["❌ Committing .env to Git"]
HARDCODE["❌ Hardcoding token in docker-compose.yml"]
PUBLIC["❌ Posting token in issues/forums"]
SHARE["❌ Sharing .env file via email/chat"]
PERMISSIONS["❌ World-readable .env file"]
end
    
    subgraph "Correct Practices (DO THIS)"
        GITIGNORE_CHECK["✓ Verify .env in .gitignore"]
ENV_PATTERN["✓ Use environment variable pattern"]
ROTATE["✓ Rotate tokens regularly"]
RESTRICT["✓ Restrict file permissions"]
SECRETS_MGR["✓ Use secrets manager in production"]
end
    
 
   COMMIT -.->|leads to| TOKEN_LEAK["Token Exposure"]
HARDCODE -.->|leads to| TOKEN_LEAK
 
   PUBLIC -.->|leads to| TOKEN_LEAK
 
   SHARE -.->|leads to| TOKEN_LEAK
 
   PERMISSIONS -.->|leads to| TOKEN_LEAK
    
 
   TOKEN_LEAK -.->|enables| UNAUTHORIZED["Unauthorized Access"]

Token Rotation

The CLOUDFLARE_TUNNEL_TOKEN can be rotated by:

1. Creating a new tunnel in the Cloudflare dashboard
2. Updating the .env file with the new token
3. Restarting containers: docker-compose restart cloudflared

Common Security Mistakes

Sources : .gitignore1

Troubleshooting

Token Not Found Error

Symptom : cloudflared container fails to start with error about missing token.

Diagnosis :

1. Verify .env file exists in project root
2. Check token variable name is exactly CLOUDFLARE_TUNNEL_TOKEN
3. Ensure no extra spaces or quotes around the token value

Solution : Create or correct the .env file using .env.sample1 as template.

Token Authentication Failed

Symptom : cloudflared container starts but fails to establish tunnel.

Diagnosis :

1. Token may be invalid or expired
2. Token may be from a different tunnel
3. Tunnel may have been deleted in Cloudflare dashboard

Solution : Generate new token from Cloudflare dashboard and update .env file.

.env File Accidentally Committed

Symptom : .env file appears in Git history.

Immediate Actions :

1. Rotate token immediately in Cloudflare dashboard
2. Remove file from Git history using git filter-branch or BFG Repo-Cleaner
3. Update .env with new token
4. Verify .gitignore1 contains .env

Environment Variable Reference Table

Sources : .env.sample1

Related Documentation

• docker-compose.yml - How environment variables are consumed in Docker Compose
• Cloudflared Tunnel Connector - How the cloudflared container uses the token
• Local Configuration - Setup instructions for creating .env file
• Security Model - Overall security architecture and secret management
• Version Control Best Practices - Git workflows for secrets

Sources : .env.sample1 .gitignore:1-2

Dismiss

Refresh this wiki

Enter email to refresh

CI/CD and Automation

Loading…

CI/CD and Automation

Relevant source files

• .github/workflows/build-docs.yml
• .github/workflows/ci.yml

Purpose and Scope

This document describes the automated testing and documentation build systems that ensure code quality and maintain up-to-date documentation for the Docker MQTT Mosquitto Cloudflare Tunnel system.

The system implements two distinct automation pipelines:

1. Continuous Integration Pipeline - Validates that the Mosquitto service can successfully start on every commit
2. Documentation Build Pipeline - Generates and deploys wiki documentation to GitHub Pages

This page is organized into three main sections:

• Continuous Integration (Section 5.1) - Details the automated testing workflow
• Documentation Pipeline (Section 5.2) - Explains the documentation generation and deployment process
• Version Control Best Practices (Section 5.3) - Covers Git workflow and secret management in the context of CI/CD

For general system setup, see page 2 (Getting Started). For component details, see page 3 (Components).

Sources: .github/workflows/ci.yml, .github/workflows/build-docs.yml, .gitignore

Automation Pipeline Overview

The system uses GitHub Actions to automate quality assurance and documentation maintenance. Both pipelines execute in isolated GitHub-hosted runners and operate independently.

Pipeline Comparison

Sources: .github/workflows/ci.yml, .github/workflows/build-docs.yml

Automation Architecture

Diagram: GitHub Actions Pipeline Architecture

This diagram illustrates the two independent automation pipelines. The CI pipeline .github/workflows/ci.yml:1-43 executes on code changes, while the documentation pipeline .github/workflows/build-docs.yml:1-81 runs on a weekly schedule. Both use GitHub-hosted runners but have different trigger mechanisms and purposes.

Sources: .github/workflows/ci.yml, .github/workflows/build-docs.yml

5.1 Continuous Integration

The CI pipeline validates that the Mosquitto MQTT broker can successfully start in a Docker environment. This automated test runs on every push to main and on all pull requests targeting main.

Workflow Configuration

The workflow is defined in .github/workflows/ci.yml:1-43 with the following key elements:

Trigger Configuration .github/workflows/ci.yml:3-9:

Job Definition .github/workflows/ci.yml:11-13:

• Job Name: test-mosquitto
• Runner: ubuntu-latest
• Purpose: Validate Mosquitto container can start and reach running state

CI Execution Steps

Health Check Mechanism

Diagram: Health Check Loop Logic

The health check loop .github/workflows/ci.yml:28-39 implements a polling strategy with bounded retry:

This bash loop:

• Executes up to 10 iterations
• Uses docker inspect to query container state
• Checks if status contains “running”
• Waits 10 seconds between attempts
• Fails after 100 seconds total (10 × 10s)

Sources: .github/workflows/ci.yml:28-39

Why Only Mosquitto Is Tested

The CI pipeline starts only the mosquitto service, not the cloudflared service .github/workflows/ci.yml25:

Rationale:

• The cloudflared container requires CLOUDFLARE_TUNNEL_TOKEN environment variable
• This token is a secret that cannot be exposed in public CI logs
• The mosquitto service has no external dependencies and can run in isolation
• Starting Mosquitto validates the core MQTT broker functionality

The docker-compose.yml file docker-compose.yml:4-9 defines mosquitto as an independent service that doesn’t depend on cloudflared, enabling this isolated testing approach.

Sources: .github/workflows/ci.yml:25, docker-compose.yml:4-9

Failure Scenarios

When the CI workflow fails, it blocks pull request merges, preventing broken configurations from entering the main branch.

Sources: .github/workflows/ci.yml:28-42

5.2 Documentation Pipeline

The documentation pipeline automatically generates and deploys technical documentation to GitHub Pages. It uses the DeepWiki documentation generation system to create an mdBook-formatted static site from the repository’s codebase.

Workflow Configuration

The workflow is defined in .github/workflows/build-docs.yml:1-81 with distinct build and deploy jobs.

Trigger Configuration .github/workflows/build-docs.yml:3-7:

The pipeline executes in two scenarios:

1. Scheduled: Every Sunday at 00:00 UTC via cron schedule
2. Manual: Triggered through GitHub UI via workflow_dispatch

Permissions .github/workflows/build-docs.yml:9-12:

These permissions enable:

• Reading repository contents
• Writing to GitHub Pages deployment
• Generating OIDC tokens for secure deployment

Build Job

The build job .github/workflows/build-docs.yml:19-69 performs documentation generation:

Diagram: Documentation Build Job Flow

Step 1: Repository Resolution

.github/workflows/build-docs.yml:25-52 determines which repository to document:

This logic allows manual workflow dispatch to specify a different repository, defaulting to the current repository (github.repository context variable).

Step 2: Title Generation

.github/workflows/build-docs.yml:37-47 generates the documentation book title:

For this repository, the generated title would be: "docker-mqtt-mosquitto-cloudflare-tunnel Documentation"

Step 3: DeepWiki Generation

.github/workflows/build-docs.yml:59-64 invokes the DeepWiki documentation generator:

The jzombie/deepwiki-to-mdbook action:

• Analyzes the repository structure
• Generates markdown documentation pages
• Creates an mdBook configuration
• Outputs static HTML to ./output/book

Step 4: Artifact Upload

.github/workflows/build-docs.yml:66-69 uploads the generated documentation:

This creates a GitHub Actions artifact containing the compiled mdBook site, which is consumed by the deploy job.

Sources: .github/workflows/build-docs.yml:19-69

Deploy Job

The deploy job .github/workflows/build-docs.yml:71-81 publishes documentation to GitHub Pages:

Diagram: Documentation Deploy Job Flow

The deploy job configuration .github/workflows/build-docs.yml:71-80:

Key aspects:

• Dependency: needs: build ensures build completes first
• Environment: Publishes to github-pages environment
• Output: page_url provides the live documentation URL
• Idempotency: Overwrites existing GitHub Pages deployment