by In this tutorial, we will show you how to self-host Zigbee2MQTT using Docker.
Zigbee2MQTT is a super neat tool that replaces your proprietary Zigbee bridges and leaves you in control of your connected devices. This software works by taking control of a Zigbee coordinator and using that to build a Zigbee
A key advantage of using this software is that it is actively developed and supports a huge range of Zigbee devices and adaptors. It even features built-in support for over-the-air updates (OTA) for devices that allow it.
Using the official Docker container is one of the easiest ways to get Zigbee2MQTT up and running on your device. This container makes maintaining and managing your Zigbee2MQTT a breeze, especially when it comes to ensuring you are running the latest release.
Of course, you will need a couple of things to use this Zigbee bridging software. The first is a Zigbee coordinator, we personally use a Sonoff Zigbee USB adaptor (Amazon Affiliate) in our own setup and have so far found it to be a very capable and reliable device.
The second thing you need is an MQTT broker., In this guide, we will be setting up one alongside the Zigbee2MQTT, but you can bring your own.
If you want to use Zigbee2MQTT with Home Assistant, we highly recommend using the add-on version instead. The advantage of this is that it sets itself up and integrates itself a bit cleaner than running it separately in a container. Of course, if you are running Home Assistant using Docker, you won’t be able to use the addon version.
Additionally, for those running a Raspberry Pi, we have a dedicated guide on installing Zigbee2MQTT.
Setting up Zigbee2MQTT using Docker
Over the following sections, we will walk you through the process of setting up Zigbee2MQTT using Docker.
The development team provides builds for almost all major architectures, so the guide below should work on any Linux-based operating system.
Preparing for Zigbee2MQTT on your Machine
1. Before you proceed, you will require the Docker runtime to be installed on your machine.
If you haven’t this installed before, we highly recommend our installing Docker on Linux guide.
https://pimylifeup.com/linux-docker-install/2. With Docker installed, our next step is to create a folder to store the Compose file for Zigbee2MQTT.
You can create this directory by using the mkdir command within the terminal.
sudo mkdir -p /opt/stacks/zigbee2mqtt3. Now that we have created a folder, change to it by using the command below.
cd /opt/stacks/zigbee2mqttIdentifying your Zigbee Adapter
4. One of the key things that you need for Zigbee2MQTT to work is a Zigbee adapter.
Once you are ready to proceed, plug your Zigbee adapter into your machine. If you already have the adapter, unplug it and plug it back in.
What we are trying to achieve here is a message from our system so we can see where the device is being mounted.
5. Once you have your Zigbee adapter plugged in, use the following command to print the output of the kernel buffer to the terminal.
This will allow us to see kernel messages, including the ones showing the adapter connecting.
sudo dmesg6. You will want to scroll to the bottom of the output and see something similar to what we have shown below. A different Linux system may show this message slightly differently.
[1067876.235950] usb 1-1.3: new full-speed USB device number 6 using xhci_hcd
[1067876.352763] usb 1-1.3: New USB device found, idVendor=1a86, idProduct=55d4, bcdDevice= 4.42
[1067876.352780] usb 1-1.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[1067876.352786] usb 1-1.3: Product: SONOFF Zigbee 3.0 USB Dongle Plus V2
[1067876.352792] usb 1-1.3: Manufacturer: ITEAD
[1067876.352797] usb 1-1.3: SerialNumber: 20231031163548
[1067876.360193] cdc_acm 1-1.3:1.0: ttyACM0: USB ACM device7. Looking through the output from this message, you will want to find a value such as “ttyUSB0“. This value represents the device name, and you will use it when filling out the Compose file later on in this guide.
In our example, the line we were looking at to find this value is shown below. If you are still unsure which device is which, try unplugging and plugging your adapter back in again.
[1067876.360193] cdc_acm 1-1.3:1.0: ttyACM0: USB ACM deviceWriting a Docker Compose File to Manage Zigbee2MQTT
8. At this point, we can move on to writing the Docker Compose file that will set up and manage the ZIgbee2MQTT container.
You can begin writing this Compose file using the following command within the terminal. We use Nano as it is fairly easy for beginners to use.
sudo nano compose.yaml9. Within this Compose file, you will want to fill out the following lines. These lines set up two separate containers. The first is the Mosquitto MQTT broker; the second is Zigbee2MQTT.
If you happen to already have an MQTT Broker installed and running, simply remove the MQTT broker from this Compose file.
While filling out this Compose file, you must replace two placeholders.
<TIMEZONE>: You will want to swap this out with the TZ Identifier for where you live.
You can find a list of TZ Identifiers and their valid values from Wikipedia. For example, we live in Hobart so we would use “Australia/Hobart“.<DEVICENAME>: Replace this placeholder with the device name that you would have worked out in the previous section.
For example, if your device was mounted to the same place as ours, you would use “ttyUSB0” here.
services:
mqtt:
image: eclipse-mosquitto:2
restart: unless-stopped
volumes:
- "./mosquitto-data:/mosquitto"
ports:
- "1883:1883"
- "9001:9001"
command: "mosquitto -c /mosquitto-no-auth.conf"
zigbee2mqtt:
container_name: zigbee2mqtt
restart: unless-stopped
image: koenkk/zigbee2mqtt
volumes:
- ./zigbee2mqtt-data:/app/data
- /run/udev:/run/udev:ro
ports:
- 8080:8080
environment:
- TZ=<TIMEZONE>
devices:
- /dev/<DEVICENAME>:/dev/<DEVICENAME>10. Once you have finished writing out this file, save and quit by pressing CTRL + X, Y, and then ENTER.
Writing a Config File for the Zigbee2MQTT Container
11. We still need to finish setting up the Zigbee2MQTT Docker container. Our next step is to write a config file that the software will read when it starts up.
Before we can write this config file, we will need to create the directory it sits in by using the command below.
sudo mkdir /opt/stacks/zigbee2mqtt/zigbee2mqtt-data12. Once the directory has been created, you can begin writing the required configuration file by using the following command within the terminal.
sudo nano /opt/stacks/zigbee2mqtt/zigbee2mqtt-data/configuration.yaml13. Within this file, enter the following lines of information.
These lines set up several things for Zigbee2MQTT to use. The first block configures the MQTT broker with which the Zigbee bridge should communicate.
The next block configures the serial device that the software will use to communicate with your Zigbee adapter. In our example, this will be the USB adapter plugged into our machine.
Next is the configuration for the frontend. The default port for Zigbee2MQTT to use for its web interface is “8080“.
There is one placeholder you must replace while filling out this file.
<DEVICENAME>: Replace this placeholder with the device name for your Zigbee adapter. This value must match the one you entered when filling out the Docker Compose file earlier.
permit_join: true
mqtt:
base_topic: zigbee2mqtt
server: mqtt://mqtt
serial:
port: /dev/<DEVICENAME>
frontend:
port: 8080
advanced:
network_key: GENERATE14. After filling out the config file, save and quit by pressing CTRL + X, Y, and then ENTER.
Starting up the Zigbee2MQTT Docker Container
15. After writing the Docker Compose and configuration files, you can start the Zigbee2MQTT container.
Starting up this container is as simple as running the following command. Docker will automatically start and manage Zigbee2MQTT from now on.
docker compose up -dAccessing the Zigbee2MQTT Web Interface
16. Now that the Zigbee2MQTT Docker container is up and running, you will want to access its web interface.
The web interface is how you will manage the various software settings. To access this web interface, you will need to know the IP address of your machine. One of the easiest ways to get this IP is to use the hostname command.
hostname -I17. In your favorite web browser, you will want to go to the following address to access Zigbee2MQTT.
Replace “<IPADDRESS>” with the IP of the device where you are hosting this service.
http://<IPADDRESS>:808018. At this point, you have successfully managed to get the Zigbee2MQTT bridge up and running using Docker.
You can turn on and off joining at any time by using the button in the top-right corner of the screen. You can also deactivate or activate this permanently through the settings screen.
19. You can now pair your Zigbee devices to your Zigbee2MQTT bridge. If you are unsure how to pair your device, the Zigbee2MQTT team provides a list of devices it officially supports and instructions on how to put them into pairing mode.
As long as Zigbee2MQTT is in join mode, it will automatically accept any new Zigbee device that is in pairing mode.
Below, you can see that we have already paired both a Zigbee router as well as a few smart water valves we use for irrigation.
Updating to the Latest Version of Zigbee2MQTT using Docker
A key reason to use Docker to run Zigbee2MQTT is that it dramatically simplifies both the setup and update process.
Over the following steps, we will show you the steps for easily updating to the latest version of the Zigbee2MQTT container.
1. Before you can update the Zigbee2MQTT Docker container, change to the directory where we wrote the Compose file.
Assuming you followed our tutorial, you can change to the correct folder by using the command below.
cd /opt/stacks/zigbee2mqtt2. Once we are in the correct folder, we can get Docker to pull the latest version of the Zigbee2MQTT container by using the following command.
While this command will download the latest image, it won’t update your existing container.
docker compose pull3. Luckily for us, updating a running container is a relatively simple process thanks to Docker Compose.
Run the command below to get Docker to automatically restart your running container on the new image.
docker compose up -dConclusion
Hopefully, at this point in the guide, you will have successfully managed to get Zigbee2MQTT up and running on your device.
Zigbee2MQTT is one of the go-to solutions for self-hosting a Zigbee bridge. It is actively maintained and has some of the best support for Zigbee devices; it is also incredibly simple to use.
Please feel free to leave a comment below if you have had any issues with getting this Zigbee2MQT container working.
If you found this tutorial helpful, we recommend exploring some of our many other Docker tutorials.
