Zigbee2mqtt dockerized on Raspberry OS

CAUTION This is a cheat-sheet for a fast startup. Security requirements are not considered here. If you follow the instructions, apps will be available from outside of the host without even any password protection! You have been warned.

Install Docker

• Install Docker via automated script
  curl -sSL https://get.docker.com | sh

• Consider setting up the Docker daemon in rootless mode for your user
  sudo apt install uidmap
dockerd-rootless-setuptool.sh install

• Some info from the installer good to keep it for later

  • To control docker.service, run: systemctl --user (start|stop|restart) docker.service
  • To run docker.service on system startup, run: sudo loginctl enable-linger pi
  • Make sure the following environment variable(s) are set (or add them to ~/.bashrc): export PATH=/usr/bin:$PATH
  • Some applications may require the following environment variable too: export DOCKER_HOST=unix:///run/user/1000/docker.sock

• Good to know about rootless mode

  • Access to some devices will require an explicit exposition with the --device option.
  • Some containers do explicitly use a non-0 uid, in some cases this can be changed with the --user option, in some not.
  • Networking works slightly different. Especially the custom chains DOCKER or DOCKER-USER are not used in this case. Consider it, when creating firewall rules.

Install mosquitto

• Make directories for config (MQTT_CONFIG_DIR), data (MQTT_DATA_DIR) and logs (MQTT_LOG_DIR)
• Create a config file mqtt-config/mosquitto.conf

1
2
3
4
5

persistence true # CAUTION - consider persistence
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
allow_anonymous true # CAUTION - make sure you really want it
listener 1883 0.0.0.0

• Create virtual network
  docker network create YOUR_NETWORK
• Start mosquitto

1
2
3
4
5
6
7
8

docker run --rm \
--name mosquitto \
-p 1883:1883 \
-v MQTT_CONFIG_DIR:/mosquitto/config \
-v MQTT_DATA_DIR:/mosquitto/data \
-v MQTT_LOG_DIR:/mosquitto/log \
--network YOUR_NETWORK \
eclipse-mosquitto

Install zigbee2mqtt

• Rootless docker will not so easily allow the container to access the physical device, more here Can't use serial device in rootless docker with dialout group #43019 on Github
  • The suggested mapping of group-ids did not work in my case
  • Easiest runtime solution (assuming the device /dev/ttyUSB0)
    sudo chmod 666 /dev/ttyUSB0
  • Same, but permanent
    sudo nano /etc/udev/rules.d/99-user.rules
    add line SUBSYSTEMS=="usb", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="XXXX", MODE="0666"
    and reboot (reload via sudo udevadm control --reload seems no to have the rights to apply the new mode)
    for debugging udev see Debugging udev
• Start zigbee2mqtt

1
2
3
4
5
6
7
8
9

docker run --rm \
--name zigbee2mqtt \
-p 8080:8080 \
-v ZIGBEE2MQTT_DATA_DIR:/app/data \
-v /run/udev:/run/udev:ro \
--device=/dev/ttyUSB0 \
--network YOUR_NETWORK \
-e TZ=Europe/Amsterdam \
ghcr.io/koenkk/zigbee2mqtt

• Configure mqtt address to mqtt://mosquitto:1883

Final commands for automatic mode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

docker run -d \ # daemon
-i \ # interactive mode
--restart unless-stopped \ # auto-restart, manual stop takes precedence
--name mosquitto \
-p 1883:1883 \
-v MQTT_CONFIG_DIR:/mosquitto/config \
-v MQTT_DATA_DIR:/mosquitto/data \
-v MQTT_LOG_DIR:/mosquitto/log \
--network YOUR_NETWORK \
eclipse-mosquitto

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

docker run -d \ # daemon
-i \ # interactive mode
--restart unless-stopped \
--name zigbee2mqtt -p 8080:8080 \
-v ZIGBEE2MQTT_DATA_DIR:/app/data \
-v /run/udev:/run/udev:ro \
--device=/dev/serial/by-id/XXXXX \ # unique identification of the device
--network YOUR_NETWORK \
-e TZ=Europe/Amsterdam \
ghcr.io/koenkk/zigbee2mqtt

Next: InfluxDB3 on Raspberry Pi / jemalloc: Unsupported system page size

Previous: Search for a host with no tools on Windows

Main Menu