Zigbee2MQTT mit Docker installieren: Verbindet Zigbee-Geräte ohne Hersteller-Gateway

Zigbee-Geräte von Philips Hue, IKEA Trådfri, Aqara oder Tuya verlangen meist eine eigene Bridge samt Cloud-Anbindung. Zigbee2MQTT (Version 2.14.1, Stand September 2026) verbindet stattdessen über einen USB-Adapter mehrere Tausend Geräte zahlreicher Hersteller direkt mit einem lokalen MQTT-Broker. MQTT ist ein schlankes Nachrichtenprotokoll, bei dem ein zentraler Broker Nachrichten zwischen Geräten und Anwendungen verteilt. Home Assistant, ioBroker, Node-RED, OpenHAB oder eigene Anwendungen sprechen darüber vollständig lokal mit den Geräten.

Voraussetzungen

1. Docker Engine >= 20.10 und Docker Compose Plugin >= 2.0 auf einem Linux-Host (Ubuntu, Debian, Raspberry Pi OS) – siehe Docker und Docker Compose auf Linux installieren
2. Zigbee-USB-Adapter auf Basis von Texas-Instruments-Chips (CC2652P, z. B. Sonoff Zigbee 3.0 USB Dongle Plus) oder Silicon-Labs-Chips (EFR32MG21), am Host eingesteckt.
3. Linux-Host mit USB-Port im Heimnetz (x86_64 oder ARM): Server, Raspberry Pi 3/4/5, Mini-PC oder NAS mit Docker. Ein Cloud-VPS scheidet aus, da der Adapter physisch am Host steckt. 1 CPU-Kern und 1 GB RAM reichen für beide Container, dazu etwa 1 GB Speicher für Images und Daten.
4. Mindestens 256 MB RAM für den Zigbee2MQTT-Container; Mosquitto benötigt zusätzlich ca. 10–20 MB
5. Terminal- oder SSH-Zugang zum Docker-Host
6. Mindestens ein Zigbee-Gerät zum Testen (Schalter, Lampe, Sensor)
7. Optional: Reverse Proxy für HTTPS-Zugriff von außen – z. B. per Traefik als Docker-Reverse-Proxy

Schritt 1: Adapter-Pfad auf dem Host ermitteln

Ermitteln Sie zuerst den Gerätepfad des USB-Dongles. Stecken Sie den Adapter ein und führen Sie aus:

ls /dev/serial/by-id/

Die Ausgabe sieht in etwa so aus:

usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00

Notieren Sie den vollständigen Pfad mit dem Präfix /dev/serial/by-id/; er ist stabiler als /dev/ttyACM0, das sich nach einem Neustart ändern kann. Ist /dev/serial/by-id/ leer, prüfen Sie mit lsusb, ob der Adapter erkannt wird, und mit ls /dev/ttyACM*, ob ein direkter Gerätepfad existiert.

Verifizieren: Der Befehl ls /dev/serial/by-id/ gibt mindestens einen Eintrag aus. lsusb zeigt das Gerät in der Liste (z. B. „Texas Instruments“ oder „Silicon Labs“).

Schritt 2: Projektordner und Verzeichnisstruktur anlegen

Alle Dateien liegen in einem Projektordner, persistente Daten in Unterverzeichnissen (Bind-Mounts).

mkdir -p /opt/zigbee2mqtt/data
mkdir -p /opt/zigbee2mqtt/mosquitto/config
mkdir -p /opt/zigbee2mqtt/mosquitto/data
mkdir -p /opt/zigbee2mqtt/mosquitto/log
cd /opt/zigbee2mqtt

Ohne minimale Konfigurationsdatei verweigert Eclipse Mosquitto 2 den Start:

cat > /opt/zigbee2mqtt/mosquitto/config/mosquitto.conf <<'EOF'
listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
EOF

Hinweis zur Sicherheit: allow_anonymous true eignet sich nur für ein isoliertes Heimnetz. Für produktive Umgebungen richten Sie MQTT-Authentifizierung ein (nicht Teil dieser Anleitung).

Verifizieren: ls /opt/zigbee2mqtt/ zeigt die Verzeichnisse data/, mosquitto/ und die Datei mosquitto/config/mosquitto.conf.

Schritt 3: Umgebungsvariablen in der .env-Datei festlegen

Zeitzone und Adapter-Pfad stehen in einer .env-Datei; bei einem Hardware-Wechsel bleibt die Compose-Datei unverändert.

