Running The Mosquitto MQTT Broker In Docker – Beginners Guide

docker-mos-iconDocker is a container technology used for quickly deploying applications without having to install them as they come pre-installed in a container.

These containers can run on window,Linux and Mac OS under Docker.

Mosquitto ships docker containers for various mosquitto versions and the list along with install instructions are available here






Before you can run Mosquitto under docker you will need to install docker and that is covered here.

Note: I am not a docker expert and this tutorial is based on my experience of running and configuring a test mosquitto broker.

I will not be covering docker in this tutorial and will concentrate on configuring Mosquitto to run under Docker.

The Docker Container and Your Host Machine

One difficulty I had when I ran my first docker application is understanding the relationship between the docker container and the host machine.

The schematic below will I hope help you to conceptualise it.


Clients Interact with mosquitto using a port (1883) or ports. So how do clients access the mosquitto broker running inside the container?

The answer is that they need to be mapped to the running port.

So if mosquitto in the container uses port 1883 then this needs to be mapped to a port on the host machine e.g.1883.

If mosquitto uses several ports then all these ports need to be mapped to be usable.

You should note that the docker port and the host port can be different but they are usually the same to avoid confusion.

The mosquitto broker in the container uses the same IP address and name as the host machine.

This especially important when using certificates or opening ports on a firewall.

Configuring Mosquitto In Docker

When you install mosquitto on your system you need to configure it using the mosquitto.conf file located in the /etc/mosquitto folder.

In addition you may also need to provide a password and ACL (access control list) file,certificate files, log folders etc.

Changing or adding files to the container is not normally done.

Instead the container provides directories that can be mapped to folders on the host machine.

The Mosquitto container provides 3 folders as described in the documentation

  • Configuration /mosquitto/config/mosquitto.conf
  • persist data to /mosquitto/data
  • log to /mosquitto/log/mosquitto.log

To access data in these folders and make changes you need to map them to folders outside the container which we will see when we run it.

Basic Docker Commands

Docker containers are available on the internet and  to use them they first need to be downloaded to your local machine.

To do this you use the pull command

docker pull eclipse-mosquitto

When you run a docker container it is assigned a unique ID which you can use to access the container.

However you can also associate a name with the container which you can used in place of the ID.

A container can be started with a command console using the -it switch or simply as background service.

When started with a console you terminate it using CTRL+C just like running a normal application.

When running in the background you can attach yourself to the command console using the attach command and now it looks just like if you had  started it with the -it switch

A running container can be stopped by using the stop command and restarted using the start command.

When using a name with the container that name is associated with the container image until you remove it using the rm command.

The following sequence of commands illustrate this:


docker run -it --name mos2 -p 1883:1883  -v /home/steve/mos-docker/mosquitto:/mosquitto/ -v ~/mos-docker/mosquitto/log:/mosquitto/log -v ~/mos-docker/mosquitto/data:/mosquitto/data  eclipse-mosquitto

We start by using the run command with :
-it to attach console
-name to give it a name (mos2)
-p map the internal toexternal ports to use
-V link the local folders to the container folders

The container is called eclipse-mosquitto

The local folders are under the mos-docker/mosquitto folder in my home folder.

We then stop the broker using control+C and now we can start and stop the broker using the name, and notice that there is no console until we use the attach command.

After using the attach command I publish a message and it shows on the console.


Finally I use the rm command to remove the container image so I can now reuse the name.


Mossquitto.conf File

To change the broker configuration we place a mosquitto.conf file in the ~/mos-docker/mosquitto folder.

Below is a simple example


Notice the file locations are container locations and not referenced to my home folder even though that is where they will go. Below is screen shot of my home folder


It is important to note that the configuration file says put the persistence data in the /mosquitto/data folder but it actually gets placed in the ~/mos-docker/mosquitto/data folder.

You can also see a certs folder there for certificates and this is where I place the certificates and the entries in the mosquitto.conf file would look like this:




Common Questions and Answers

Q- Can I run mosquitto in docker without mapping Volumes?

A- Yes but it will run with default configuration of the container.

Q- I’m using SSL on port 8883 and MQTT on port 1883 how do I do this.

A- Use: docker run -it –name mos2 -p 1883:1883 -p 8853:8883

Related articles and resources


Please rate? And use Comments to let me know more


  1. Hi Steve, Hope you’re doing well. I worked with docker mosquitto and tested bridge between 2 brokers and it worked but once I wanted use tls between bridges, it didn’t work. and that was interesting because when I used the exact config in tow normal mosquitto on ubuntu it works well without any problem. could you test it?

  2. Will you be using docker for most of your installations in the future?

    When would you use and and when would you not use it?

    Could you see any performance hit from using docker?

    Thanks for such an interesting article!

    1. Good question but as I don’t use Mosquitto in any real world application then I will be working with both. My preference would be a normal setup but Docker implementations seem to be common.

Leave a Reply

Your email address will not be published. Required fields are marked *