Docker

It is possible to run Zigbee2MQTT in a Docker container using the official Zigbee2MQTT Docker imageopen in new window.

This image support the following architectures: 386, amd64, arm/v6, arm/v7, arm64. Since Zigbee2MQTT images are manifest listed, Docker will auto-detect the architecture and pull the right image.

Start by figuring out the location of your adapter as explained here.

IMPORTANT: Using a Raspberry Pi? Make sure to check Notes for Raspberry Pi users.

Creating the initial configuration

Navigate to the directory where you will store the Zigbee2MQTT data and execute the following command:

wget https://raw.githubusercontent.com/Koenkk/zigbee2mqtt/master/data/configuration.yaml -P data

Now configure the MQTT server and adapter location as explained here.

Running the container

Execute the following command, update the --device parameter to match the location of your adapter.

$ docker run \
   --name zigbee2mqtt \
   --restart=unless-stopped \
   --device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0 \
   -p 8080:8080 \
   -v $(pwd)/data:/app/data \
   -v /run/udev:/run/udev:ro \
   -e TZ=Europe/Amsterdam \
   koenkk/zigbee2mqtt

Parameters explanation:

  • --name zigbee2mqtt: Name of container
  • --restart=unless-stopped: Automatically start on boot and restart after a crash
  • --device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0: Location of adapter (e.g. CC2531). The path before the : is the path on the host, the path after it is the path that is mapped to inside the container. You should always use the /dev/serial/by-id/ path on the host.
  • -v $(pwd)/data:/app/data: Directory where Zigbee2MQTT stores it configuration (pwd maps to the current working directory)
  • -v /run/udev:/run/udev:ro: only required for auto-detecting the port and some adapters like ConBee
  • -e TZ=Europe/Amsterdam: Configure the timezone
  • -p 8080:8080: port forwarding from inside Docker container to host (for the frontend)

TIP

If you run the MQTT-Server on the same host (localhost) you could use the IP of the docker0 bridge to establish the connection: server: mqtt://172.17.0.1.

Rootless container

To improve the security of the deployment you may want to run Zigbee2MQTT as a non-root user.

  1. Identify the group that has access to the adapter (in Ubuntu, e.g. it might be assigned to dialout). Update ttyACM0 to match your adapter location.
$ ls -l /dev/ttyACM0
crw-rw---- 1 root dialout 166, 0 Nov 5 16:31 /dev/ttyACM0
  1. If you want to run Zigbee2MQTT using your current user find the uid (UserID) and gid (GroupID):
$ id
uid=1001(pi) gid=1001(pi) Groups=...
  1. Start the docker container after updating device, user (uid:gid) and group-add:
$ sudo docker run \
   --name=zigbee2mqtt \
   --restart=unless-stopped \
   -p 8080:8080 \
   -v $(pwd)/data:/app/data \
   -v /run/udev:/run/udev:ro \
   --device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0 \
   --user 1001:1001 \
   --group-add dialout \
   -e TZ=Europe/Amsterdam \
   koenkk/zigbee2mqtt

3.1

Parameters explanation:

  • --user 1001:1001: Run the Zigbee2MQTT process within the container using the provided UserID and GroupID
  • --group-add dialout: Assign the dialout group to the user to be able to access the device

Rootless with Podman (>3.2)

$ podman run \
   --name=zigbee2mqtt \
   --restart=unless-stopped \
   -p 8080:8080 \
   -v $(pwd)/data:/app/data \
   -v /run/udev:/run/udev:ro \
   --device=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0 \
   --group-add keep-groups \
   -e TZ=Europe/Amsterdam \
   koenkk/zigbee2mqtt

Updating

To update to the latest Docker image:

docker pull koenkk/zigbee2mqtt:latest
docker rm -f zigbee2mqtt
# Now run the container again with the instructions above

Tags

The following tags are available:

  • Latest release version: latest
  • Latest dev version (based on devopen in new window branch): latest-dev
  • Specific release version, e.g: 1.7.0

Docker Compose

Example of a Docker Compose file:

version: '3.8'
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      # Frontend port
      - 8080:8080
    environment:
      - TZ=Europe/Berlin
    devices:
      # Make sure this matched your adapter location
      - /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00:/dev/ttyACM0

