Smart-Home-Geräte mit dem Zigbee-Funkstandard – Lampen von IKEA Tradfri, Hue, Innr, Sensoren von Aqara, Bewegungsmelder von Philips – brauchen einen Zigbee-Coordinator, der das Funknetz aufspannt und die Geräte zentral verwaltet. deCONZ von dresden elektronik ist eine der bekanntesten Open-Source-Lösungen dafür, Phoscon ist die zugehörige Weboberfläche. Diese Anleitung zeigt Schritt für Schritt, wie sich deCONZ als Docker-Container auf einem Linux-Server, Raspberry Pi oder Mini-PC einrichten lässt – und wie das erste Zigbee-Gerät angemeldet wird.

Was ist deCONZ und was ist Phoscon?

deCONZ ist die Server-Software, die mit dem Zigbee-Coordinator-Stick kommuniziert, das Funknetz verwaltet und eine REST- sowie WebSocket-API bereitstellt. Phoscon ist die mitgelieferte Web-App, mit der sich Geräte anmelden, Räume anlegen und Szenen bauen lassen. Wer Home Assistant, ioBroker oder Node-RED einsetzt, nutzt typischerweise deCONZ im Hintergrund und steuert die Geräte aus der Smart-Home-Zentrale heraus – Phoscon dient dann nur noch zum Pairing und zur Diagnose.

Hardware-Voraussetzungen

Zigbee-Coordinator

deCONZ funktioniert ausschließlich mit Hardware von dresden elektronik:

ConBee II (USB-Stick) – der Klassiker, sehr stabil, ab etwa 40 EUR. Empfehlung für die meisten Setups.
ConBee III (USB-Stick) – die aktuelle Generation mit Zigbee 3.0, besseren Antennen und Thread-Unterstützung. Etwas teurer, dafür zukunftssicher.
RaspBee II (Raspberry-Pi-HAT) – Aufsteckmodul für den Raspi, spart einen USB-Port, braucht aber einen freien GPIO-Header.

USB-Verlängerungskabel (nicht optional!)

USB-3.0-Ports erzeugen elektromagnetische Störungen genau im Zigbee-Frequenzband (2,4 GHz). Steckt der ConBee direkt am Server, sinkt die Reichweite erheblich. Eine aktive USB-2.0-Verlängerung von ein bis zwei Metern löst das Problem zuverlässig und sollte fest eingeplant werden – das ist kein optionales Extra, sondern Pflicht.

Server-Hardware

deCONZ ist extrem genügsam:

Raspberry Pi 4 oder 5 reicht völlig.
Synology-NAS mit Container Manager.
Beliebiger Linux-Server (Debian, Ubuntu, Alma, etc.) mit Docker.
RAM-Bedarf: ca. 200 MB für den Container.

Schritt 1: Docker und Docker Compose prüfen

Per SSH auf den Zielserver verbinden und prüfen, ob Docker und Docker Compose installiert sind:

docker --version

docker compose version

Beide Befehle müssen eine Versionsnummer ausgeben. Fehlt Docker, kann es unter Debian/Ubuntu mit folgendem offiziellen Skript installiert werden:

curl -fsSL https://get.docker.com | sudo sh

Schritt 2: Datenordner anlegen

Der Container speichert Konfiguration, Datenbank und Firmware-Backups im Volume /opt/deCONZ. Diesen Pfad auf dem Host vorbereiten:

sudo mkdir -p /opt/deconz

sudo chown -R $(whoami):$(whoami) /opt/deconz

Auf einer Synology bietet sich stattdessen /volume1/docker/deconz an – analog zu anderen Container-Volumes.

Schritt 3: Coordinator anschließen und Geräte-Pfad finden

Den ConBee II oder ConBee III über die USB-Verlängerung an den Server anschließen. Anschließend per SSH prüfen, ob das Gerät erkannt wird:

lsusb | grep -i conbee

