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