Zigbee2MQTT¶
Zigbee bridge. Publishes to the Mosquitto broker running as a Home Assistant add-on, not a broker in the Swarm.
| Runtime | Container (Docker Swarm) |
| Tier | Core |
| Node | swarm-core |
| Image | koenkk/zigbee2mqtt:2.12.1 |
| URL | https://zigbee2mqtt.lab.riversfamily.uk |
| Auth | Forward-auth (authentik@swarm) — no native OIDC |
| Source | ansible/stacks/core/zigbee2mqtt/ |
tier=core because this is the node the Zigbee USB adaptor is passed
through to (see below), not because Zigbee2MQTT depends on anything else
running on swarm-core.
Configuration¶
MQTT broker connection: ZIGBEE2MQTT_CONFIG_MQTT_SERVER=mqtt://{{ mqtt_host }}:{{ mqtt_port }},
credentials mqtt_username/mqtt_password — set in
ansible/inventory/group_vars/all/vars.yml. mqtt_host is currently empty
(the Home Assistant VM's broker is not yet configured), so this service is
currently non-functional pending that and the USB adaptor choice below.
USB adaptor passthrough¶
The physical Zigbee USB adaptor is handed down two levels: Proxmox host to
the swarm-core VM (via zigbee_usb_hostspec, consumed by the proxmox_vm
role), then VM to container (via zigbee_serial_device, mapped with a
devices: entry in this compose file). Both variables default to empty in
group_vars/all/vars.yml, and the container's device mapping is skipped
entirely ({% if zigbee_serial_device | length > 0 %}) until the adaptor
model is chosen. Prefer a /dev/serial/by-id/... path for
zigbee_serial_device so it survives reboots.
Volumes¶
| Volume | Path | Backing | Contents |
|---|---|---|---|
data |
/app/data |
Local | Zigbee2MQTT state and config |
Secrets¶
| Vault variable | Delivered as | Purpose |
|---|---|---|
vault_mqtt_password |
Plain env var (MQTT_PASSWORD) |
MQTT broker password — no file-based option |
Gotchas¶
- Not yet functional: needs the Zigbee USB adaptor chosen
(
zigbee_usb_hostspec,zigbee_serial_device) and the Home Assistant Mosquitto broker configured (mqtt_host). - Depends on the Home Assistant VM being up for its MQTT broker — an accepted coupling, not considered a bug.