Reference

Relevant source files

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

This page provides technical reference documentation for all configuration files and settings in the Docker MQTT Mosquitto Cloudflare Tunnel system. It serves as a comprehensive guide to the structure and relationships between configuration files.

For detailed references of individual configuration files, see:

• docker-compose.yml Reference
• mosquitto.conf Reference
• Environment Variables Reference

For security and access control details, see Security Model. For production deployment considerations, see Production Considerations.

Configuration Files Overview

The system uses three primary configuration files to define services, MQTT broker behavior, and authentication credentials:

Configuration File Relationships

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

Configuration Directive Mapping

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

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

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

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

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 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

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

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"]

.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