Planning

While working on a personal project Komponist, I was due to update
Mosquitto MQTT Broker due to a CVE and found some interesting changes
that will impact me in the future when it comes to configuring the Broker. This post
provides a solution to make the Broker compatible with future versions using new and
less visited concepts in Docker Compose v2, namely:

• Docker Init Containers
• Using the include feature in Docker Compose files

Observations

This section provides information on what currently is observed post upgrading the
Mosquitto Broker to v2.0.18.

Current Docker Compose File

This is my current docker-compose.mosquitto.yml with the following file structure
generated by Komponist:

|- docker-compose.mosquitto.yml
|-- mosquitto
    |--- acl
    |--- users
    |--- mosquitto.conf

The Compose file content is:

services:
  mosquitto:
    image: docker.io/eclipse-mosquitto:2.0.18
    container_name: komponist_mosquitto
    configs:
      - mosquitto_conf
      - mosquitto_acl
      - mosquitto_users
    command: mosquitto -c /mosquitto_conf
    security_opt:
      - "no-new-privileges=true"
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

configs:
  mosquitto_conf:
    file: ./mosquitto/mosquitto.conf
  mosquitto_acl:
    file: ./mosquitto/acl
  mosquitto_users:
    file: ./mosquitto/users

Bringing the container up using:

docker compose -f docker-compose.mosquitto.yml up

The logs will throw some warnings such as the following:

Warning: File /mosquitto_users has world readable permissions. Future versions will refuse to load this file.

Warning: File /mosquitto_users owner is not mosquitto. Future versions will refuse to load this file.
...
...

So for future versions the files need to have a specific user and file permissions
to make the current configuration files valid.

Caveats

In systems where I do not have superuser privileges to create a new user mosquitto whose
UID/GID should be 1883 and changing file permissions is not an option, the only way to tackle
such a solution is through Docker Init Containers.

Docker Init Containers are like sidecar containers in Kubernetes or a patching container where
it initializes a state (here specific configuration file) and then starts the core container.

This feature has existed for a while, but it is not well documented in the Compose Specifications
with some practical examples. In essence, we will use the depends_on service dependency logic
between a generic alpine container that will:

1. change the user for the core configuration files
2. change the file permissions for the core configuration files
3. pass on the core files to the eclipse-mosquitto broker using shared volumes

Once this container is mounted with the files and is run successfully, the adapted configuration
files will be passed on to the main docker container for the Mosquitto MQTT Broker.

Solution

We keep the file structure same as previously mentioned but we create a new Compose file
called docker-compose.mosquitto-init.yml file as follows:

services:
  mosquitto_init:
    image: alpine:3.18
    container_name: mosquitto_init
    command: sh -c 'chmod 0400 -R /config/ && chown 1883:1883 -R /config/'
    volumes:
      - ./mosquitto/mosquitto.conf:/config/mosquitto_conf
      - ./mosquitto/users:/config/mosquitto_users
      - ./mosquitto/acl:/config/mosquitto_acl

We are mounting the configuration files into the init container under the /config directory
and changing the file persmissions and ownership for the files in this init container.

NOTE: we will have to refactor out the Docker Configs section previously configured in
original docker-compose.mosquitto.yml file into the docker-compose.mosquitto-init.yml file

We now refactor the mosquitto.conf file a bit to accept the new location for the files
as follows:

# MQTT Port Listener
listener    1883
protocol    mqtt

# Authentication
allow_anonymous     false
password_file       /config/mosquitto_users

# Authorization
acl_file    /config/mosquitto_acl
# Logging Configuration
log_timestamp true
log_type all

Note the /config as prefix to the ACL and password file.

Final refactoring takes place in the docker-compose.mosquitto.yml file as follows:

include:
  - docker-compose.mosquitto-init.yml

services:
  mosquitto:
    image: docker.io/eclipse-mosquitto:2.0.18
    container_name: komponist_mosquitto
    entrypoint: mosquitto -c /config/mosquitto_conf
    depends_on:
      mosquitto_init:
        condition: service_completed_successfully
    security_opt:
      - "no-new-privileges=true"
    volumes_from:
      - mosquitto_init
    volumes:
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

Upon bringing the stack up again:

docker compose -f docker-compose.mosquitto.yml up

the Warnings should be gone and your config files that were valid prior to
version 2.0.18 will still be compatible for the upcoming versions (unless the development
of mosquitto demands something more in the future).

In a Nutshell, the main mosquitto service is now dependent on the mosquitto-init service
via the depends_on spec and core files are exchanged from the init container to the main container
via volumes_from spec.

NOTE: this approach will change the file permissions / owner for the core configuration files
on the host machine since they are volume mounted.

At the time of writing this post, this is the only approach I have tested out.

If you have read this post and have better approaches in mind, connect with me on LinkedIn and share
your solutions or improve upon the method. I would love to hear your feedback.

GitHub Gist

the Gist of the code can be found here