Zigbee2MQTT Docker Compose: so setze ich es sauber auf

Wenn ich zigbee2mqtt docker compose einrichte, will ich drei Dinge: schnelle Installation, stabile Verbindung zum Zigbee-Adapter und eine Konfiguration, die ich später ohne Chaos erweitern kann. Genau darum geht es hier.

Zigbee2MQTT ist eines der besten Tools, wenn du Zigbee-Geräte flexibel steuern willst. Statt dich an ein proprietäres Gateway zu binden, läuft alles lokal. Mit Docker Compose wird das Setup sauber, reproduzierbar und leicht wartbar.

Warum ich Zigbee2MQTT mit Docker Compose nutze

Ich nutze Docker Compose, weil ich keine Lust auf manuelle Bastelinstallationen habe. Ein Compose-Setup ist klar, versionierbar und in Minuten wiederhergestellt. Das ist besonders stark, wenn du dein Smart Home ernst nimmst.

• Einfaches Deployment: Ein Befehl startet den Container.
• Saubere Updates: Neues Image ziehen, Container neu starten.
• Weniger Abhängigkeiten: Alles ist in einer Datei dokumentiert.
• Bessere Kontrolle: Du bestimmst Ports, Volumes und Gerätezugriff.

Wenn du Zigbee2MQTT direkt auf dem Host installierst, geht das auch. Aber Docker Compose ist für die meisten Setups der schnellere und robustere Weg.

Zigbee2MQTT Docker Compose: Grundvoraussetzungen

Bevor ich starte, prüfe ich immer diese Punkte:

• Ein laufender Docker-Host
• Docker Compose Dokumentation als Referenz
• Ein Zigbee-USB-Adapter, zum Beispiel Sonoff, ConBee oder vergleichbar
• Der richtige Gerätepfead, meist /dev/ttyUSB0 oder /dev/ttyACM0
• Ein MQTT-Broker, meist Mosquitto

Wichtig: Zigbee2MQTT braucht fast immer einen MQTT-Broker. Ohne Broker läuft die Gerätekommunikation nicht sinnvoll. Wenn du keinen hast, setze zuerst Mosquitto auf.

Beispiel für Zigbee2MQTT Docker Compose

Das ist ein solides Basis-Setup für zigbee2mqtt docker compose:

version: "3.8"
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    network_mode: bridge

Das ist bewusst simpel. Ich mag einfache Setups, weil sie leichter zu debuggen sind. Sobald das läuft, kann ich es erweitern.

Die wichtigste Zigbee2MQTT Konfiguration

Die Container-Datei allein reicht nicht. Du brauchst auch die configuration.yaml im Datenverzeichnis.

homeassistant: true
permit_join: false
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://YOUR_MQTT_BROKER_IP'
serial:
  port: /dev/ttyUSB0
frontend:
  port: 8080
advanced:
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Ein paar Punkte dazu:

• homeassistant: true ist sinnvoll, wenn du Home Assistant nutzt.
• permit_join: false lässt nur gezieltes Pairing zu.
• mqtt.server muss auf deinen Broker zeigen.
• serial.port muss exakt zum Adapter passen.

Typische Fehler bei Zigbee2MQTT Docker Compose

Hier scheitern die meisten. Nicht an Zigbee2MQTT selbst, sondern an Kleinigkeiten, die später viel Zeit kosten.

• Falscher USB-Port: Der Adapter hängt nicht an dem Gerät, das du denkst.
• Berechtigungsproblem: Der Docker-Container darf nicht auf den Serial-Port zugreifen.
• MQTT falsch konfiguriert: Broker-Adresse oder Login stimmen nicht.
• USB-Stromsparmodus: Der Adapter fällt sporadisch aus.
• Zu nah an Störquellen: USB 3.0 und WLAN können Zigbee stören.

Mein Ansatz: erst die Hardware sauber machen, dann die Software. Nicht andersrum.

So finde ich den richtigen Zigbee-Adapter-Port

Wenn ich nicht sicher bin, welchen Port der Adapter nutzt, prüfe ich direkt auf dem Host:

ls -l /dev/serial/by-id/

Das ist besser als blind /dev/ttyUSB0 zu nehmen. Der /dev/serial/by-id/-Pfad ist stabiler, weil er sich bei Neustarts meist nicht ändert.

Wenn möglich, verwende ich immer diesen Pfad im Compose-Setup. Das spart Probleme nach Reboots.

Best Practices für ein stabiles Setup

Wenn du willst, dass zigbee2mqtt docker compose langfristig stabil läuft, mache es nicht kompliziert. Mach es sauber.

• Nutze einen festen USB-Verlängerer: Der Adapter sollte nicht direkt am Server hängen.
• Halte Abstand zu WLAN-Routern: Funkstörungen killen Reichweite und Stabilität.
• Verwende den by-id-Pfad: Weniger Überraschungen nach Reboots.
• Backup das Datenverzeichnis: Besonders configuration.yaml und Pairing-Daten.
• Updates kontrolliert einspielen: Nicht blind jedes neue Image sofort ziehen.

Das klingt banal, ist aber der Unterschied zwischen einem System, das läuft, und einem System, das du ständig reparierst.

Wie ich Zigbee2MQTT mit Home Assistant verbinde

Wenn du Home Assistant nutzt, wird Zigbee2MQTT richtig interessant. Ich lasse Zigbee2MQTT die Geräte verwalten und Home Assistant die Automationen steuern.

Dafür brauchst du in der Regel:

• MQTT in Home Assistant aktiviert
• homeassistant: true in Zigbee2MQTT
• Den gleichen MQTT-Broker für beide Systeme

Die offizielle Zigbee2MQTT-Dokumentation findest du hier: Zigbee2MQTT Docker Installation.

Update-Strategie für Zigbee2MQTT

Ich update Zigbee2MQTT nicht aus Gewohnheit, sondern mit Absicht. Das ist ein Infrastruktur-Tool. Wenn es läuft, soll es laufen.

Mein Ablauf:

1. Release Notes prüfen
2. Wenn nötig Backup machen
3. Neues Image ziehen
4. Container neu starten
5. Logs prüfen

Wichtig: Ein Update kann Geräte oder Konfiguration beeinflussen. Also nicht blind handeln. Erst lesen, dann klicken.

Fazit zu Zigbee2MQTT Docker Compose

Wenn ich zigbee2mqtt docker compose aufsetze, will ich ein System, das leicht, stabil und wartbar ist. Genau das liefert dir Docker Compose, wenn du die Basics richtig machst: korrekter USB-Pfad, sauberer MQTT-Broker, persistente Daten und ein vernünftiges Backup.

Mein Rat ist simpel: Starte klein, halte das Setup sauber und optimiere erst dann. So bekommst du ein Smart-Home-System, das nicht nur heute läuft, sondern auch in sechs Monaten noch verlässlich funktioniert. zigbee2mqtt docker compose ist dafür einer der besten Wege.