Starting with MQTT using Docker and Home Assistant

MQTT is a great protocol to have in your automation arsenal. This article explains how to quickly get started with MQTT using Docker and Home Assistant.

Note: I now use the Eclipse MQTT container and have written an updated MQTT, Docker, and Home Assistant article. I’m leaving this article as a reference.

MQTT, Home Assistant and Docker together
MQTT working with Clients, Docker, and Home Assistant

What is MQTT and what can I do with it?

MQTT, which stands for Message Queuing Telemetry Transport, is often described as the protocol of the Internet of Things (IOT). It’s a lightweight publish/subscribe system where clients can both publish and subscribe to messages. It works well for IOT devices because it is low-bandwidth.

MQTT uses a broker to facilitate communication between subscribers and publishers. In the diagram above, Home Assistant subscribes to messages published by sensors and jobs. However, Home Assistant can also be a publisher and the clients can also be subscribers.

Common uses of MQTT include:

  • Sharing and reacting to sensor information like temperature, humidity, motion, and light levels
  • Integrating alarm panels that don’t normally talk to your smarthome hub
  • For relays to communicate with home automation controllers to open gates, garage doors, even to control irrigation, heating and cooling systems
  • As a substitute for devices that don’t have an API or a standard way to communicate with other devices in your ecosystem. You can build these devices for pennies on the dollar compared to their commercial counterparts

I am currently using MQTT to provide Home Assistant with the status of my home backups and some cron jobs. I also use MQTT to interface with a homebrew garage door controller, temperature/humidity/motion multisensor, and relays that control light switches.

What is Docker?

Docker Logo

Docker is a virtualization technology, similar to virtual machines. Instead of virtualizing an entire operating system, Docker allows you to virtualize an application into a container for maximum portability and flexibility. I previously wrote an article about Docker so I won’t go into too much detail here.

See also  Home Assistant Can Control Google Assistant

What is Home Assistant?

Home Assistant Social Logo

Home Assistant is a software-based smarthome hub with a focus on security and local control. It is the brain of my smarthome. I’ve written lots about it if you want to learn more.

Setting up MQTT in Docker

Picking a broker is the first part of getting started with MQTT. Home Assistant comes with an embedded broker. Cloud-based brokers are popular as well. I went with Mosquitto because it’s popular and there’s a Docker image.

Set up persistent data and base configuration

I chose to go with the Toke Mosquitto container because I easily found good documentation. You should set up persistent data directories and the base configuration file (mosquitto.conf) before starting your container. I’m basing this tutorial on my Ubuntu 18.04 system, but this should work with most Linux systems:

mkdir -p /storage/mosquitto/config
mkdir -p /storage/mosquitto/data
mkdir -p /storage/mosquitto/log

Replace the directories with whatever is appropriate to you. You should copy a mosquitto.conf file into the “config” directory. My base mosquitto file:

# Place your local configuration in /mqtt/config/conf.d/

pid_file /var/run/

persistence true
persistence_location /mqtt/data/

user mosquitto

# Port to use for the default listener.
port 1883

log_dest file /mqtt/log/mosquitto.log
log_dest stdout

include_dir /mqtt/config/conf.d

Create and run the container

Now the easy part, the Docker run command:

sudo docker run -itd \
--name=mqtt \
--restart=always \
--net=host \
-v /storage/mosquitto/config:/mqtt/config:ro \
-v /storage/mosquitto/data:/mqtt/data \
-v /storage/mosquitto/log:/mqtt/log \

This command tells the container to where to look for config, data, and log files. I’ve pointed these to the local directories I set up earlier. My Mosquitto MQTT broker should be up and running now.

Testing MQTT

To test, install the mosquitto client package:

sudo apt install mosquitto-clients

This will get you access to publish and subscribe commands. First, start by opening a terminal and subscribing to a topic:

mosquitto_sub -h <brokerhost> -t "test"

Replace <brokerhost> with the IP or hostname of your broker. This starts a subscription to any messages that are published with the topic “test.”

See also  6 Most Common Problems with Robot Vacuum Cleaners

In another terminal send a message to the topic test:

mosquitto_pub -h <brokerhost> -t "test" -m "Hello World" 

After entering this command, “Hello World” should show up in the terminal where you ran the mosquitto_sub command. If you see it, your broker is working!

Adding security

As it is currently set up, any client can connect to your broker to publish and subscribe to any topic. You can add some security by requiring a username and password for clients to connect to the broker.

First, you’ll need to create a password file. The best way is to connect to your container and run mosquitto_passwd. In order to connect to your container’s console you need to find out its ID:

docker ps

This will give you a list of containers and their IDs. Using that ID you can then run:

docker exec -it <containerID> bash

Replacing <containerID> with the container of your Mosquitto container will give you a command line. Alternatively, you can use Portainer to connect directly to the console.

From the console run something similar to:

mosquitto_passwd -c /mqtt/config/credentials <username>

With appropriate filename and username arguments, this command will ask for a password and then create a hashed password file. Then you need to update your Mosquitto config.

If you used a mosquitto.conf file similar to what I posted above you need to create a default.conf file in the conf.d subdirectory of your config directory with the following contents:

allow_anonymous false
password_file /mqtt/config/credentials

Remember to use the appropriate password_file path and filename. After restarting the container your publish and subscribe commands will need to have a username and password to work:

mosquitto_sub -h <brokerhost> -t "test" -u "<username>" -P "<password>"
mosquitto_pub -h <brokerhost> -t "test" -m "Hello World" -u "<username>" -P "<password>"

You can make your broker more secure by using web sockets or TLS. Digital Ocean has a great tutorial.

Configuring Home Assistant for MQTT

This is as simple as adding the following code to your configuration.yaml:

  broker: <brokerip>
  username: <mqtt_username>
  password: <mqtt_password>

You don’t need the username and password if you did not configure your broker to use one. Then, you want to configure Home Assistant to subscribe to some topics. I decided to test this by subscribing to a topic that displays the time of my last Home Assistant backup:

  - platform: mqtt
    name: "Last HA config backup"
    state_topic: "backup/HA"

I added a mosquitto_pub statement to my backup script. It simply sends the time of the last backup to the topic “backup/HA.” Here is the sensor card in the UI that displays the message:

Sensor card for MQTT

Final thoughts

MQTT is cool, solid, and fast. It provides an easy way to pass information. It also makes it easy to integrate inexpensive hardware. Running it in Docker and configuring Home Assistant to use MQTT is a straightforward process.

See also  Shelly Plus Plug US: Improvement on Excellence

I have a few MQTT projects upcoming/completed that I’ll write about over the next few weeks:

As a reminder, I wrote an updated MQTT article that you should use if you are interested in setting it up in Docker.

Are any of you using MQTT? What do you use it for? Let me know in the comments or connect with me on Twitter!

This page contains affiliate links. If you purchase an item using an affiliate link I will receive a small commission at no cost to you. Affiliates do not influence my recommendations. Read my disclosures for more information.

Share this:

Starting with MQTT using Docker and Home Assistant

by HomeTechHacker time to read: 5 min