How to Install MQTT on Docker (Step-by-Step Tutorial for Beginners)

Introduction

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol widely used in IoT (Internet of Things) systems for reliable, low-bandwidth communication.

Setting up an MQTT broker manually can be time-consuming — especially when dealing with dependencies and configurations.
With Docker, you can deploy an MQTT broker like Eclipse Mosquitto in seconds and start publishing/subscribing messages immediately.

In this comprehensive guide, you’ll learn how to install MQTT on Docker, test it using simple commands, and apply best practices to keep your setup stable and secure.

What is MQTT?

MQTT is a publish/subscribe protocol designed for minimal overhead and reliable message delivery in constrained environments.

Key features:

• Lightweight and bandwidth-efficient
• Works over TCP/IP
• Supports QoS (Quality of Service) levels for guaranteed delivery
• Ideal for sensors, microcontrollers, and mobile applications

Common MQTT implementations:

• Eclipse Mosquitto (most popular open-source broker)
• HiveMQ
• EMQX
• VerneMQ

In this tutorial, we’ll use Eclipse Mosquitto because it’s open-source, lightweight, and Docker-ready.

Why Use Docker for MQTT?

Running MQTT on Docker provides several benefits:

✅ Fast setup: Deploy the entire broker in one command
✅ Portability: Works identically across any OS (Windows, macOS, Linux)
✅ Isolation: Keeps MQTT separate from your host system
✅ Easy updates: Upgrade or roll back versions effortlessly
✅ Reproducibility: Great for testing IoT systems in clean environments

Prerequisites

Before we begin, ensure that you have:

1. Docker installed on your system
   → Install Docker
2. Docker Compose (included in Docker Desktop)
3. Basic command-line knowledge
4. Free port 1883 (default MQTT port) on your host machine

To confirm Docker is working, run:

docker --version
docker compose version

Step 1 – Pull the Eclipse Mosquitto Docker Image

Eclipse Mosquitto provides an official Docker image on Docker Hub.
Pull it using the following command:

docker pull eclipse-mosquitto

Verify the image is available:

docker images

Expected output:

REPOSITORY          TAG       IMAGE ID       CREATED         SIZE
eclipse-mosquitto   latest    1f2d4e7abcde   2 days ago      8.7MB

Step 2 – Run MQTT Using Docker

Let’s start a simple MQTT broker container using the default configuration:

docker run -d \
  --name mosquitto \
  -p 1883:1883 \
  eclipse-mosquitto

This command runs Mosquitto in detached mode and exposes port 1883, the default MQTT TCP port.

Check if it’s running:

docker ps

You should see:

CONTAINER ID   IMAGE                COMMAND                  STATUS         PORTS
abcd1234efgh   eclipse-mosquitto    "/docker-entrypoint.…"   Up 2 minutes   0.0.0.0:1883->1883/tcp

Step 3 – Verify MQTT Functionality

To confirm your broker is working, you can use Mosquitto clients (mosquitto_pub and mosquitto_sub).

If you have Mosquitto clients installed locally:

mosquitto_sub -h localhost -t test/topic

In another terminal, publish a message:

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

You should see:

Hello MQTT from Docker!

Alternatively, you can use MQTT Explorer or MQTTX GUI clients to connect to localhost:1883 and verify communication visually.

Step 4 – Create a Custom Mosquitto Configuration

For advanced use, you’ll want to use a custom configuration file.

Create a directory structure:

mkdir -p ~/mosquitto/config ~/mosquitto/data ~/mosquitto/log

Then create a config file:

nano ~/mosquitto/config/mosquitto.conf

Add the following:

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

Now run Mosquitto with this configuration mounted:

docker run -d \
  --name mosquitto \
  -p 1883:1883 \
  -v ~/mosquitto/config/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  -v ~/mosquitto/data:/mosquitto/data \
  -v ~/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto

✅ Explanation:

• -v mounts configuration, data, and logs directories
• This ensures persistent data even if the container restarts

Step 5 – Use Docker Compose for a Reproducible Setup

Create a docker-compose.yml file for easier management:

version: '3'
services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./config/mosquitto.conf:/mosquitto/config/mosquitto.conf
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log
    restart: unless-stopped

Start the service:

docker compose up -d

Check logs:

docker logs mosquitto

You should see:

mosquitto version 2.x starting
Configuration loaded from /mosquitto/config/mosquitto.conf

Step 6 – Connect MQTT Clients

Once your MQTT broker is running, connect clients locally or remotely.

Example:

• Broker host: localhost
• Port: 1883
• Topic: iot/sensor/data

Using CLI

mosquitto_pub -h localhost -t iot/sensor/data -m "Temperature:25"
mosquitto_sub -h localhost -t iot/sensor/data

Using MQTTX or MQTT Explorer

1. Open MQTTX → “New Connection”
2. Set:

• Host: localhost
• Port: 1883
• Protocol: MQTT

1. Click Connect
2. Subscribe to iot/sensor/data
3. Publish messages and see results instantly

Step 7 – Secure MQTT with Username and Password

For security, avoid anonymous access.
Update your config file:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwordfile

Create a password file:

docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwordfile admin

Restart the container:

docker restart mosquitto

Now connect with credentials:

mosquitto_sub -h localhost -u admin -P yourpassword -t secure/topic

Step 8 – Troubleshooting Common Issues

Problem	Cause	Fix
Broker won’t start	Missing config file or permission issue	Check file paths and use absolute directories
Client can’t connect	Port conflict or wrong listener	Ensure port 1883 is open
Messages not received	Wrong topic name or QoS	Verify exact topic string
“Connection Refused: Not authorized”	Auth disabled or incorrect password	Check Mosquitto config and credentials

Pro Tip 💡: Always check logs for details:

docker logs mosquitto

Best Practices for MQTT on Docker

• ✅ Use persistent volumes for data and logs
• ✅ Enable authentication and TLS in production
• ✅ Use Docker Compose for consistent environments
• ✅ Monitor logs regularly (docker logs mosquitto)
• ✅ Keep the image updated (docker pull eclipse-mosquitto:latest)

Step 9 – Stop and Remove the Container

When finished testing:

docker compose down

or if running standalone:

docker stop mosquitto
docker rm mosquitto

This stops and removes the broker cleanly.

Conclusion

Installing MQTT on Docker with Eclipse Mosquitto is quick, portable, and reliable.
You now have a running MQTT broker capable of handling IoT messages — perfect for local testing, automation, or integration with tools like Node-RED, Home Assistant, or Python Paho clients.

By combining Docker and MQTT, you simplify deployment, reduce manual setup, and gain flexibility for your IoT projects.