Supercharge Your IoT: Running Zigbee2MQTT via Docker on a Pi Zero 2 W

In our last post, we built a bulletproof MQTT broker. Now, it’s time to give that broker something to talk to. Today, we’re setting up Zigbee2MQTT using Docker on a Raspberry Pi Zero 2 W.
By bridging your Zigbee devices (sensors, bulbs, switches) directly to MQTT, you free yourself from proprietary hubs and cloud services. We'll be using a Sonoff Zigbee 3.0 Dongle Plus V2 for this setup. Since the Pi Zero 2 W is a low-power device, we’ll do a little prep work to ensure Docker runs smoothly.
Let’s get into it!
Step 1: Increase the Swap Size
The Raspberry Pi Zero 2 W has 512MB of RAM. Docker can be a bit memory-hungry, so we need to increase the swap file size to prevent the system from crashing under load.
Bash
sudo nano /etc/dphys-swapfile

Find the CONF_SWAPSIZE line and change it to 1024:
Plaintext
CONF_SWAPSIZE=1024

Save the file, exit, and restart the swap service:
Bash
sudo systemctl restart dphys-swapfile

Step 2: Install Docker
Next, we’ll bring the Pi up to date and install Docker using their automated convenience script.
Bash
sudo apt-get update && sudo apt-get upgrade -y
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Once installed, add your user to the Docker group so you don’t have to type sudo for every command (you may need to log out and log back in for this to take effect):
Bash
sudo usermod -aG docker $USER

Step 3: Setup Directories (and Restore Backups)
Let's create the folder where Zigbee2MQTT will store its database and configuration.
Bash
cd /home/rasp-zero-mqtt/
mkdir zigbee2mqtt_data

Note: If you are migrating from an older setup and have a backup archive, you can extract it into this folder now using a command like tar -xf zigbee2mqtt_data.tar.
Step 4: Create the Docker Compose File
Docker Compose makes managing containers a breeze. We'll map your specific Sonoff Zigbee dongle directly into the container.
Bash
nano /home/rasp-zero-mqtt/docker-compose.yaml

Paste the following configuration:
YAML
services:
zigbee2mqtt:
container_name: zigbee2mqtt
image: koenkk/zigbee2mqtt
restart: unless-stopped
network_mode: host
volumes:
- /home/rasp-zero-mqtt/zigbee2mqtt_data:/app/data
- /run/udev:/run/udev:ro
- /etc/localtime:/etc/localtime:ro
environment:
- TZ=Asia/Amman
- ZIGBEE2MQTT_CONFIG_FRONTEND_AUTH_TOKEN=New_Password
devices:
# Map the stable ID to ttyUSB0 inside the container
- /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_5cc186dc0bc3ef118755e6b08048b910-if00-port0:/dev/ttyUSB0

Step 5: Configure Zigbee2MQTT
Before we spin up the container, we need to give Zigbee2MQTT its marching orders—specifically, where your MQTT broker is and how to talk to the Sonoff dongle.
Bash
nano /home/rasp-zero-mqtt/zigbee2mqtt_data/configuration.yaml

Add the following, ensuring you update the MQTT server credentials to match your setup:
YAML
homeassistant:
enabled: true
mqtt:
base_topic: zigbee2mqtt
server: mqtt://your_mqtt_host_server
user: your_mqtt_broker_username
password: your_mqtt_broker_password
serial:
port: /dev/ttyUSB0
adapter: ezsp
baudrate: 115200
frontend:
enabled: true
port: 8081
version: 4
advanced:
channel: 25
devices:
availability:
enabled: true

Step 6: Fire It Up!
With the configuration saved, all that's left is to start the container in the background (-d for detached mode).
Bash
sudo docker compose up -d

Give it a few moments to initialize. Once it's running, you can navigate to http://:8081 in your web browser, enter your frontend auth token (New_Password), and start pairing your Zigbee devices!



"If you've got any questions or need a hand wrangling your own setup, don't hesitate to reach out at [email protected] or connect with me via www.yazan.me. I'm always keen to help out!"