Adding zigbee2mqtt docker container to Home Assistant

My old Mint Linux laptop ("cottage") already runs Home Assistant as a docker container.

I now want to add a Sonoff USB zigbee dongle to provide zigbee2mqtt for it.

Following the instructions at: https://www.zigbee2mqtt.io/guide/installation/02_docker.html

I plugged in the ZBDongle-P (https://sonoff.tech/en-eu/products/sonoff-zigbee-3-0-usb-dongle-plus-zbdongle-p)

cottage@cottage-AMILO-Pro-Series-V8210:~$ date
Sun 04 Oct 2026 17:49:48 IST

cottage@cottage-AMILO-Pro-Series-V8210:~$ docker run    --name zigbee2mqtt    --restart=unless-stopped    --device=/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_18ab6971458aef1198d7baa3ef8776e9-if00-port0    -p 8180:8080    -v $(pwd)/data:/app/data    -v /run/udev:/run/udev:ro    -e TZ=Europe/Amsterdam    ghcr.io/koenkk/zigbee2mqtt

Using '/app/data' as data directory

Starting Zigbee2MQTT without watchdog.

Onboarding page is available at http://0.0.0.0:8080/

Now looking at http://172.28.207.40:8180/ I get the Zigbee2MQTT Onboarding control panel

Where I selected the USB dongle and set up access to my local MQTT server. But when I clicked on submit it crashed....

cottage@cottage-AMILO-Pro-Series-V8210:~$ docker run    --name zigbee2mqtt    --restart=unless-stopped    --device=/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_18ab6971458aef1198d7baa3ef8776e9-if00-port0    -p 8180:8080    -v $(pwd)/data:/app/data    -v /run/udev:/run/udev:ro    -e TZ=Europe/Amsterdam    ghcr.io/koenkk/zigbee2mqtt
Using '/app/data' as data directory
Starting Zigbee2MQTT without watchdog.
Onboarding page is available at http://0.0.0.0:8080/
[2026-10-04 19:03:47] info:     z2m: Logging to console, file (filename: log.log)
[2026-10-04 19:03:47] info:     z2m: External JS (converters/extensions) is disabled
[2026-10-04 19:03:47] info:     z2m: Starting Zigbee2MQTT version 2.14.2 (commit #5c0c1c60078e1737c5dee5f8217583bca7610e66
)
[2026-10-04 19:03:47] info:     z2m: Starting zigbee-herdsman (10.10.0)
[2026-10-04 19:03:48] info:     zh:adapter:discovery: Matched adapter: {"path":"/dev/ttyUSB0","manufacturer":"ITead","serialNumber":"18ab6971458aef1198d7baa3ef8776e9","pnpId":"usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_18ab6971458aef1198d7baa3ef8776e9-if00-port0","vendorId":"10c4","productId":"ea60"} => zstack: 4
[2026-10-04 19:03:48] info:     zh:zstack:znp: Opening SerialPort with {"path":"/dev/ttyUSB0","baudRate":115200,"rtscts":false,"autoOpen":false}
[2026-10-04 19:03:48] error:    z2m: Error while starting zigbee-herdsman
[2026-10-04 19:03:48] error:    z2m: Failed to start zigbee-herdsman
[2026-10-04 19:03:48] error:    z2m: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start_crashes-runtime.html for possible solutions
[2026-10-04 19:03:48] error:    z2m: Exiting...
[2026-10-04 19:03:48] error:    z2m: Error: Error: No such file or directory, cannot open /dev/ttyUSB0
cottage@cottage-AMILO-Pro-Series-V8210:~$ ls -al /dev/ttyUSB0 
crw-rw----+ 1 root dialout 188, 0 Oct  4 17:48 /dev/ttyUSB0

So tried using a docker-compose.yaml file next... It appears to be running and the onboarding URL still works. 

cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ docker ps
CONTAINER ID   IMAGE                                               COMMAND                  CREATED         STATUS                 PORTS                                                                                                                                     NAMES
21c367c966e1   ghcr.io/koenkk/zigbee2mqtt                          "docker-entrypoint.s…"   2 minutes ago   Up About a minute      0.0.0.0:8180->8080/tcp, [::]:8180->8080/tcp                                                                                               zigbee2mqtt
fe6073fda2b6   ghcr.io/nextcloud-releases/aio-domaincheck:latest   "/start.sh"              11 days ago     Up 11 days (healthy)   0.0.0.0:443->443/tcp, [::]:443->443/tcp                                                                                                   nextcloud-aio-domaincheck
51d370ce0c3b   ghcr.io/nextcloud-releases/all-in-one:latest        "/start.sh"              12 days ago     Up 12 days (healthy)   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 0.0.0.0:8443->8443/tcp, [::]:8443->8443/tcp, 9000/tcp   nextcloud-aio-mastercontainer
537d6342b1a8   portainer/portainer-ce                              "/portainer"             12 days ago     Up 12 days             8000/tcp, 9443/tcp, 0.0.0.0:9000->9000/tcp, [::]:9000->9000/tcp                                                                           portainer
f3334b17bdfe   ghcr.io/home-assistant/home-assistant:stable        "/init"                  4 weeks ago     Up 3 weeks                                                                                                                                                       homeassistant
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ date
Sun 04 Oct 2026 18:16:08 IST
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ 

But how to control it? The last time I used this it listed all devices allowed for joining, etc. Ah I need to enable the frontend (disable onbaording) in the configuration.yaml file and restart it!

cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ cat data/configuration.yaml 
version: 5
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://***SECRET ***:1883
  password: ***SECRET ***
  user: ***SECRET ***
serial:
  port: /dev/ttyUSB0
  adapter: zstack
  baudrate: 115200
  rtscts: false
advanced:
  log_level: info
  channel: 11
  network_key:
    - 254
    - 211
    - 68
    - 22
    - 58
    - 56
    - 250
    - 47
    - 128
    - 49
    - 238
    - 228
    - 90
    - 12
    - 209
    - 230
  pan_id: 53974
  ext_pan_id:
    - 136
    - 21
    - 24
    - 143
    - 233
    - 86
    - 235
    - 52
  enable_external_js: false
frontend:
  enabled: false
  port: 8080
homeassistant:
  enabled: false
onboarding: true
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ vim data/configuration.yaml 
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ ls -al data/configuration.yaml 
-rw-r--r-- 1 root root 632 Oct  4 18:14 data/configuration.yaml
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ sudo vim data/configuration.yaml 
[sudo] password for cottage:           
Sorry, try again.
[sudo] password for cottage:             
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ 
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ docker ps
CONTAINER ID   IMAGE                                               COMMAND                  CREATED          STATUS                 PORTS                                                                                                                                     NAMES
21c367c966e1   ghcr.io/koenkk/zigbee2mqtt                          "docker-entrypoint.s…"   18 minutes ago   Up 16 minutes          0.0.0.0:8180->8080/tcp, [::]:8180->8080/tcp                                                                                               zigbee2mqtt
fe6073fda2b6   ghcr.io/nextcloud-releases/aio-domaincheck:latest   "/start.sh"              11 days ago      Up 11 days (healthy)   0.0.0.0:443->443/tcp, [::]:443->443/tcp                                                                                                   nextcloud-aio-domaincheck
51d370ce0c3b   ghcr.io/nextcloud-releases/all-in-one:latest        "/start.sh"              12 days ago      Up 12 days (healthy)   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 0.0.0.0:8443->8443/tcp, [::]:8443->8443/tcp, 9000/tcp   nextcloud-aio-mastercontainer
537d6342b1a8   portainer/portainer-ce                              "/portainer"             12 days ago      Up 12 days             8000/tcp, 9443/tcp, 0.0.0.0:9000->9000/tcp, [::]:9000->9000/tcp                                                                           portainer
f3334b17bdfe   ghcr.io/home-assistant/home-assistant:stable        "/init"                  4 weeks ago      Up 3 weeks                                                                                                                                                       homeassistant
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ docker compose restart zigbee2mqtt
[+] restart 0/1
 ⠧ Container zigbee2mqtt Restarting                                                                                       1.7s
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ 
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ docker ps
CONTAINER ID   IMAGE                                               COMMAND                  CREATED          STATUS                 PORTS                                                                                                                                     NAMES
21c367c966e1   ghcr.io/koenkk/zigbee2mqtt                          "docker-entrypoint.s…"   18 minutes ago   Up 3 seconds           0.0.0.0:8180->8080/tcp, [::]:8180->8080/tcp                                                                                               zigbee2mqtt
fe6073fda2b6   ghcr.io/nextcloud-releases/aio-domaincheck:latest   "/start.sh"              11 days ago      Up 11 days (healthy)   0.0.0.0:443->443/tcp, [::]:443->443/tcp                                                                                                   nextcloud-aio-domaincheck
51d370ce0c3b   ghcr.io/nextcloud-releases/all-in-one:latest        "/start.sh"              12 days ago      Up 12 days (healthy)   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp, 0.0.0.0:8443->8443/tcp, [::]:8443->8443/tcp, 9000/tcp   nextcloud-aio-mastercontainer
537d6342b1a8   portainer/portainer-ce                              "/portainer"             12 days ago      Up 12 days             8000/tcp, 9443/tcp, 0.0.0.0:9000->9000/tcp, [::]:9000->9000/tcp                                                                           portainer
f3334b17bdfe   ghcr.io/home-assistant/home-assistant:stable        "/init"                  4 weeks ago      Up 3 weeks                                                                                                                                                       homeassistant
cottage@cottage-AMILO-Pro-Series-V8210:~/zigbee2mqtt$ 

Now keep getting start up errors:

Using '/app/data' as data directory
Starting Zigbee2MQTT without watchdog.
[2026-10-04 18:39:30] info: z2m: Logging to console, file (filename: log.log)
[2026-10-04 18:39:30] info: z2m: External JS (converters/extensions) is disabled
[2026-10-04 18:39:30] info: z2m: Starting Zigbee2MQTT version 2.14.2 (commit #5c0c1c60078e1737c5dee5f8217583bca7610e66
)
[2026-10-04 18:39:30] info: z2m: Starting zigbee-herdsman (10.10.0)
[2026-10-04 18:39:30] info: zh:adapter:discovery: Matched adapter: {"path":"/dev/ttyUSB0","manufacturer":"ITead","serialNumber":"18ab6971458aef1198d7baa3ef8776e9","pnpId":"usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_18ab6971458aef1198d7baa3ef8776e9-if00-port0","vendorId":"10c4","productId":"ea60"} => zstack: 4
[2026-10-04 18:39:30] info: zh:zstack:znp: Opening SerialPort with {"path":"/dev/ttyUSB0","baudRate":115200,"rtscts":false,"autoOpen":false}
[2026-10-04 18:39:30] error: z2m: Error while starting zigbee-herdsman
[2026-10-04 18:39:30] error: z2m: Failed to start zigbee-herdsman
[2026-10-04 18:39:30] error: z2m: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start_crashes-runtime.html for possible solutions
[2026-10-04 18:39:30] error: z2m: Exiting...
[2026-10-04 18:39:30] error: z2m: Error: Error: No such file or directory, cannot open /dev/ttyUSB0

So tried restarting the "cottage" laptop. Still keeps restarting due to above error..

Maybe a USB 3.0 port issue. I will try on a RPi 4 tomorrow... (My "cttage" laptop is old Lenovo ThinkPad T420 and doesn't have 3.0 USB ports just 2.0 ones)

https://www.productindetail.com/pn/lenovo-thinkpad-t420#specs

(19:39) Decided to burn a Home Assistant OS 18.3 image onto a RPi4 Model B..

https://www.raspberrypi.com/products/raspberry-pi-4-model-b/

Which has 2x USB 3 ports