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