Monthly Archives: September 2024

Configuring an MQTT broker for Home Assistant

I recently purchased a ratgdo device to replace MyQ's kit for a local non-cloud dependent solution. ratgdo offers homekit, mqtt, and Control4, Nice/Elan, or Crestron integration. For this tutorial, I'm going to cover ratgdo and MQTT integration.

If you run Home Assistant as-is or are using their hardware, you can easily setup an MQTT broker by navigating to Add-Ons and installing the MQTT Broker, however in the past I have written articles on Home Assistant and Z-Wave JS as separate containers, so I wanted to follow the same concept by running the MQTT broker as a container as well.

Across the board, the consensus seems to be that most people are running Mosquitto as an MQTT broker, so here is how you can get that setup as a container.

  1. Download the docker image for Mosquitto
docker pull eclipse-mosquitto

2. Create directories for Mosquitto's config and data files. If desired, you can create one for logs as well, but I'm ok not persisting that.

mkdir /home/docker/mosquitto/
mkdir /home/docker/mosquitto/config
mkdir /home/docker/mosquitto/data

3. Create a configuration file for mosquitto. This file will configure what ports MQTT data should be listed on as well as its corresponding port for receiving data via WebSocket. In addition, we will define where data should be stored, and require authentication to be able to connect. For now, leave the password file, which contains the username/password combo for who can authenticate.

vi /home/docker/mosquitto/config/mosquitto.conf

Press i to enter insert mode and paste the following:

listener 1883 0.0.0.0
listener 9001 0.0.0.0
protocol websockets
persistence true
persistence_file mosquitto.db
persistence_location /mosquitto/data/
allow_anonymous false
#password_file /mosquitto/config/passwd

Type !wq to save and quit.

4. Start the mosquitto container. We'll map both the mqtt and websocket ports and volumes for config and data to persist.

docker run -d --restart=always --name="mosquitto-mqtt" -p 1883:1883 -p 9001:9001 -v /home/docker/mosquitto/config:/mosquitto/config -v /home/docker/mosquitto/data:/mosquitto/data eclipse-mosquitto

5. Launch shell on the container

docker exec -it -u 1883 mosquitto-mqtt sh

6. Use the mosquitto_passwd utility to generate an encrypted username and password. An ask for the password will prompt once you run the command. Type exit to return back to your local terminal.

mosquitto_passwd -c /mosquitto/config/passwd mqtt-user
exit

7. Modify your mosquitto.conf file.

vi /home/docker/mosquitto/config/mosquitto.conf

Uncomment the password file by removing the # sign and then type !wq to save and quit.

8. Restart the container so mosquitto will pickup the username/password

docker restart mosquitto-mqtt

At this point, your mqtt broker service should be up and ready! If you'd like to test connectivity and authentication, download a copy of MQTT MQTT Explorer | An all-round MQTT client that provides a structured topic overview (mqtt-explorer.com)