Zigbee2MQTT + Mosquitto on naruto — Design Spec

Date: 2026-06-03

Goal

Run Zigbee2MQTT and Mosquitto as Docker containers on naruto, managed by the raspberry_pi Ansible role. Home Assistant (running in k3s) connects to Mosquitto over the LAN.

Hardware

Host: naruto (Pi 4, 192.168.20.13)
Zigbee coordinator: SONOFF Dongle Lite MG21 on /dev/ttyUSB0
Stable by-id path: /dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Lite_MG21_0263f93f46a2ef11b078926661ce3355-if00-port0

Architecture

Two containers via Docker Compose on naruto. Ansible templates all configs and manages the stack. Home Assistant adds the MQTT integration pointing at 192.168.20.13:1883.

[SONOFF Dongle /dev/ttyUSB0]
        |
[zigbee2mqtt container]
        | MQTT (internal docker network)
[mosquitto container] :1883
        |
[Home Assistant in k3s] — via LAN 192.168.20.13:1883

Directory Layout on naruto

/opt/docker/
  config/
    mosquitto/
      mosquitto.conf
      data/
      log/
    zigbee2mqtt/
      configuration.yaml
      data/
  compose/
    docker-compose.yml

Mosquitto Config

Listens on port 1883
No authentication (internal LAN only)
Persistence enabled, logs to /opt/docker/config/mosquitto/log/

Zigbee2MQTT Config

Serial port: /dev/serial/by-id/usb-SONOFF_SONOFF_Dongle_Lite_MG21_0263f93f46a2ef11b078926661ce3355-if00-port0
MQTT broker: mqtt://mosquitto:1883 (internal docker network)
Network key: stored in vars/group_vars/raspberry_pi/secrets.yaml as vault_raspberry_pi.zigbee2mqtt.network_key
Frontend enabled on port 8080 for local device management

Secrets

vars/group_vars/raspberry_pi/secrets.yaml (vault-encrypted, placeholder for now):

vault_raspberry_pi:
  zigbee2mqtt:
    network_key: "YOUR_ZIGBEE_NETWORK_KEY"

Ansible Changes

Action	Path	Responsibility
Modify	`roles/raspberry_pi/tasks/main.yaml`	Include numbered task files
Create	`roles/raspberry_pi/tasks/10_directories.yaml`	Create `/opt/docker/` tree
Create	`roles/raspberry_pi/tasks/20_zigbee2mqtt.yaml`	Template configs, start compose
Create	`roles/raspberry_pi/templates/zigbee2mqtt/docker-compose.yml.j2`	Compose file
Create	`roles/raspberry_pi/templates/zigbee2mqtt/mosquitto.conf.j2`	Mosquitto config
Create	`roles/raspberry_pi/templates/zigbee2mqtt/z2m-configuration.yaml.j2`	Zigbee2MQTT config
Create	`vars/group_vars/raspberry_pi/secrets.yaml`	Network key placeholder

Host Constraint

The raspberry_pi role applies to both naruto and pi. The Zigbee2MQTT tasks must be guarded with when: inventory_hostname == 'naruto' since the USB dongle is only on naruto.

2.7 KiB Raw Blame History