Die Ausgabe sollte eine Zeile mit dresden elektronik enthalten. Anschließend den stabilen Geräte-Pfad ermitteln – nur by-id-Pfade sind nach Reboot sicher gleich:

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

Den vollständigen Pfad notieren, er sieht ungefähr so aus:

/dev/serial/by-id/usb-dresden_elektronik_ingenieurtechnik_GmbH_ConBee_II_DE2521467-if00

Schritt 4: docker-compose.yml erstellen

In den vorbereiteten Ordner wechseln und eine docker-compose.yml mit folgendem Inhalt anlegen. Den Geräte-Pfad aus Schritt 3 einsetzen:

version: "3.7"

services:

deconz:

image: deconzcommunity/deconz:stable

container_name: deconz

restart: unless-stopped

ports:

- "8080:80"

- "8443:443"

devices:

- "/dev/serial/by-id/usb-dresden_elektronik_xxxxxx-if00:/dev/ttyACM0"

volumes:

- "./deconz-data:/opt/deCONZ"

- "/etc/localtime:/etc/localtime:ro"

environment:

- DECONZ_WEB_PORT=80

- DECONZ_WS_PORT=443

- DECONZ_DEVICE=/dev/ttyACM0

- TZ=Europe/Berlin

Wichtige Punkte zu dieser Konfiguration:

ports mappt das Phoscon-Web-UI auf Port 8080 (HTTP) und 8443 (HTTPS) auf dem Host. Wer Port 80 frei hat, kann auch direkt 80:80 nutzen.
devices reicht den ConBee-USB-Stick exakt durch – ohne diese Zeile findet deCONZ den Coordinator nicht.
volumes sichert alle Daten persistent. Ohne dieses Volume wären beim nächsten Container-Update alle Geräte-Pairings verloren.
TZ=Europe/Berlin sorgt für korrekte Zeitstempel in Logs und Automatisierungen.

Schritt 5: Container starten

Im selben Verzeichnis wie die docker-compose.yml:

docker compose up -d

Der erste Start lädt das Image (ca. 200 MB) und initialisiert die Datenbank. Mit docker compose logs -f deconz lässt sich der Start mitlesen – wenn die Zeile Started up at port 80 erscheint, ist das Web-UI bereit.

Schritt 6: Phoscon-Web-UI öffnen

Im Browser folgende Adresse aufrufen, SERVER-IP durch die lokale IP-Adresse des Servers ersetzen:

http://SERVER-IP:8080

Beim ersten Aufruf erkennt Phoscon das neue Gateway automatisch und bietet die Inbetriebnahme an.

Schritt 7: Admin-Konto und Gateway-Konfiguration

Im Setup-Assistenten folgende Schritte durchlaufen:

Phoscon-App als Anwendungstyp wählen.
Passwort festlegen – mindestens 12 Zeichen, dieses Konto verwaltet später die komplette Smart-Home-Zentrale.
Gateway-Name vergeben, z. B. SmartHome.
Standort für korrekte Sonnenauf-/-untergangszeiten setzen.

Schritt 8: Erstes Zigbee-Gerät anmelden

Phoscon trennt Geräte nach Kategorie: Lampen, Sensoren und Schalter. Beispiel: eine Philips-Hue-Lampe anmelden.

Im Menü links auf Lampen klicken und anschließend auf Neue Lampen hinzufügen.
Phoscon schaltet den Coordinator für 60 Sekunden in den Pairing-Modus.
Die Lampe in unmittelbarer Nähe des Coordinators stromlos schalten und sechsmal innerhalb von zwei Sekunden wieder ein- und ausschalten – das setzt die Lampe in den Reset- und Pairing-Modus. Bei IKEA Tradfri funktioniert das Pairing meist über sechsmal Ein-/Ausschalten oder mit einer Original-Fernbedienung.
Phoscon meldet die gefundene Lampe innerhalb weniger Sekunden in der Liste.
Einen aussagekräftigen Namen vergeben (z. B. Wohnzimmer Stehlampe) und mit Übernehmen bestätigen.

