MQTT: how to install as a Docker Container

MQTT… “It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks…” (MQTT: FAQ) While there are many MQTT implementations I settled on Eclipse Mosquitto as an open source message broker. I’ll be using Docker built on top of Ubuntu Server 16.04.

Host System Set-Up:

First, create the MQTT configuration, data, and log directories on the host docker file system. For my purposes I use the  /opt/containters/parent directory for organizational purposes. We will be running the Docker container using the ‘user1’ account. Additionally the Docker file system that the container will use will need to be owned by the ‘user1’ account.

sudo mkdir -p /opt/containers/mqtt-mosquitto/{config,log,data}
sudo chown -R user1:user1 /opt/containers/mqtt-mosquitto

Code explanation: TGP: mkdir
Code explanation: TGP: usermod

We will need to get the user and group IDs for accounts we just created with the  id <account> command.

javier@docker:~$ id user1
uid=1000(user1) gid=1000(user1) groups=1000(user1)

The ‘user1’ user ID ‘uid’ is 1000. That uid will be used later when the container is created.

Docker Set-Up:

We will need to retrieve a copy of the Eclipse Mosquitto configuration file located in the container at  /mosquitto/config/mosquitto.conf. To do this we will create a temporary container running Eclipse Mosquitto, copy out the mosquitto.conf from the container to the Docker host system, delete the temporary container, and finally edit the mouitto.conf to make it ready for a running Mosquitto container.

Create a temporary Eclipse Mosquitto container

docker run -d \
--name=mqtt-mosquitto \
-p 1883:1883 \
-p 9001:9001 \

Copy out the mosquitto.conf file from the temporary container to the Docker file system

sudo docker cp mqtt-mosquitto:/mosquitto/config/mosquitto.conf /opt/containers/mqtt-mosquitto/config/mosquitto.conf

Stop and remove the temporary container running Eclipse Mosquitto

docker stop mqtt-mosquitto
docker rm mqtt-mosquitto

Edit mosquitto.conf on the Docker file system

sudo nano /opt/containers/mqtt-mosquitto/config/mosquitto.conf

Add the following to the end of the mosquitto.conf file for persistent data, and logging, capabilities.

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

Docker Implementation:

Create the Mosquitto Docker container running with the User ID = 1000, and using the files on the Docker host file system.

docker run -d \
--name=mqtt-mosquitto \
-p 1883:1883 \
-p 9001:9001 \
-u 1000 \
-v /opt/containers/mqtt-mosquitto/config/mosquitto.conf:/mosquitto/config/mosquitto.conf \
-v /opt/containers/mqtt-mosquitto/data:/mosquitto/data \
-v /opt/containers/mqtt-mosquitto/log:/mosquitto/log \

Once that is complete you can test the Eclipse Mosquitto MQTT container using a program like MQTT.fx.


If you are familiar with using Docker compose you can build the container using the following docker-compose.yaml file. This can only be used once you have done after your have completed the ‘Docker Setup-up’ section of this post.

version: "3"
 image: eclipse-mosquitto
 - "1883:1883"
 - "9001:9001"
 user: "1000"
 - "/opt/containers/mqtt-mosquitto/config/mosquitto.conf:/mosquitto/config/mosquitto.conf"
 - "/opt/containers/mqtt-mosquitto/data:/mosquitto/data"
 - "/opt/containers/mqtt-mosquitto/log:/mosquitto/log"

About the Author

%d bloggers like this: