Home Assistant in Docker #4: Add-ons. MQTT and Zigbee2MQTT

In the current post series, I’m describing the path I took from a regular Home Assistant setup on Home Assistant Blue to a home server with Docker and various software. Assuming we already have our Home Assistant in Docker up and running, it is time to add some addons to it.

Previous posts in series:

• Debian Buster on ODROID-N2+ aka Home Assistant Blue
• Installing Docker on ODROID-N2+ with Debian Buster
• docker-compose.yml for Home Assistant and MariaDB explained

Today’s post could be an example of how to add some additional smart home software (known as add-ons on a regular Home Assistant installation) to an existing Home Assistant Docker installation.

Having our docker-compose.yaml from the previous post, we now could add additional services to it.

Mosquitto Broker aka MQTT

Under the services section of our docker-compose.yaml let’s add:

  mosquitto:
    image: eclipse-mosquitto
    container_name: mosquitto
    volumes:
      - /root/mosquitto:/mosquitto
    ports:
      - 1883:1883
      - 9001:9001
    restart: unless-stopped

The /root/mosquitto folder here should be created by us with the configuration files in it. Sure you can choose any other path for MQTT configuration, but in docker-compose.yaml the path of the second part of this volume should always be the same: /mosquitto.

Now we need to create a config folder with a new mosquitto.conf file in our MQTT directory (/root/mosquitto in the current example) with the next content:

persistence true
persistence_location /mosquitto/data/

log_dest stdout
log_dest file /mosquitto/log/mosquitto.log
log_type warning
log_timestamp true
connection_messages true

listener 1883

#password_file /mosquitto/config/password.txt

As you can see, we have password_file entry in our config. It is commented for now, so will not be used. password.txt file will store MQTT username and hashed password for a broker to use. In case you want to allow unauthenticated connections, you should replace password_file line with:

allow_anonymous true

Otherwise, we need to make Mosquitto generate a password.txt file for us by connecting to a running Docker container. So we are starting our broker executing this from the place of our docker-compose.yaml:

docker compose up -d mosquitto

After that, we will connect to our Mosquitto container with:

docker exec -it mosquitto /bin/sh

We are now inside the container and can make Mosquitto create credentials with:

mosquitto_passwd -c /mosquitto/config/password.txt mqttuser

This will ask us to enter a new password for mqttuser we are creating and write all the needed information into a password.txt.

Use exit command to disconnect from a container.

Now stop the container with:

docker compose stop mosquitto

Uncomment password_file entry in mosquitto.conf file to make it look like this:

persistence true
persistence_location /mosquitto/data/

log_dest stdout
log_dest file /mosquitto/log/mosquitto.log
log_type warning
log_timestamp true
connection_messages true

listener 1883

password_file /mosquitto/config/password.txt

And start broker again:

docker compose start mosquitto

Home Assistant MQTT integration

We will need MQTT integration configured in our Home Assistant now. Use “mosquitto” as the Broker address, leave “1883” port as is and use newly created credentials as username and password (“mqttuser” in our example).

Done!

Zigbee2MQTT

In our docker-compose.yaml where we have our Home Assistant and MQTT services declined, let’s add a new service:

 zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    container_name: zigbee2mqtt
    volumes:
      - /root/zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8099:8099
    environment:
      - TZ=Europe/Kyiv
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff:/dev/ttyACM0
    restart: unless-stopped

/root/zigbee2mqtt/data should be created by us to store all necessary data. This is also a location where you can copy all configuration files and network data from your previous Zigbee2MQTT instance. See the documentation for more information.

/dev/serial/by-id/usb-ITead_Sonoff should be replaced with your ZigBee device path. Using the “serial/by-id” path is recommended to make sure it would not be changed when you put your device in another USB port of your server. To know the ID of your ZigBee dongle, use:

ls /dev/serial/by-id/

If it is not working, see the corresponding documentation section.

In case this is a new Zigbee2MQTT instance, we need to start a container for configuration files to be created:

docker compose up -d zigbee2mqtt

After a successful start, wait for configuration.yaml to appear in /root/zigbee2mqtt/data folder. Once it is there – stop the container:

docker compose stop zigbee2mqtt

Now let’s edit the configuration.yaml. You need to replace existing entries if any.

Here is the MQTT configuration using our Mosquitto container name as the address and credentials we’ve created previously:

mqtt:
  base_topic: zigbee2mqtt
  user: mqttuser
  password: *******
  server: mqtt://mosquitto:1883

This is a port number for the web interface (frontend) we mentioned in docker-compose.yaml:

frontend:
  port: 8099

This is our ZigBee coordinator path from docker-compose.yaml where we’ve mapped our real device path:

serial:
  port: >-
    /dev/ttyACM0

And this is the most important part of configuration.yaml:

homeassistant: true

All other entries could be configured later from the UI. Now:

docker compose start zigbee2mqtt

And Zigbee2MQTT’s frontend should be available through our server’s IP address or hostname and the port we’ve configured. For example http://192.168.1.43:8099

That’s all for today.