# /opt/zigbee2mqtt/.env
TZ=Europe/Berlin

# Adapter-Pfad auf dem HOST (vor dem Doppelpunkt in der devices-Liste)
# Ermitteln mit: ls /dev/serial/by-id/
ZIGBEE_ADAPTER_HOST=/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00

Passen Sie TZ und ZIGBEE_ADAPTER_HOST (Pfad aus Schritt 1) an.

Verifizieren: cat /opt/zigbee2mqtt/.env zeigt beide Variablen mit korrekten Werten.

Schritt 4: compose.yaml erstellen

Der Stack besteht aus Eclipse Mosquitto (MQTT-Broker) und Zigbee2MQTT (Bridge) im gemeinsamen Netzwerk z2m-net; Zigbee2MQTT erreicht den Broker unter dem Service-Namen mosquitto.

# /opt/zigbee2mqtt/compose.yaml
services:

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto:2
    restart: unless-stopped
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - "1883:1883"
    networks:
      - z2m-net

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    depends_on:
      - mosquitto
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=${TZ}
    devices:
      # Pfad des USB-Adapters auf dem HOST (vor dem Doppelpunkt)
      # Diesen Pfad an Ihren Adapter anpassen!
      - ${ZIGBEE_ADAPTER_HOST}:/dev/ttyACM0
    # Rootless-Betrieb (optional, UID/GID des ausführenden Benutzers):
    # user: "1000:1000"
    # group_add:
    #   - dialout
    networks:
      - z2m-net

networks:
  z2m-net:
    driver: bridge

Hinweis zum Image: Die offizielle Dokumentation nutzt ghcr.io/koenkk/zigbee2mqtt; dieselben Tags gibt es als koenkk/zigbee2mqtt auf Docker Hub. :latest zieht bei jedem pull die neueste Version. Für planbare Updates schreiben Sie die Version fest, z. B. ghcr.io/koenkk/zigbee2mqtt:2.14.1.

Verifizieren: docker compose config im Projektordner zeigt die interpolierte Compose-Konfiguration ohne Fehler aus.

Eckdaten auf einen Blick

Schritt 5: Stack starten

Starten Sie den Stack im Projektordner:

cd /opt/zigbee2mqtt
docker compose up -d

Beim ersten Start lädt Docker beide Images; das Zigbee2MQTT-Image ist je nach Architektur ca. 200–400 MB groß.

Verifizieren:

docker compose ps

Erwartete Ausgabe (beide Services in Spalte STATUS als Up):

NAME            IMAGE                              SERVICE        STATUS          PORTS
mosquitto       eclipse-mosquitto:2                mosquitto      Up 28 seconds   0.0.0.0:1883->1883/tcp
zigbee2mqtt     ghcr.io/koenkk/zigbee2mqtt:latest  zigbee2mqtt    Up 25 seconds   0.0.0.0:8080->8080/tcp

Prüfen Sie die Logs beider Services auf Fehler:

docker compose logs mosquitto
docker compose logs zigbee2mqtt

Die Zigbee2MQTT-Logs dürfen keine Error- oder ENOENT-Meldungen zum Adapter zeigen. Mit aktivem Onboarding-Wizard erscheint Zigbee2MQTT started! oder ein Hinweis auf den Web-Server auf Port 8080.

Schritt 6: Onboarding-Wizard und Erst-Einrichtung im Browser

Rufen Sie das Web-Frontend auf:

http://<HOST-IP>:8080

Beim ersten Start führt der Onboarding-Wizard durch:

1. Adapter auswählen: Der Wizard erkennt den Adapter über den udev-Mount. Wählen Sie ihn aus oder geben Sie /dev/ttyACM0 ein (der Container-Pfad hinter dem Doppelpunkt in der Compose-Datei).
2. MQTT-Broker konfigurieren: Server-Adresse mqtt://mosquitto:1883 (Service-Name). Nicht localhost oder 127.0.0.1, die auf den Container selbst zeigen.
3. Netzwerkschlüssel: Zigbee2MQTT erzeugt einen zufälligen Schlüssel; übernehmen Sie ihn oder geben Sie einen eigenen ein.

Danach schreibt Zigbee2MQTT die Konfiguration nach /opt/zigbee2mqtt/data/configuration.yaml, das Dashboard ist verfügbar.

Verifizieren:

curl -I http://localhost:8080

Erwartete Antwort: HTTP/1.1 200 OK. Im Browser sehen Sie das Zigbee2MQTT-Dashboard mit der Gerätekarte und dem Menü. In den Logs bestätigt eine Zeile wie Connected to MQTT server die erfolgreiche Broker-Verbindung:

docker compose logs zigbee2mqtt | grep -i mqtt

Schritt 7: Gerät pairen

Zum Einbinden eines Geräts klicken Sie oben rechts im Dashboard auf Permit join (All). Das Netz bleibt 254 Sekunden offen und schließt sich dann automatisch.

Versetzen Sie das Gerät in den Pairing-Modus (meist langer Knopfdruck oder dreimal ein-/ausstecken). Es erscheint nach wenigen Sekunden in der Geräteliste mit Modellname, IEEE-Adresse und Datenpunkten (Temperatur, Helligkeit, An/Aus).

Verifizieren: Das neue Gerät erscheint in der Geräteliste unter dem erkannten Modellnamen. In den Logs erscheint eine Meldung mit „Successfully interviewed“ und der IEEE-Adresse des Geräts:

docker compose logs zigbee2mqtt | grep -i "successfully interviewed"

Schritt 8: Updates und Backup

Die Konfiguration in ./data/ bleibt beim Update erhalten. Sichern Sie den Ordner trotzdem vorher:

# Backup vor dem Update
cp -r /opt/zigbee2mqtt/data /opt/zigbee2mqtt/data_backup_$(date +%Y%m%d)

# Update durchführen
cd /opt/zigbee2mqtt
docker compose pull
docker compose up -d

Besonders wichtig für das Backup: Die Datei ./data/configuration.yaml enthält den Zigbee-Netzwerkschlüssel (network_key). Ohne diesen Schlüssel müssen Sie bei einer Migration auf neue Hardware alle Geräte neu pairen. Sichern Sie den ./data/-Ordner daher regelmäßig. Eine allgemeine Backup-Strategie finden Sie unter 3-2-1-Backup-Strategie umsetzen.

Verifizieren:

docker compose ps

Beide Services zeigen nach dem Update wieder Up. Die Versionsnummer im Dashboard unter Settings > About hat sich aktualisiert.

Troubleshooting / Typische Fehler

1. Veraltetes Image nach Update: Feste alte Version oder inoffizielle Quelle in der Compose-Datei. ghcr.io/koenkk/zigbee2mqtt mit gewünschter Version eintragen, dann docker compose pull und docker compose up -d.
2. Adapter nicht gefunden (/dev/serial/by-id/... No such file or directory): Der Symlink wird nicht automatisch in den Container übertragen. /run/udev:/run/udev:ro als Volume einbinden UND den korrekten by-id-Pfad im devices-Eintrag setzen. Alternativ /dev/ttyACM0 (weniger stabil nach Reboot).
3. Device-Pfad-Mismatch (cannot open port): serial.port in der configuration.yaml muss den Container-Pfad enthalten (hinter dem Doppelpunkt im devices-Eintrag, hier /dev/ttyACM0), nicht den Host-Pfad.
4. MQTT-Verbindung schlägt fehl (Connection refused): mqtt.server darf bei Mosquitto in Docker nicht auf localhost oder 127.0.0.1 zeigen; korrekt ist mqtt://mosquitto:1883. Mosquitto prüfen: docker compose ps mosquitto.
5. Berechtigungsfehler (Permission denied auf /dev/ttyACM0): Der Container-Benutzer hat keinen Zugriff auf das Gerät. Lösung: In der Compose-Datei user: "1000:1000" und group_add: [dialout] eintragen (UID/GID des Host-Benutzers, der Mitglied der Gruppe dialout ist).
6. Konfiguration wird nicht geladen (Portainer/Proxmox-Stacks): ./data/ wird manchmal als leeres Docker-Volume angelegt, bevor der Bind-Mount greift. Verzeichnis vorher mit mkdir -p ./data anlegen und Berechtigungen setzen.
7. Adapter hat nach einem Neustart eine andere Nummer (ttyACM1, ttyACM2 …): Auf dem Host den stabilen by-id-Pfad verwenden; im Container bleibt der Pfad über das Mapping /dev/ttyACM0.
8. Zigbee-Kanal-Kollision mit WLAN: Zigbee nutzt 2,4 GHz. Kanal 11 überlagert sich mit WLAN-Kanal 1, Kanal 15 mit WLAN-Kanal 3, Kanal 25 mit WLAN-Kanal 11. Im Frontend unter Settings > Network einen Kanal wählen, der nicht mit dem WLAN überlappt.
9. Container startet, aber kein Frontend erreichbar: Port 8080 belegt. Mit docker compose logs zigbee2mqtt prüfen, ob der Web-Server läuft, und ggf. auf einen freien Port wechseln (z. B. "18080:8080").

