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

Wer Zigbee-Geräte von Philips Hue, IKEA Trådfri, Aqara oder Tuya betreibt, kennt das Problem: Jede Marke verlangt ihre eigene Bridge, die Cloud-Anbindung ist Pflicht, und ein Ausfall beim Hersteller legt das halbe Smarthome lahm. Zigbee2MQTT durchbricht dieses Muster radikal. Die Open-Source-Bridge (15.200 GitHub-Stars, Version 2.12.0, Stand Juni 2026) verbindet über einen günstigen USB-Dongle für 10–20 EUR alle 5.473 unterstützten Geräte von 577 Herstellern direkt mit einem lokalen MQTT-Broker. Von dort aus sprechen Home Assistant, ioBroker, Node-RED, OpenHAB oder jede eigene Anwendung mit den Geräten – vollständig lokal, vollständig unter eigener Kontrolle.

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: Empfohlen sind Dongles auf Basis von Texas-Instruments-Chips (CC2652P, z. B. Sonoff Zigbee 3.0 USB Dongle Plus) oder Silicon-Labs-Chips (EFR32MG21). Preis: ca. 10–25 EUR. Adapter muss am Host eingesteckt sein.
3. Linux-Host mit USB-Port: x86_64-Server, Raspberry Pi 3/4/5, Mini-PC oder NAS mit Docker-Unterstützung
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

Bevor du die Compose-Datei schreibst, musst du wissen, unter welchem Gerätepfad dein USB-Dongle auf dem Host erreichbar ist. Stecke den Adapter ein und führe folgenden Befehl aus:

ls /dev/serial/by-id/

Die Ausgabe sieht in etwa so aus:

usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00

Notiere dir den vollständigen Pfad mit dem Präfix /dev/serial/by-id/. Dieser symbolische Link ist stabiler als /dev/ttyACM0, der sich nach einem Neustart ändern kann. Falls /dev/serial/by-id/ leer ist, prüfe mit lsusb, ob der Adapter überhaupt 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 des Stacks kommen in einen gemeinsamen Projektordner. Die persistenten Daten landen in Unterverzeichnissen, die Docker später als Bind-Mounts einbindet.

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

Mosquitto benötigt eine minimale Konfigurationsdatei, bevor der Container startet. Ohne diese Datei 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 solltest du MQTT-Authentifizierung einrichten – das übersteigt den Rahmen 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

Auch wenn Zigbee2MQTT nur wenige Pflicht-Umgebungsvariablen kennt, ist es sauber, die Zeitzone über eine .env-Datei zu steuern. Trägst du dort außerdem den Adapter-Pfad ein, musst du die Compose-Datei bei einem Hardware-Wechsel nicht anfassen.

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

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

Passe TZ an deine Zeitzone und ZIGBEE_ADAPTER_HOST an den im vorherigen Schritt ermittelten Pfad an.

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

Schritt 4: compose.yaml erstellen

Der Stack besteht aus zwei Services: Eclipse Mosquitto als MQTT-Broker und Zigbee2MQTT als Bridge. Beide laufen im selben Docker-Netzwerk z2m-net, sodass Zigbee2MQTT den Broker einfach unter dem Service-Namen mosquitto erreicht.

