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://<your-pi-ip>: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!"