Anschließend ist die Lampe dimmbar, farbwählbar und über die Phoscon-App steuerbar.

Schritt 9: Gateway-Backup einrichten

Ohne Backup geht bei einem Defekt oder versehentlichen Reset die komplette Zigbee-Netzwerk-Konfiguration verloren – inklusive aller Pairings. Phoscon bietet dafür einen integrierten Export:

In Phoscon auf Einstellungen → Gateway → Backup.
Auf Backup herunterladen klicken, die .dat-Datei lokal speichern.

Diese Datei zusätzlich in den eigenen Backup-Job aufnehmen (Hyper Backup auf Synology, restic auf Linux, Veeam Agent unter Windows). Ergänzend lohnt sich, das gesamte Volume deconz-data regelmäßig wegzusichern – dort liegen Datenbank und Firmware-Backups parallel.

Bonus: REST-API für Home Assistant nutzen

Damit Home Assistant, ioBroker oder Node-RED auf die Geräte zugreifen können, wird ein API-Key benötigt. Dieser wird einmalig im Phoscon-Gateway erzeugt:

In Phoscon auf Einstellungen → Gateway → Erweitert.
Den Punkt App authentifizieren aktivieren – das Gateway öffnet ein 60-Sekunden-Zeitfenster.
Innerhalb dieser Zeit aus der zukünftigen Smart-Home-Zentrale (z. B. Home Assistant) den API-Key abrufen. Home Assistant erledigt das über die Integration deCONZ automatisch – einfach Gateway-IP und Port 8080 eintragen.

Sobald der Key gespeichert ist, übernimmt Home Assistant Lampen, Sensoren und Schalter automatisch und stellt sie als Entitäten bereit.

Troubleshooting

ConBee wird nicht erkannt: lsusb liefert keine Ausgabe → USB-Verlängerung defekt, USB-3.0-Port stört, oder der Benutzer braucht Rechte auf /dev/ttyACM0 (Gruppe dialout).
Container startet, Web-UI nicht erreichbar: Logs mit docker compose logs deconz prüfen. Häufig blockiert eine lokale Firewall Port 8080.
Geräte verschwinden zufällig: ConBee zu nah am Server, USB-3.0-Interferenz. Aktive USB-Verlängerung verwenden, idealerweise 1–2 Meter Abstand zum Server.
Pairing schlägt fehl: Das Gerät war vorher schon mit einem anderen Hub gepaart – vor dem Anlernen komplett zurücksetzen (Reset-Prozedur je Hersteller unterschiedlich).
Lange Funkstrecken: Zigbee ist ein Mesh. Routende Geräte wie netzbetriebene Lampen oder Steckdosen leiten Signale weiter. Wer nur batteriebetriebene Sensoren hat, sollte mindestens eine routende Lampe oder Steckdose im Zwischenraum platzieren.

Updates und Wartung

Updates des deCONZ-Containers laufen über folgende drei Befehle:

docker compose pull

docker compose up -d

docker image prune -f

Vor jedem Update das Gateway-Backup aus Schritt 9 erneuern. Die Firmware des Coordinators wird automatisch bei Bedarf aktualisiert; manuell anstoßen lässt sie sich über Einstellungen → Gateway → Firmware aktualisieren.

Fazit

Mit deCONZ und Phoscon entsteht in unter einer Stunde ein leistungsfähiger, lokal betriebener Zigbee-Server, der unabhängig von Cloud-Diensten und Hersteller-Hubs läuft. Der Container ist genügsam, die Hardware-Kosten halten sich mit ConBee II oder III in Grenzen, und über die REST-API ist die Anbindung an Home Assistant, ioBroker oder Node-RED Standard. Wer das Smart Home konsequent lokal betreiben möchte, fährt mit diesem Stack langfristig sehr gut.

Weitere praktische Anleitungen rund um Docker und Linux-Infrastruktur in den Kategorien Docker und Linux.

Quellen: Phoscon – ConBee II Installation, deCONZ REST-Plugin auf GitHub