I don’t have any guide for that, but I’ll try to summarize briefly what a quick search gave me.
Assuming you’ve got Docker and Docker-compose up and running on a Raspberry.
Create 2 containers using docker-compose.yml files.
You obviously need to adapt ports and path to your liking.
MQTT
mosquitto:
container_name: mosquitto
image: eclipse-mosquitto:2
restart: unless-stopped
ports:
- "1883:1883/tcp"
volumes:
- ./data/mosquitto/config:/mosquitto/config
- ./data/mosquitto/data:/mosquitto/data
- ./data/mosquitto/log:/mosquitto/log
environment:
- TZ=Europe/Berlin # Match your timezone
healthcheck:
test: ["CMD", "mosquitto_sub", "-u", "test", "-P", "test_user_password", "-h", "localhost", "-t", "$$SYS/broker/uptime", "-i", "docker_health_check", "-C", "1"]
interval: 1m
timeout: 10s
retries: 3
Then in /data/mosquitto/config
you’ll want to create a config file. Mine for instance looks like:
persistence true
persistence_location /mosquitto/data/
password_file /mosquitto/config/pwfile
allow_anonymous false
log_dest file /mosquitto/log/mosquitto.log
listener 1883
And once you start the container you can create a user in mosquitto with a command like this:
docker compose exec mosquitto mosquitto_passwd -b /mosquitto/config/pwfile test test_user_password
Once you’ve created a user you need to restart mosquitto (restart the container).
You’d need to also create a user for zigbee2mqtt and another one for Home Assistant.
Then, we can create the Z2M container.
Zigbee2MQTT
services:
zigbee2mqtt:
container_name: zigbee2mqtt
image: ghcr.io/koenkk/zigbee2mqtt
restart: unless-stopped
volumes:
- ./data/z2m:/app/data # a folder on your Pi to store the config files
- /run/udev:/run/udev:ro
ports:
# WebUI port
- 8080:8080
environment:
- TZ=Europe/Berlin # Match your timezone
devices:
# Make sure this matched your adapter location
- /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0
Once the container is running, go to the WebUI (port 8080 in the example below) to continue the configuration, it’s pretty straightforward.
Lastly, in Home Assistant, add the MQTT integration and add an entry for the MQTT broker installed on the RPi.
All Zigbee devices added through Z2M will be published to MQTT and Home Assistant will see them if properly connected to MQTT.
Hope that could help you,
Sources:
MQTT - Home Assistant