furtka-apps/apps/zigbee2mqtt/docker-compose.yaml

# Furtka Zigbee2MQTT — Zigbee-to-MQTT bridge (dependency consumer).
#
# Declares `requires: [{app: mosquitto, ...}]` in manifest.json. Installing
# this app pulls in mosquitto first; mosquitto's provision-client.sh hook then
# creates a dedicated MQTT account and writes MQTT_SERVER / MQTT_USER /
# MQTT_PASS into THIS app's .env before the container below starts. We feed
# those into zigbee2mqtt via its ZIGBEE2MQTT_CONFIG_* env overrides, so no
# configuration.yaml has to be templated by hand.
#
# host.docker.internal: the broker runs in a separate compose project on a
# separate network, so we reach its host-published 1883 via the docker
# host-gateway. The hook hands us mqtt://host.docker.internal:1883 to match.
#
# Hardware: zigbee2mqtt needs a physical Zigbee USB coordinator. ${ZIGBEE_SERIAL_PORT}
# is a required text setting (a `path`-type setting can't express a /dev node:
# the validator rejects non-directories and the /dev deny-list). The `devices`
# entry maps that host device into the container. The `:-/dev/null` fallback is
# ONLY so `docker compose config` (catalog validation, run with no .env) parses
# cleanly; a real install always has the device set. zigbee-herdsman opens the
# serial adapter BEFORE connecting to MQTT, so on a box with no stick attached
# the container exits early and never reaches the broker — the dependency
# handshake is verified provider-side instead (the account + creds land in this
# app's .env at install time).
#
# Frontend: z2m 1.42's default config is `frontend: true` (boolean shorthand,
# enabled on port 8080). We deliberately set NO ZIGBEE2MQTT_CONFIG_FRONTEND_*
# env here: a nested override like FRONTEND_PORT/FRONTEND_ENABLED makes z2m try
# to write a property onto that boolean and crash on boot with
# "Cannot create property 'port' on boolean 'true'". The default 8080 is what we
# publish to the host as 8084 below, so no override is needed.
#
# Port 8084 on the host -> 8080 in the container (8080 is taken by it-tools).
#
# TODO(image-pin): pin to a digest once verified against the upstream registry.

services:
  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:1.42.0
    restart: unless-stopped
    ports:
      - "8084:8080"
    environment:
      - TZ=Europe/Berlin
      - ZIGBEE2MQTT_CONFIG_MQTT_SERVER=${MQTT_SERVER}
      - ZIGBEE2MQTT_CONFIG_MQTT_USER=${MQTT_USER}
      - ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD=${MQTT_PASS}
      - ZIGBEE2MQTT_CONFIG_SERIAL_PORT=${ZIGBEE_SERIAL_PORT}
    devices:
      - ${ZIGBEE_SERIAL_PORT:-/dev/null}:${ZIGBEE_SERIAL_PORT:-/dev/null}
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - furtka_zigbee2mqtt_data:/app/data

volumes:
  furtka_zigbee2mqtt_data:
    external: true