You can also run a rootless container with Docker Compose by adding the required attributes to the zigbee2mqtt service block in your docker-compose.yml:

    group_add:
      - dialout
    user: 1000:1000

Starting the container

To start the Docker container:

docker compose up -d zigbee2mqtt

You can optionally skip zigbee2mqtt and it will start all containers listed in the compose file.

Updating

To update to the latest Docker image:

docker compose pull zigbee2mqtt
docker compose up -d zigbee2mqtt

You can optionally skip zigbee2mqtt and it will pull any new images for all containers in the compose file, and then restart those that were updated.

Notes for Raspberry Pi users

  • If you are running Raspbian Buster (not Bullseye!) (find out by executing grep "PRETTY_NAME" /etc/os-release) you need to install libseccomp2, this can be done by executing the following commands:
sudo apt-key adv --keyserver hkps://keyserver.ubuntu.com:443 --recv-keys 04EE7237B7D453EC 648ACFD622F3D138
echo "deb http://httpredir.debian.org/debian buster-backports main contrib non-free" | sudo tee -a "/etc/apt/sources.list.d/debian-backports.list"
sudo apt update
sudo apt install libseccomp2 -t buster-backports

If you do not do this you will get the following error when starting the Zigbee2MQTT container:

#
# Fatal error in , line 0
# unreachable code
#
#
#
#FailureMessage Object: 0x7eace25c
  • For Raspberry Pi 1 and zero users: there is a bug in Docker which selects the wrong image architecture. Before executing docker run pull the correct image with docker pull koenkk/zigbee2mqtt --platform linux/arm/v6.

Docker Stack device mapping

This is only relevant when using Docker Stack

Docker stack doesn't support device mappings with option --devices when deploying a stack in swarm mode. There are two solutions to this. Both of these solutions start with binding the devices as volumes.

Automatic device mapping for cgroup v1 and v2

The easiest solution for enabling devices on Docker Stacks is the allfro device-mapping-manager docker imageopen in new window. This container has a tiny program that reads all of the volume mounts on its own host, identifies devices, and then modifies the permissions on the host to allow the container to use them. Unlike other solutions, this works for both versions of cgroups.

This container has to be deployed directly to docker, not through a stack. It's possible to work around this by creating a stack with a privileged service that acts as a proxy to launch the actual device mapper container.

version: "3.8"

services:
  dmm:
    image: docker
    entrypoint: docker
    restart: unless-stopped
    privileged: true
    command: |
      run
      -i
      --rm
      --privileged
      --cgroupns=host
      --pid=host
      --userns=host
      -v /sys:/host/sys
      -v /var/run/docker.sock:/var/run/docker.sock
      -v /dev:/dev
      ghcr.io/allfro/allfro/device-mapping-manager:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      mode: global

Manual cgroup v1

A workaround is to manually set the right permissions. The workaround is based on the solution found at Add support for devices with "service create"open in new window, all credits goes this him.

