How to Install MQTT using Docker

April 27, 2025

#1

When working with Internet of Things (IoT) projects, lightweight messaging protocols are essential—and that’s where MQTT shines. MQTT (Message Queuing Telemetry Transport) is a popular publish-subscribe protocol designed for low-bandwidth, high-latency, or unreliable networks. It's perfect for sensors, mobile apps, and small embedded systems.
But setting up an MQTT broker can feel like a chore—unless you’re using Docker. In this guide, we’ll walk through how to quickly install and run an MQTT broker using Docker, with a focus on the widely used Eclipse Mosquitto image. Whether you’re prototyping, testing, or learning, Docker offers a fast, no-fuss setup.

Why Use Docker for MQTT?

Running an MQTT broker in Docker offers several benefits:

• No manual setup : Avoid installing software and dependencies on your host system.
• Easy cleanup : Start or stop your MQTT environment with just one command.
• Portable and repeatable : Share your setup or run it across multiple machines effortlessly.
• Perfect for testing : Use separate containers for different environments or versions.

Step 1: Pull the MQTT Docker Image

The most commonly used MQTT broker in Docker is Eclipse Mosquitto. It’s lightweight, open-source, and actively maintained.
Start by pulling the official Mosquitto image from Docker Hub:

docker pull eclipse-mosquitto

This will download the latest version of the broker.

Step 2: Run Mosquitto with Docker

To start a basic Mosquitto MQTT broker, run the following command:

docker run -it -p 1883:1883 -p 9001:9001 --name mosquitto eclipse-mosquitto

Here’s a quick breakdown of what this does:

• -it: Runs the container in interactive mode (you can also use -d to run it in the background).
• -p 1883:1883: Exposes the default MQTT port (1883) for broker-client communication.
• -p 9001:9001: Exposes the WebSocket port (optional but useful for browser-based clients).
• --name mosquitto: Names your container for easier reference.
• eclipse-mosquitto: Uses the official Docker image.

That’s it—your MQTT broker is now up and running!

Step 3: Test Your MQTT Broker

To make sure everything is working, you can test the broker using a variety of tools:

• MQTT.fx or MQTT Explorer (GUI clients)
• Command-line tools like mosquitto_pub and mosquitto_sub (included in the Mosquitto client package)
• Code libraries like paho-mqtt (Python), mqtt.js (Node.js), or MQTTnet (.NET)

Try this with the Mosquitto client (if installed on your machine):

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

You should see the message show up right away if everything's working.

Step 4: Customize Mosquitto Configuration (Optional)

While the default setup works fine for basic use, you might want to tweak settings such as authentication, persistent storage, or message logging.
To do this, you’ll need to mount a custom configuration file. First, create a directory on your machine:

mkdir mosquitto
cd mosquitto
mkdir config data log

Then, create a basic config file inside the config directory: mosquitto.conf

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883
allow_anonymous true

Now run the container using this config:

docker run -d --name mosquitto-custom \
  -p 1883:1883 -p 9001:9001 \
  -v $(pwd)/config:/mosquitto/config \
  -v $(pwd)/data:/mosquitto/data \
  -v $(pwd)/log:/mosquitto/log \
  eclipse-mosquitto

This tells Docker to use your local config, data, and log directories.

Step 5: Use Docker Compose (Recommended for Teams)

For easier collaboration or multi-service setups, Docker Compose simplifies everything. Create a docker-compose.yml file like this:

version: '3'
services:
  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

Start it up with:

docker-compose up -d

And bring everything down with:

docker-compose down

Tips

• Security matters: In real projects, disable anonymous access and add user authentication.
• WebSocket clients: Make sure your browser-based clients connect over port 9001 if enabled.
• Monitor activity: Check logs using docker logs mosquitto or through the log files if mapped.