Häufige Fragen

Brauche ich zwingend Home Assistant?

Nein. Zigbee2MQTT kommuniziert nur per MQTT und funktioniert ebenso mit ioBroker, Node-RED, Domoticz, OpenHAB, Gladys oder eigenen MQTT-Anwendungen.

Welcher Zigbee-Adapter eignet sich?

USB-Dongles mit Texas-Instruments-Chips (CC2652P, z. B. Sonoff Zigbee 3.0 USB Dongle Plus) oder Silicon-Labs-Chips (EFR32MG21, z. B. SLZB-06). Beide Stacks (zStack, EmberZNet) unterstützen Coordinator-Backups für Migrationen. Von ZiGate wird abgeraten (nicht mehr gepflegt), ZBOSS (Nordic Semiconductor) gilt als experimentell.

Wie viele Geräte kann ein Zigbee-Netzwerk aufnehmen?

Ein Zigbee-Netzwerk ist ein Mesh-Netzwerk. Der Coordinator kann direkt 15–20 Direktverbindungen halten; netzbetriebene Geräte fungieren automatisch als Router und erweitern das Netz. In der Praxis sind 200+ Geräte realisierbar. Batteriebetriebene Geräte (Sensoren, Fernbedienungen) sind End-Nodes und routen nicht.

Muss ich Zigbee2MQTT neu starten, wenn ich ein neues Gerät pairen will?

Nein, über Permit join (All) im Web-Frontend (Schritt 6); der Pairing-Modus schließt sich nach dem Timeout automatisch.

Was passiert, wenn der MQTT-Broker nicht erreichbar ist?

Zigbee2MQTT läuft weiter, loggt die Fehler und verbindet sich automatisch neu. Gepaarte Geräte bleiben in devices.yaml erhalten und sind danach sofort verfügbar.

Wie sichere ich das Zigbee-Netzwerk am besten?

Ohne den Netzwerkschlüssel (network_key in ./data/configuration.yaml) müssen Sie bei einem Hardware-Wechsel alle Geräte neu pairen. Sichern Sie ./data/ regelmäßig extern; für zStack- und EmberZNet-Adapter gibt es zusätzlich Coordinator-Backups im Web-Frontend.

Funktioniert Zigbee2MQTT auch auf einem Synology NAS?

Ja, sofern das NAS den USB-Adapter erkennt und Docker-Support bietet. Die Einrichtung im Synology Container Manager folgt denselben Prinzipien – die Compose-Datei ist identisch. Den USB-Pfad ermitteln Sie per SSH auf dem NAS. Hinweise zur SSH-Aktivierung finden Sie unter SSH auf dem Synology NAS aktivieren.

Fazit

Ein USB-Adapter, ein Stack aus zwei Containern und ein einmaliges Onboarding genügen, um Zigbee-Geräte ohne Hersteller-Gateway und Cloud mit jeder MQTT-fähigen Plattform zu verbinden. Die Konfiguration liegt in ./data/, Updates kosten zwei Befehle, das Mesh wächst mit jedem netzbetriebenen Gerät.

Als nächsten Schritt empfiehlt sich die Integration mit Home Assistant mit Docker oder einem anderen MQTT-fähigen System Ihrer Wahl. Wer den Zigbee-Stack um einen Conbee/RaspBee-Adapter erweitern möchte, findet eine alternative Herangehensweise in der Phoscon-Anleitung mit deCONZ in Docker.

Weiterführende Anleitungen und Quellen

1. Home Assistant mit Docker: die lokale Smart-Home-Zentrale
2. Phoscon einrichten: Zigbee-Server mit deCONZ in Docker installieren
3. Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage
4. SSH auf dem Synology NAS aktivieren und verbinden
5. 3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud

Offizielle Quellen: Zigbee2MQTT Docker-Installationsdokumentation | GitHub-Repository koenkk/zigbee2mqtt | Getting-Started-Guide

Passende Anleitungen auf S-EDV

1. Automatische Sicherheitsupdates unter Debian/Ubuntu mit unattended-upgrades einrichten
2. Eclipse Mosquitto auf dem Synology NAS installieren: MQTT-Broker für das Smart Home