How to Deploy Mosquitto MQTT Broker with Docker Compose: A Step-by-Step Guide

X (Twitter) Facebook Pinterest LinkedIn

Eclipse Mosquitto™ is an open-source message broker that implements the MQTT protocol versions 5.0, 3.1.1, and 3.1. MQTT, or Message Queuing Telemetry Transport, is a lightweight, publish-subscribe network protocol that transports messages between devices. Due to its efficiency and scalability, the Mosquitto broker is widely used for Internet of Things (IoT) and messaging applications. Deploying Mosquitto with Docker Compose can simplify the setup and management process, making it an ideal solution for development, testing, and production environments. This guide will walk you through the steps to deploy a Mosquitto MQTT broker using Docker Compose.

Table of Contents

Prerequisites

Before you begin, make sure you have the following:

Docker installed on your system.
Docker Compose installed on your system.
Basic understanding of Docker concepts and the Docker Compose tool.

Step 1: Create a Docker Compose File

First, create a directory dedicated to your Mosquitto deployment. This directory will contain your Docker Compose file (docker-compose.yml) and any additional configuration files.

mkdir mosquitto-docker && cd mosquitto-docker

Create the docker-compose.yml file:

touch docker-compose.yml

Open this file in a text editor and add the following configuration:

version: '3'

services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    ports:
      - "1883:1883" # Default MQTT port
      - "9001:9001" # WebSocket port (optional)
    volumes:
      - "./config/mosquitto.conf:/mosquitto/config/mosquitto.conf"
      - "mosquitto_data:/mosquitto/data"
      - "mosquitto_log:/mosquitto/log"
    restart: unless-stopped

volumes:
  mosquitto_data:
  mosquitto_log:

Configuration Explained:

image: Uses the eclipse-mosquitto:latest Docker image, ensuring you have the latest version of Mosquitto.
container_name: Sets a custom name for the container.
ports: Exposes the default MQTT port (1883) and an optional WebSocket port (9001) to the host. Adjust these as needed.
volumes: Mounts volumes for the Mosquitto configuration file, persistent data storage, and log files. You’ll need to create a configuration file in the specified path (./config/mosquitto.conf).

Step 2: Create a Mosquitto Configuration File

Before starting your Mosquitto container, you must create a Mosquitto configuration file. This file allows you to customize your MQTT broker settings.

First, create a config directory and then create a mosquitto.conf file within it:

mkdir config && touch config/mosquitto.conf

Open config/mosquitto.conf in a text editor and add basic configuration settings. Here’s a simple example that enables both MQTT and WebSockets:

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log

listener 1883
listener 9001
protocol websockets

Feel free to adjust these settings based on your requirements. The official Mosquitto documentation provides detailed information on all available configuration options.

Step 3: Launch Mosquitto

With your docker-compose.yml and mosquitto.conf files ready, start your Mosquitto broker by running:

docker compose up -d

This command will pull the Mosquitto image (if not already pulled) and start the container in detached mode.

Step 4: Verify the Mosquitto MQTT Broker

To ensure that Mosquitto is running correctly, you can subscribe to a test topic using the Mosquitto CLI tools or any MQTT client:

mosquitto_sub -h localhost -t test/topic

In a separate terminal, publish a message to the same topic:

mosquitto_pub -h localhost -t test/topic -m "Hello, MQTT!"

If everything is set up correctly, the subscriber should receive the message “Hello, MQTT!”.

Conclusion

Deploying Mosquitto with Docker Compose offers a straightforward and efficient method for setting up an MQTT broker. Following the steps outlined in this guide, you can quickly have a Mosquitto instance running on your system, ready to facilitate communication between IoT devices or any application requiring lightweight messaging.

Author
Recent Posts

Follow me

Anastasios Antoniadis

Anastasios Antoniadis is the founder and editor-in-chief of BORDERPOLAR... He is a software engineer, blogger, and avid gamer covering tech, gaming, and coding guides for over 4 years. He is a 2014 graduate of the Department of Informatics and Telecommunications of the University of Athens, an M.Sc. holder in Computer Science, and a Ph.D. student in Program Analysis.