Setting Up Mosquitto Broker with Docker


Create Directories (Folders) for Mosquitto Configuration, Data, and Logs

When running Docker as a container, you will need a directory on the Host OS where the container can store required data, and reference configuration files. This is known as a mount. If you have never used Docker mounts before, check out Managing Data in Docker.


Mosquitto references a configuration file that has some very important settings that need to be changed. In order for the container to read the configuration file, we will need to map a directory containing the config file from the Host OS into the container. This is known as a bind mount.


In this bind mount we will put a folder to store configuration files, state data of the broker, and log data. In a location with appropriate permissions, create a directory structure like the one below:

A folder breakdown of the configuration files. The top folder is Mosquitto and the three files listed underneath are config, data, and log.

If you are on Windows you can run this command to create the required folder structure in C:\docker-mounts\mosquitto. It will create all required folders if they do not exist already.

mkdir C:\docker-mounts\mosquitto\config C:\docker-mounts\mosquitto\data C:\docker-mounts\mosquitto\log

Create Configuration file

A configuration file is necessary to initialize Mosquitto broker, setup ports for listening, configure security and tell Mosquitto where to store data. Configuration files redirect the data collected towards logs which can be used for error-checking and auditing purposes.

To create a configuration file, we need to open a text editor in administrative mode. Notepad++ works well for this.

  • Open a text editor (preferably Notepad++).

  • Paste the below code on the text editor

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

log_type error
log_type warning
log_type notice
log_type information

Save as mosquitto.conf under the mosquitto/config directory you just set up. Make sure the "Save as type" is selected "All types".

If it's giving you trouble saving the file, try launching Notepad++ in admin mode.

  • persistence true: If set to true connection, subscription and message data will be written to the disk in mosquitto.db at the location dictated by persistence_location. If set to false, the data will be stored in memory only. Defaults to false.

  • persistence_location /mosquitto/data: The path where the persistence database should be stored. If not given, then the current directory is used.

  • log_dest file /mosquitto/log/mosquitto.log: Send log messages to a particular destination. The file destination requires an additional parameter which is the file to be logged to. The file will be closed and reopend when the broker receives a HUP signal. Only a single file destination may be configured.

  • listener 1883: Listen to network traffic posted on port 1883 of the computer it is running on. If you don't add this then the broker will only be accessible over localhost.

  • allow_anonymous true: Anyone on the network can publish and subscribe to topics even if they do not have a username and password.


The last 4 lines indicate the type of messages that are allowed to be stored in the logs file. As the broker runs, it will generate logs that are categorized as either errors, warnings, notices, or information.

  • log_type error: Store error messages in log file

  • log_type warning: Store warning messages in log file

  • log_type notice: Store notice messages in log file

  • log_type information: Store information messages in log file


For more info on the differences between these type of logs, and other configuration settings check out Managing Data in Docker. Search for log_type types.

Create a Docker Container to run Mosquitto

The command to start the broker is below. Note the areas that you will need to fill in. 


docker run -d
  --name gateway_mosquitto
  -p 1883:1883
  -v {Path to .conf file on Host OS}:/mosquitto/config/mosquitto.conf
  -v {Path to data directory on Host OS}:/mosquitto/data
  -v {Path to log directory on Host OS}:/mosquitto/log
  eclipse-mosquitto

This command will only run if you replace the whole '{}' part with the corresponding paths. Fully completed example code is given at the end of this section.

  • {Path to .conf file on Host OS} is the path the mosquitto.conf file you made in step 3.

  • {Path to data directory on Host OS} is the path to the data directory created in step 2.

  • {Path to log directory on Host OS} is the path to the log directory created in step 2.

Command Syntax Explanation:

  • docker run: The run command starts the container for a specific image. In this case, the image is Mosquitto.

  • eclipse-mosquitto: This is the reference to the image found on Docker Hub provided by the Eclipse Foundation. Yu can find the link to the image here.

There are several flags used on the above code to create a container inside docker.

  • --name: is used to name the container being created. Here, our container is named "gatewat_mosquitto". Otherwise it will be named something random.

  • -d: stands for "detached mode". This allows continues use of the terminal once the command is started. Without this the terminal will be dedicated to running the container, and you will not be able to run other commands in that terminal.

  • -v: stands for volume. Technically what we are doing here is a Bind Mount, but the -v flag still works for bind mounts. The syntax does like :host system directory : container directory". It is used to mount the host systems directly onto the docker container. Here, we are using 3 -v flags. For example, "-v C:\mosquitto\config\mosquitto.conf:/mosquitto/config/mosquitto.conf" means that we are mounting the file "mosquitto.conf" from our host system into the /mosquitto/config/ directory inside the container. Same is being done for the data and log directories as well.

  • -p: stands for port. The syntax goes like "host system port : container port". Here. we map the port of the host system to the port inside the container. Port '1883' is the default port for MQTT communication.


Assuming that you are on Windows and you created your folder structure in C:\\docker-mounts\\mosquitto this command should work.


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

It should look like this in your cmd:

An Administrator Command Prompt window showing the output of running the caboce command

The broker should now be running!

Test if Mosquitto broker is running on Docker

Verify if the Docker Container is running

- Run "docker ps" in CMD and check if the above created container is displayed or not. Use the container ID to reference it for further testing/troubleshooting.

  • docker ps

- Alternatively you can check the status of the container using the Docker Desktop UI. Launch Docker Desktop, click "Containers" and you should see the status of your container running mosquitto.

A screenshot of Docker Desktop showing the newly created docker container.

Check Docker logs

Check the logs to verify if docker is running

  • docker logs <container_id>

We could also use the container name instead of the container ID as per personal convenience.

Container ID can be fetched using "docker ps" command. In case the container is not running, we can recreate it using Step 4.

Restarting and Deleting Docker Container

To restart a container, use the below command in CMD:

  • docker restart <container_name>

To verify if the container has been restarted, we can use the command "docker ps" to check.

To delete a container, use the below command in CMD:

  • docker rm <container_name>

Replace with the actual container name.

Check if Docker is running Mosquitto

To check if a broker is established, we could run a simple pub-sub setup inside docker and verify it.

To do this, navigate to the "Exec" tab inside the container created. In the below screenshot, the container is named "gateway_mosquitto" with port 1883 from the host machine is mapped to port 1883 of the container.


The "Exec" tab here represents the Command Prompt inside the Docker container which can be used to execute commands.

To run it in a separate window, use "Open in external terminal" option on the right side of the same screen.

Using Docker container terminal

Open a separate external terminal from "Exec" tab and type the below command:

  • mosquitto_sub -h localhost -t gatewaylabs/topic

Above command creates a subscriber, where messages sent through the broker on topic "gatewaylabs/topic" will be received/displayed here.

  • mosquitto_pub -h localhost -t gatewaylabs/topic -m "Signal Check from Gateway"

Above command creates a publisher, where a message is sent through the topic "gatewaylabs/topic" on host "localhost" with the message "Signal Check from Gateway".

  • 1. Create subscriber

    A terminal window running the subscriber command listed above.

  • 2. Create publisher

    A terminal window running the publisher command listed above.

  • 3. Message should appear on subscriber side

    The terminal window running the subscriber command showing the message sent from the publisher.

After publishing the message, if the message is received by the Subscriber with no errors, then the Mosquitto broker is setup on the specified container in Docker.

Additional Resources