This project contains configurations and tools to setup a MQTT broker with mosquitto using Docker.

By default, the broker allows anonymous access to a configurable topic and restricted access for a single (configurable) user to a (configurable) restricted topic. Take a look at the the env.example file to see how you can configure it.

If you want to provide a custom MQTT configuration (e.g. authentication / authorization), take a look at Custom MQTT configuration section.

Table of Contents

• Flightdata
  • Getting started
    • Prerequisites
    • Source code
    • Execute with Docker
    • Custom MQTT configuration
      • Config Files
  • FAQ
    • Why do I not get feedback when publishing to a topic
    • Default topics
    • Testing
      • How can I check if publishing succeeded?
      • How do I publish / subscribe to the MQTT broker?
  • Information
    • Guidelines
    • Support
    • Contributing
    • Documentation
    • Versioning
    • License
    • Authors

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

To build the project, the following prerequisites must be met:

• Docker
• Docker Compose

Get a copy of the repository:

git clone https://github.com/noi-techpark/odh-broker-mqtt.git

Change directory:

cd odh-broker-mqtt/

Copy the file .env.example to .env and adjust the configuration parameters.

cp env.example .env

Then you can start the MQTT broker using the following command:

docker-compose up

The service will be available at localhost and your specified server port.

If you want to provide a custom MQTT configuration, you have to do three things:

• target the base image of the provided Dockerfile
• provide your config files when you start Docker Compose
• change the Docker Compose command to start mosquitto with your configuration

Note: if you provide your own config files, the settings in a .env file becomes irrelevant.

The best way to provide your own config is to override the relevant parts in a docker-compose.override.yml file (take a look at https://docs.docker.com/compose/extends for more info on Docker compose config override).

This project provides a docker-compose.override.yml.example file that you can use as base.

Copy the file docker-compose.override.yml.example to docker-compose.override.yml and adjust the configuration parameters.

cp docker-compose.override.yml.example docker-compose.override.yml

provide your config files inside the ./config folder. Finally, start the MQTT broker using the following command:

docker-compose up

Note: just modify the docker-compose.yml file if you don't want to handle an additional docker-compose.override.yml file.

Rename example-config to config, and mount that folder, when you start the container. Files are as follows:

• aclfile: See Default topics for some explanations
• passwordfile: Each configured username and encrypted password (use mosquitto_passwd to create new ones)
• mosquitto.conf: The main config file

For more information look into Mosquitto Docs.

In general, if you want to know if publishing to a topic succeeded, subscribe to that topic. All of your published messages should show up in your subscription.

For topics that need authentication, this is not always true. You may be allowed to subscribe to a topic as anonymous, but due to access control restrictions on that topic you may not see your published messages. You may even not notice that publishing did not succeed when you are not allowed to.

If in doubt, please first double check that you use the correct topic and credentials (where necessary). If you still have troubles, please contact our support.

Given that you don't provide your own mosquitto config (see Custom MQTT configuration on how to do this), mosquitto defines two topics:

• /open/#: anyone can subscribe / publish to this topic (anonymous access)
• flightdata: special topic with authentication to publish / subscribe flightdata (see https://github.com/noi-techpark/odh-datacollector-flightdata).

In general, if you want to know if publishing to a topic succeeded, subscribe to that topic. All of your published messages should show up in your subscription.

For topics that need authentication, this is not always true. You may be allowed to subscribe to a topic as anonymous, but due to access control restrictions on that topic you may not see your published messages. You may even not notice that publishing did not succeed when you are not allowed to.

If in doubt, please first double check that you use the correct topic and credentials (where necessary). If you still have troubles, please contact our support.

You can use any MQTT client you want to publish messages to the MQTT broker, e.g. MQTT Explorer or MQTTX.

You can also use the mosquitto publish / subscribe features provided by mosquitto.

Use the following command to subscribe to the topic /open/test on localhost:

# Subscribe to the topic /open/test using the MQTT instance on localhost

docker run -it --rm --name mosquitto-sub --network="host" eclipse-mosquitto:2.0.12 sh -c "mosquitto_sub -t '/open/test' -h localhost"

Using the Docker version of mosquitto, you can publish a message to topic /open/test on localhost using the following command:

# Publish the message "some" (= valid JSON string) to the topic /open/test using the MQTT instance on localhost
# Please make sure that you correctly escape the double ticks in the message in order to provide valid JSON. 

docker run -it --rm --name mosquitto-pub --network="host" eclipse-mosquitto:2.0.12 sh -c "mosquitto_pub -t '/open/test' -h localhost -m '\"some\"'"

No message arrives? Check your permissions when you publish or subscribe to a certain topic.

Find here guidelines for developers.

For support, please contact [email protected].

If you'd like to contribute, please follow the following instructions:

• Fork the repository.

• Checkout a topic branch from the development branch.

• Make sure the tests are passing.

• Create a pull request against the development branch.

A more detailed description can be found here: https://github.com/noi-techpark/documentation/blob/master/contributors.md.

More documentation can be found at https://opendatahub.readthedocs.io/en/latest/index.html.

This project uses SemVer for versioning. For the versions available, see the tags on this repository.

The code in this project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 license. See the LICENSE.md file for more information.

• Christian Gapp - Initial work - gappc