This workaround only works with cgroup v1, which is not enabled on many newer distro releases.

  1. Identify serial adapter Identify the serial adapter using the following command:

    sudo lsusb -v
    
    Bus 001 Device 005: ID 0451:16a8 Texas Instruments, Inc.
    Device Descriptor:
      bLength                18
      bDescriptorType         1
      bcdUSB               2.00
      bDeviceClass            2 Communications
      bDeviceSubClass         0
      bDeviceProtocol         0
      bMaxPacketSize0        32
      idVendor           0x0451 Texas Instruments, Inc.
      idProduct          0x16a8
      bcdDevice            0.09
      iManufacturer           1 Texas Instruments
      iProduct                2 TI CC2531 USB CDC
      iSerial                 3 __0X00124B001936AC60
      bNumConfigurations      1
      Configuration Descriptor:
    	bLength                 9
    	bDescriptorType         2
    	wTotalLength           67
    	bNumInterfaces          2
    	bConfigurationValue     1
    	iConfiguration          0
    	bmAttributes         0x80
    	  (Bus Powered)
    	MaxPower               50mA
    	Interface Descriptor:
    	  bLength                 9
    	  bDescriptorType         4
    	  bInterfaceNumber        0
    	  bAlternateSetting       0
    	  bNumEndpoints           1
    	  bInterfaceClass         2 Communications
    	  bInterfaceSubClass      2 Abstract (modem)
    	  bInterfaceProtocol      1 AT-commands (v.25ter)
    	  iInterface              0
    	  CDC Header:
    		bcdCDC               1.10
    	  CDC ACM:
    		bmCapabilities       0x02
    		  line coding and serial state
    	  CDC Union:
    		bMasterInterface        0
    		bSlaveInterface         1
    	  CDC Call Management:
    		bmCapabilities       0x00
    		bDataInterface          1
    	  Endpoint Descriptor:
    		bLength                 7
    		bDescriptorType         5
    		bEndpointAddress     0x82  EP 2 IN
    		bmAttributes            3
    		  Transfer Type            Interrupt
    		  Synch Type               None
    		  Usage Type               Data
    		wMaxPacketSize     0x0040  1x 64 bytes
    		bInterval              64
    	Interface Descriptor:
    	  bLength                 9
    	  bDescriptorType         4
    	  bInterfaceNumber        1
    	  bAlternateSetting       0
    	  bNumEndpoints           2
    	  bInterfaceClass        10 CDC Data
    	  bInterfaceSubClass      0 Unused
    	  bInterfaceProtocol      0
    	  iInterface              0
    	  Endpoint Descriptor:
    		bLength                 7
    		bDescriptorType         5
    		bEndpointAddress     0x84  EP 4 IN
    		bmAttributes            2
    		  Transfer Type            Bulk
    		  Synch Type               None
    		  Usage Type               Data
    		wMaxPacketSize     0x0040  1x 64 bytes
    		bInterval               0
    	  Endpoint Descriptor:
    		bLength                 7
    		bDescriptorType         5
    		bEndpointAddress     0x04  EP 4 OUT
    		bmAttributes            2
    		  Transfer Type            Bulk
    		  Synch Type               None
    		  Usage Type               Data
    		wMaxPacketSize     0x0040  1x 64 bytes
    		bInterval               0
    Device Status:     0x0000
      (Bus Powered)
    
  2. UDEV Rules

    Create a new udev rule for serial adapter, idVendor and idProduct must be equal to values from lsusb command. The rule below creates device /dev/zigbee-serial:

    echo "SUBSYSTEM==\"tty\", ATTRS{idVendor}==\"0451\", ATTRS{idProduct}==\"16a8\", SYMLINK+=\"zigbee-serial\",  RUN+=\"/usr/local/bin/docker-setup-zigbee-serial.sh\"" | sudo tee /etc/udev/rules.d/99-zigbee-serial.rules
    

    Reload newly created rule using the following command:

    sudo udevadm control --reload-rules
    
  3. Create docker-setup-zigbee-serial.sh

    sudo nano /usr/local/bin/docker-setup-zigbee-serial.sh
    

    Copy the following content:

    #!/bin/bash
    USBDEV=`readlink -f /dev/zigbee-serial`
    read minor major < <(stat -c '%T %t' $USBDEV)
    if [[ -z $minor || -z $major ]]; then
    	echo 'Device not found'
    	exit
    fi
    dminor=$((0x${minor}))
    dmajor=$((0x${major}))
    CID=`docker ps -a --no-trunc | grep koenkk/zigbee2mqtt | head -1 |  awk '{print $1}'`
    if [[ -z $CID ]]; then
    	echo 'CID not found'
    	exit
    fi
    echo 'Setting permissions'
    echo "c $dmajor:$dminor rwm" > /sys/fs/cgroup/devices/docker/$CID/devices.allow
    

    Set permissions:

    sudo chmod 744 /usr/local/bin/docker-setup-zigbee-serial.sh
    
  4. Create docker-event-listener.sh

    sudo nano /usr/local/bin/docker-event-listener.sh
    

    Copy the following content:

    #!/bin/bash
    docker events --filter 'event=start'| \
    while read line; do
    	/usr/local/bin/docker-setup-zigbee-serial.sh
    done
    

    Set permissions:

    sudo chmod 744 /usr/local/bin/docker-event-listener.sh
    
  5. Create docker-event-listener.service

    sudo nano /etc/systemd/system/docker-event-listener.service
    

    Copy the following content:

    [Unit]
    Description=Docker Event Listener for Zigbee serial adapter
    After=network.target
    StartLimitIntervalSec=0
    [Service]
    Type=simple
    Restart=always
    RestartSec=1
    User=root
    ExecStart=/bin/bash /usr/local/bin/docker-event-listener.sh
    
    [Install]
    WantedBy=multi-user.target
    

    Set permissions:

    sudo chmod 744 /etc/systemd/system/docker-event-listener.service
    

    Reload daemon

    sudo systemctl daemon-reload
    

    Start Docker event listener

    sudo systemctl start docker-event-listener.service
    

    Status Docker event listener

    sudo systemctl status docker-event-listener.service
    

    Enable Docker event listener

    sudo systemctl enable docker-event-listener.service
    
  6. Verify and deploy Zigbee2MQTT stack

    Now reconnect the serial adapter. Verify using the following command:

    ls -al /dev/zigbee-serial
    
    lrwxrwxrwx 1 root root 7 Sep 28 21:14 /dev/zigbee-serial -> ttyACM0
    

    Below an example of a docker-stack-zigbee2mqtt.yml:

    version: "3.7"
    services:
      zigbee2mqtt:
    	image: koenkk/zigbee2mqtt:latest-dev
    	environment:
    	  - TZ=Europe/Amsterdam
    	volumes:
    	  - /mnt/docker-cluster/zigbee2mqtt/data:/app/data
    	  - /dev/zigbee-serial:/dev/zigbee-serial
    	networks:
    	  - proxy_traefik-net
    	deploy:
    	  placement:
    		constraints: [node.hostname == rpi-3]
    	  replicas: 1
    
    networks:
      proxy_traefik-net:
    	external: true
    

    In the above example, proxy_traefik-net is the network to connect to the mqtt broker. The constraint makes sure Docker deploys only to this (rpi-3) node, where the serial adapter is connected to. The volume binding /mnt/docker-cluster/zigbee2mqtt/data is the zigbee2mqtt persistent directory, where configuration.yaml is saved.

    The zigbee2Zigbee2MQTTmqtt configuration.yaml should point to /dev/zigbee-serial:

    [...]
      port: /dev/zigbee-serial
    [...]
    

    Deploy the stack:

    docker stack deploy zigbee2mqtt --compose-file docker-stack-zigbee2mqtt.yml
    

