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/8a829fda/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