# /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)
      # Passe diesen Pfad auf deinen Adapter an!
      - ${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

Wichtig – nur ghcr.io: Das offizielle Image liegt ausschließlich auf der GitHub Container Registry. Viele ältere Anleitungen nennen noch koenkk/zigbee2mqtt (Docker Hub) – dieses Image wird nicht mehr gepflegt. Verwende immer ghcr.io/koenkk/zigbee2mqtt:latest.

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

Eckdaten auf einen Blick

Schritt 5: Stack starten

Starte den Stack aus dem Projektordner heraus:

cd /opt/zigbee2mqtt
docker compose up -d

Docker lädt beim ersten Start beide Images von den Registrierungen herunter. 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üfe die Logs beider Services auf Fehler:

docker compose logs mosquitto
docker compose logs zigbee2mqtt

Zigbee2MQTT sollte in den Logs keine Error- oder ENOENT-Meldungen zum Adapter zeigen. Falls der Onboarding-Wizard aktiv ist, erscheint eine Zeile wie Zigbee2MQTT started! oder ein Hinweis auf den Web-Server auf Port 8080.

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

Öffne deinen Browser und rufe das Web-Frontend auf:

http://<HOST-IP>:8080

Beim ersten Start erscheint der Onboarding-Wizard. Er führt dich durch folgende Schritte:

1. Adapter auswählen: Der Wizard erkennt den eingebundenen USB-Adapter automatisch über den udev-Mount. Wähle den erkannten Adapter aus der Liste oder gib den Pfad /dev/ttyACM0 manuell ein (das ist der interne Container-Pfad, den du in der Compose-Datei hinter dem Doppelpunkt definiert hast).
2. MQTT-Broker konfigurieren: Trage als Server-Adresse mqtt://mosquitto:1883 ein – das ist der Service-Name aus der Compose-Datei. Nicht localhost oder 127.0.0.1, da sich diese Adressen auf den Container selbst beziehen.
3. Netzwerkschlüssel: Zigbee2MQTT generiert beim ersten Start automatisch einen zufälligen Netzwerkschlüssel. Du kannst ihn übernehmen oder einen eigenen eingeben.

Nach dem Abschluss des Wizards schreibt Zigbee2MQTT die Konfiguration in /opt/zigbee2mqtt/data/configuration.yaml. Ab jetzt ist das Dashboard verfügbar.

Verifizieren:

curl -I http://localhost:8080

Erwartete Antwort: HTTP/1.1 200 OK. Im Browser siehst du 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

Um ein neues Zigbee-Gerät einzubinden, aktiviere im Dashboard den Pairing-Modus: Navigiere zu Settings > Permit join (all) oder klicke oben rechts auf das Steckersymbol. Der Modus ist standardmäßig auf 255 Sekunden begrenzt, um das Netzwerk nicht dauerhaft offen zu lassen.

Versetze dein Gerät in den Pairing-Modus (gerätespezifisch: meist langen Knopfdruck halten oder Stecker dreimal ein-/ausstecken). Nach wenigen Sekunden erscheint das Gerät in der Geräteliste des Dashboards mit seinem Modellnamen, der IEEE-Adresse und allen verfügbaren Datenpunkten (Temperatur, Helligkeit, An/Aus etc.).

Verifizieren: Das neue Gerät erscheint in der Geräteliste unter dem erkannten Modellnamen. In den Logs erscheint eine Zeile wie:

docker compose logs -f zigbee2mqtt
Zigbee2MQTT:info  2026-06-11 10:23:45: Successfully interviewed '0x00158d0001234567', device has successfully been paired

Schritt 8: Updates und Backup

Updates spielst du ein, ohne Daten zu verlieren – alle Konfigurationsdateien liegen in ./data/ und bleiben beim Update unangetastet. Sichere dennoch den Ordner 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 musst du bei einer Migration auf neue Hardware alle Geräte neu pairen. Sichere den ./data/-Ordner daher regelmäßig – eine allgemeine Backup-Strategie findest du 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. Falsches Image (koenkk/zigbee2mqtt von Docker Hub): Das Docker-Hub-Image wird nicht mehr gepflegt. Verwende ausschließlich ghcr.io/koenkk/zigbee2mqtt. Falls du das alte Image verwendest, ziehe es mit docker compose pull neu, nachdem du das Image in der Compose-Datei korrigiert hast.
2. Adapter nicht gefunden (/dev/serial/by-id/... No such file or directory): Der Symlink in /dev/serial/by-id/ wird nicht automatisch in den Container übertragen. Stelle sicher, dass /run/udev:/run/udev:ro als Volume eingebunden ist UND der korrekte by-id-Pfad im devices-Eintrag steht. Alternativ: Direkt /dev/ttyACM0 verwenden (weniger stabil nach Reboot).
3. Device-Pfad-Mismatch (cannot open port): Der Pfad im devices-Eintrag der Compose-Datei (vor dem Doppelpunkt, also der Host-Pfad) muss dem in serial.port in der configuration.yaml entsprechen. Nach dem Onboarding-Wizard stimmt das normalerweise überein; bei manueller Konfiguration aber leicht zu verwechseln.
4. MQTT-Verbindung schlägt fehl (Connection refused): Wenn Mosquitto ebenfalls in Docker läuft, darf mqtt.server in der configuration.yaml nicht auf localhost oder 127.0.0.1 zeigen. Korrekt ist mqtt://mosquitto:1883 (Service-Name aus der Compose-Datei). Prüfe außerdem, ob Mosquitto wirklich läuft: 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): In manchen Umgebungen wird ./data/ als leeres Docker-Volume angelegt, bevor der Bind-Mount greift. Lösung: Verzeichnis manuell anlegen (mkdir -p ./data) und Berechtigungen setzen, bevor docker compose up läuft.
7. ttyACM2+ funktioniert nicht: Docker unterstützt nur /dev/ttyACM0 und /dev/ttyACM1 zuverlässig. Bei höheren Nummern: udev-Regel anlegen, die den Adapter immer auf ttyACM0 mappt, oder den stabilen by-id-Pfad verwenden.
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: Falls Port 8080 bereits belegt ist, schlägt das Binding still fehl. Prüfe mit docker compose logs zigbee2mqtt, ob der Web-Server gestartet ist, und ändere in Compose ggf. auf einen freien Port (z. B. "18080:8080").

Häufige Fragen

Brauche ich zwingend Home Assistant?

Nein. Zigbee2MQTT ist vollständig plattformneutral und kommuniziert ausschließlich per MQTT. Die Bridge funktioniert genauso gut mit ioBroker, Node-RED, Domoticz, OpenHAB, Gladys oder jeder eigenen Anwendung, die MQTT lesen kann. Home Assistant ist nur eine von vielen Möglichkeiten.

Welchen Zigbee-Adapter soll ich kaufen?

Empfohlen sind USB-Dongles auf Basis von Texas-Instruments-Chips (CC2652P, z. B. Sonoff Zigbee 3.0 USB Dongle Plus) oder Silicon-Labs-Chips (EFR32MG21, z. B. SLZB-06). Beide Protokoll-Stacks (zStack und EmberZNet) unterstützen Coordinator-Backups – wichtig für Migrationen. Preis: ca. 10–20 EUR. Von ZiGate-basierten Adaptern wird abgeraten (nicht mehr aktiv 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. Das Pairing aktivierst du direkt im Web-Frontend über Settings > Permit join, ohne den Container neu zu starten. Der Pairing-Modus schließt sich nach dem konfigurierten Timeout automatisch.

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

Zigbee2MQTT startet weiterhin und loggt die Verbindungsfehler. Es versucht automatisch, die Verbindung zum Broker wiederherzustellen. Bereits gepaarte Geräte bleiben in der lokalen Datenbank (devices.yaml) erhalten und sind nach dem Wiederverbinden sofort wieder verfügbar.

Wie sichere ich das Zigbee-Netzwerk am besten?

Der Netzwerkschlüssel (network_key in ./data/configuration.yaml) ist das Herzstück deines Zigbee-Netzes. Ohne ihn musst du bei einem Hardware-Wechsel alle Geräte neu pairen. Sichere den gesamten ./data/-Ordner regelmäßig extern. Für zStack- und EmberZNet-basierte Adapter unterstützt Zigbee2MQTT zusätzlich Coordinator-Backups über das 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 ermittelst du per SSH auf dem NAS. Hinweise zur SSH-Aktivierung findest du unter SSH auf dem Synology NAS aktivieren.

Fazit

Zigbee2MQTT ist die überzeugendste Lösung, um sich von Hersteller-Gateways und Cloud-Abhängigkeiten zu befreien. Mit einem einzigen günstigen USB-Adapter, einem Docker-Stack aus zwei Containern und einem einmaligen Onboarding im Browser verbindest du über 5.400 Geräte von 577 Herstellern mit jeder MQTT-fähigen Plattform. Die Konfiguration liegt vollständig in deinem ./data/-Ordner, Updates kosten zwei Befehle, und das Mesh-Netzwerk skaliert problemlos auf Hunderte von Geräten. Wer einen zuverlässigen Zigbee-Coordinator-Adapter auf Basis von Texas-Instruments- oder Silicon-Labs-Chips wählt, hat eine stabile Grundlage für ein vollständig lokales Smarthome – ohne monatliche Abogebühren und ohne Vendor-Lock-in.

Als nächsten Schritt empfiehlt sich die Integration mit Home Assistant mit Docker oder einem anderen MQTT-fähigen System deiner 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. OpenSSL: Neun Schwachstellen im Sicherheitsrelease vom 9. Juni 2026, darunter Hi
2. Automatische Sicherheitsupdates unter Debian/Ubuntu mit unattended-upgrades rich
3. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden