A step-by-step guide for starting a mosquitto broker service in a containers with docker-compose
Tags: docker, mqtt, mosquitto, broker
Published: 2023-04-27 11:04:50

---
title: A step-by-step guide for starting a mosquitto broker service in a containers with docker-compose
published: true
description: A step-by-step guide for starting a mosquitto broker service in a containers with docker-compose
tags: docker, mqtt, mosquitto, broker
# cover_image: https://direct_url_to_image.jpg
# Use a ratio of 100:42 for best results.
# published_at: 2023-04-27 11:02 +0000
---

# A step-by-step guide for starting a mosquitto broker service in a containers with `docker-compose`
## Prerequisites

Before we start, make sure you have the following installed on your machine:

- Docker
- docker-compose

[You can install the prerequisites following this tutorial](https://dev.to/abbazs/how-to-install-the-latest-docker-and-docker-compose-on-debian-based-linux-systems-3o9j).

1. Open your terminal and create a new directory called `mosquitto`:

   ```bash
   mkdir mosquitto
   ```

1. Change to the `mosquitto` directory:

   ```bash
   cd mosquitto
   ```

1. Create the `config` folder and the `mosquitto.conf` and `password.txt` files inside it (with the content as following):

   ```bash
   mkdir config
   echo 'listener 1883
   persistence true
   persistence_location /mosquitto/data/
   log_dest file /mosquitto/log/mosquitto.log
   allow_anonymous false
   password_file /mosquitto/config/password.txt' > config/mosquitto.conf
   echo "admin:\$7\$101\$xuOfObQdv0Hi2p0A\$o+J3vzbpm0hekukYw73tT3fiB2Ogi1UCJgbzNyFA0GOgxAo79hqfTeXVr062KoD5nCphwV+1V/NxlMzwnV5Kvg==" > config/password.txt
   ```

1. Create the `log` folder and the `mosquitto.log` file inside it:

   ```bash
   mkdir log
   touch log/mosquitto.log
   ```

1. Set the read and write permissions for all users for the following files:

   ```bash
   chmod o+w log/mosquitto.log
   chmod 766 -R config
   ```

1. Create the `docker-compose.yml` file with the following content:

   ```docker-compose
   version: '3.8'
   networks:
   mqtt-net:
       driver: bridge
       ipam:
       driver: default
       config:
           - subnet: 172.100.10.0/24
   services:
    mqtt-broker:
        image: eclipse-mosquitto:latest
        user: mosquitto
        volumes:
        - type: bind
            source: ./config/
            target: /mosquitto/config/
            read_only: false
        - type: bind
            source: ./log/
            target: /mosquitto/log/
            read_only: false
        - type: volume
            source: data
            target: /mosquitto/data/
        ports:
        - target: 1883
            published: 1883
            protocol: tcp
            mode: host
        - target: 9001
            published: 9001
            protocol: tcp
            mode: host
        networks:
            mqtt-net:
                ipv4_address: 172.100.10.10
    mqtt-pub:
        image: eclipse-mosquitto:latest
        command: sh -c "mosquitto_pub -h mqtt-broker -t test -m 'Hello World' -u admin -P password"
        depends_on:
            - mqtt-broker
        networks:
            mqtt-net:
                ipv4_address: 172.100.10.11
    mqtt-sub:
        image: eclipse-mosquitto:latest
        command: sh -c "mosquitto_sub -h mqtt-broker -t test -u admin -P password"
        depends_on:
            - mqtt-broker
        networks:
            mqtt-net:
                ipv4_address: 172.100.10.12
   volumes:
   data:
       name: "mqtt-broker-data"
   ```

   _Note that we have assigned a static IP address of `172.100.10.10` to the `mqtt-broker` service._

1. Build and start the containers by running the following command:

   ```bash
   docker-compose up --build
   ```

   This should bring up 3 services namely mqtt-broker, mqtt-pub, mqtt-sub. And the mqtt-pub service will immediatly exit since it just exits after publishing a message.

   The default username and password for mqtt-broker is `admin` and `password` respectively.

1. We can now publish messages using the mqtt-pub service using the docker compose.

   ```bash
   docker compose run mqtt-pub sh -c "mosquitto_pub -h mqtt-broker -t test -m 'Hello World' -u admin -P password"
   docker compose run mqtt-pub sh -c "mosquitto_pub -h mqtt-broker -t test -m 'Message 2' -u admin -P password"
   docker compose run mqtt-pub sh -c "mosquitto_pub -h mqtt-broker -t test -m 'Message 3' -u admin -P password"
   ```

   And we shall be able to see the output as following:

   ```bash
   mqtt-mqtt-sub-1     | Hello World
   mqtt-mqtt-sub-1     | Message 2
   mqtt-mqtt-sub-1     | Message 3
   ```

1. To change the password of admin user (_after changing the password the service needs to be restarted_):

   ```bash
   docker compose exec mqtt-broker mosquitto_passwd -b /mosquitto/config/password.txt admin NEWPASSWORD
   ```

   Understanding the command:

   1. `docker`: This is the command used to interact with Docker, a containerization platform used to run applications in isolated environments.

   2. `compose`: This is an option used with the `docker` command to run a multi-container Docker application using a Compose file.

   3. `exec`: This is an option used with the `docker-compose` command to execute a command inside a running container.

   4. `mqtt-broker`: This is the name of the service in the Compose file that corresponds to the MQTT broker container.

   5. `mosquitto_passwd`: This is the command to set or update a password in the password file used by the Mosquitto MQTT broker.

   6. `-b`: This is an option for the `mosquitto_passwd` command that specifies that the next argument is the password to be added or updated.

   7. `/mosquitto/config/password.txt`: This is the path to the password file in the Mosquitto container.

   8. `admin`: This is the username to which the password will be added or updated.

   9. `NEWPASSWORD`: This is the new password that will be set for the `admin` user in the Mosquitto password file.

   In summary, this command sets or updates the password for the `admin` user in the Mosquitto password file located at `/mosquitto/config/password.txt` with the new password `NEWPASSWORD`, inside the running `mqtt-broker` container in a Docker Compose environment.

   Restart the container:

   ```bash
   docker compose restart mqtt-broker
   ```

1. Since we changed the admin password, we no longer will be able to start the mqtt-pub service as `docker compose up mqtt-sub`. We need to start it using the following command:

   ```bash
   docker compose run mqtt-sub sh -c "mosquitto_sub -h mqtt-broker -t test -u admin -P CHANGED_PASSWORD"
   ```

   Now we can publish a message (using another terminal) and see that being refelceted in the mqtt-sub container service.

   ```bash
   docker compose run mqtt-pub sh -c "mosquitto_pub -h mqtt-broker -t test -m 'Hello World' -u admin -P CHANGED_PASSWORD"
   ```