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 Docker Compose Orchestration. For deployment procedures, see Deployment. For environment variable setup, see Environment Variables Reference.

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