Troubleshooting

It could happen that even after the above the container is not starting correctly and bringing a "Operation not permitted" message in the log of the service for the device:

Error: Error while opening serialport 'Error: Error: Operation not permitted, cannot open /dev/zigbee-serial'

This is due to the usage of cgroupv2 instead of cgroupv1 which is not fully supported by docker/containerd. To switch from cgroupv2 to cgroupv1 you have to add systemd.unified_cgroup_hierarchy=false to the grub cmdline. E.g. on an Raspberry Pi 4 with Raspian Bullseye you can add it to the end of the line in the /boot/cmdline.txt file:

[...] rootfstype=ext4 fsck.repair=yes rootwait cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=false

Docker on Synology DSM 7.0

NOTE: This may not work with all Zigbee controllers, but has been tested with the CC2531.

As of Disk Station Manager version 7, Synology removed the built-in support for USB-devices like a Zigbee controller. The USB support can be installed to the Linux kernel by issuing the following commands as root.

modprobe usbserial
modprobe ftdi_sio
modprobe cdc-acm

After issuing the commands, the Zigbee controller may need to be unplugged and re-inserted to the USB port.

You may also need additional drivers based on your USB Zigbee controller setup, e.g. CH341 module is not included by default. You can download precompiled modules from jadahl.com pages - select module directory based on NAS CPU architecture (DS218+ -> INTEL Celeron J3355 -> Apollo Lake).

cd /lib/modules
wget http://www.jadahl.com/iperf-arp-scan/DSM_7.0/apollolake/ch341.ko
insmod /lib/modules/ch341.ko

It is possible to create a start-up task that issues the above commands:

  1. Create an executable script file that contains the three modprobe commands.
  2. Using DSM's Control Panel -> Task Scheduler -> Create -> Triggered Task -> User-defined script with the settings: User: root, Event: Boot-up, and a bash command executing the executable file under Task Settings.