ioBroker ist seit 2014 die bevorzugte Smart-Home-Integrationsplattform im deutschsprachigen Raum. Während Home Assistant mit seiner internationalen Community punktet, überzeugt ioBroker durch überragende Unterstützung für Homematic, KNX, Busch-Jaeger und andere in Deutschland verbreitete Protokolle – ergänzt durch flexible JavaScript- und Blockly-Automatisierungen. Das offizielle Docker-Image, gepflegt von Maintainer „buanet" in Zusammenarbeit mit der ioBroker GmbH, lässt sich auf jedem Synology NAS mit Intel/AMD- oder ARM64-CPU als sauber strukturiertes Compose-Projekt betreiben. Diese Anleitung führt dich vom leeren NAS bis zur laufenden Admin-Oberfläche – und zeigt nach jedem Schritt, wie du den Erfolg verifizierst, bevor du weitermachst.

Voraussetzungen

Synology NAS mit DSM 7.2 oder neuer und installiertem Container Manager (aus dem Package Center)
CPU-Architektur: Intel/AMD (amd64) oder ARM64 – arm32v7 wird ab buanet/iobroker v11.0.2 nicht mehr unterstützt
Mindestens 2 GB freier RAM (ioBroker selbst benötigt 200–500 MB; jeder Adapter addiert weitere 50–200 MB)
Mindestens 5 GB freier Speicherplatz auf dem Docker-Volume
SSH-Zugang zum NAS (zum Ermitteln von UID/GID und zur Log-Beobachtung) – Einrichtung: SSH auf dem Synology NAS aktivieren und verbinden
Internetzugang beim Erststart (Adapter-Download; Standard: OFFLINE_MODE=false)

Schritt 1: UID und GID deines Synology-Benutzers ermitteln

ioBroker-Prozesse laufen im Container unter der in SETUID/SETGID konfigurierten Benutzer-ID. Stimmen diese Werte nicht mit dem Eigentümer des gemounteten Volumes überein, verweigert ioBroker das Schreiben von Daten – ein häufiger und schwer zu diagnostizierender Fehler. Verbinde dich per SSH mit deinem NAS und führe folgenden Befehl aus:

id deinbenutzername

Die Ausgabe sieht in etwa so aus:

uid=1026(deinbenutzername) gid=100(users) groups=100(users),101(administrators)

Notiere uid und gid – du brauchst sie im nächsten Schritt als Werte für SETUID und SETGID. Auf Synology hat der erste angelegte Benutzer typischerweise UID 1026 und GID 100.

Verifizieren: Der Befehl gibt eine Zeile mit uid=, gid= und groups= zurück. Liefert er einen Fehler wie no such user, hast du den falschen Benutzernamen angegeben – prüfe ihn in der DSM-Benutzerverwaltung.

Schritt 2: Compose-Projekt im Container Manager anlegen

Der sauberste Weg auf Synology ist ein Container-Manager-Projekt mit einer compose.yaml. Wie du ein neues Projekt anlegst, erklärt die Grundanleitung Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren. Wähle als Projektname iobroker und hinterlege folgende Compose-Konfiguration:

services:
  iobroker:
    image: buanet/iobroker:latest-v11
    container_name: iobroker
    hostname: iobroker
    restart: always
    ports:
      - "8081:8081"
    volumes:
      - iobrokerdata:/opt/iobroker
    environment:
      - TZ=Europe/Berlin
      - LANG=de_DE.UTF-8
      - LANGUAGE=de_DE:de
      - LC_ALL=de_DE.UTF-8
      - SETUID=1026
      - SETGID=100

volumes:
  iobrokerdata:

Passe SETUID und SETGID auf die in Schritt 1 ermittelten Werte an. Das Named Volume iobrokerdata wird von Docker automatisch angelegt und ist beim ersten Start garantiert leer – eine wichtige Voraussetzung für die korrekte ioBroker-Initialisierung.

Warum Named Volume statt Bind Mount?

Named Docker Volumes werden ohne noexec-Flag angelegt. Synology-Bind-Mounts auf /volume1/… können dieses Flag tragen, was die ioBroker-Installation still zum Scheitern bringt, weil der Prozess ausführbaren Code (Node-Module, Skripte) unter /opt/iobroker ablegen muss. Named Volumes umgehen dieses Problem zuverlässig. Mehr zu Volumes und Berechtigungen: Docker-Ordner und Berechtigungen auf dem Synology NAS.

Image-Tag: Warum `latest-v11` statt `latest`?

Der Tag latest wechselt bei neuen Major Releases automatisch die Node.js-Basis-Version. Wer Watchtower oder automatische Neustarts einsetzt, kann so unbeabsichtigt von Node 22 auf eine zukünftige Version springen und Breaking Changes in Adaptern auslösen. Der Tag latest-v11 rollt nur innerhalb der Major Version v11 und ist die offizielle Produktionsempfehlung von buanet. Alternativ kannst du auf buanet/iobroker:v11.1.0 pinnen (Stand: Juni 2026).

Verifizieren: Nachdem du das Projekt im Container Manager angelegt hast, erscheint es in der Projektliste mit dem Status Wird ausgeführt. Der Container iobroker sollte grün markiert sein. Ist der Status Fehler oder Beendet, prüfe zunächst die Logs (Schritt 3).

Schritt 3: Erststart überwachen und Admin-Oberfläche aufrufen

Der erste Start dauert typischerweise 3–5 Minuten: Das Entrypoint-Script installiert ioBroker, lädt Kern-Adapter herunter und startet den Admin-Dienst. Verbinde dich per SSH und beobachte die Logs in Echtzeit:

docker logs iobroker --follow

Du siehst zunächst Installationsschritte; der entscheidende Hinweis lautet:

ioBroker started
host.iobroker ... admin ... started on port 8081

Erst wenn diese Zeilen erscheinen, öffne im Browser:

http://[NAS-IP]:8081

Beim allerersten Aufruf startet ein kurzer Einrichtungsassistent, der Sprache, Netzwerk und optionale Cloud-Registrierung abfragt.

Verifizieren: Die Admin-Oberfläche lädt vollständig und zeigt das ioBroker-Dashboard mit Systemstatus. Erscheint stattdessen „Verbindung abgelehnt" oder eine leere Seite, laufen die Logs noch – warte weitere 1–2 Minuten und lade neu. Erscheinen in den Logs Fehlermeldungen mit EACCES oder permission denied, stimmen SETUID/SETGID nicht mit den Volume-Eigentümerrechten überein (siehe Troubleshooting).

Schritt 4: Firewall-Port freigeben

Synologys eingebaute Firewall blockiert neue Ports standardmäßig. Wie du Port 8081 (TCP) in der DSM-Firewall freigibst, beschreibt die Grundanleitung DSM-Firewall: Ports für Docker-Container freigeben.

Verifizieren: Rufe die Admin-Oberfläche von einem anderen Gerät im Netzwerk auf (nicht vom NAS selbst). Lädt sie korrekt, ist die Firewallregel aktiv. Schlägt der Aufruf fehl, obwohl der Container läuft, fehlt die Freigabe oder du verwendest die falsche IP-Adresse des NAS.

Schritt 5: Ersten Geräte-Adapter installieren und verifizieren

In der Admin-Oberfläche navigierst du zu Adapter und suchst nach dem gewünschten Protokoll. Für den DACH-Raum besonders relevant:

Adapter	Protokoll / Gerät	Empfohlene Architektur auf Synology
zigbee2mqtt (via MQTT)	Zigbee (Philips Hue, IKEA, Sonoff …)	Separater Zigbee2MQTT-Container + MQTT-Adapter
mqtt-client / mqtt-broker	MQTT-Geräte (Shelly, Tasmota …)	Externer Mosquitto-Container empfohlen
hm-rpc / hm-rega	Homematic IP / CCU	Bridge-Netzwerk, direkte IP-Verbindung zur CCU
knx	KNX-Bus (Busch-Jaeger, Gira …)	Bridge-Netzwerk mit IP-Interface
yahka	HomeKit (Apple-Integration)	Host-Netzwerk (mDNS erforderlich)

Für ein typisches MQTT-Setup mit Shelly-Geräten: Installiere zuerst einen externen Mosquitto-Broker (Anleitung: Eclipse Mosquitto auf dem Synology NAS installieren), dann den ioBroker-MQTT-Client-Adapter und verbinde ihn mit dem Mosquitto-Container über dessen internen Hostnamen im selben Docker-Netzwerk.

Nach der Adapter-Installation klicke auf Instanz anlegen. Die neue Instanz erscheint unter Instanzen mit dem Status grünes Häkchen, sobald die Verbindung steht.

Verifizieren: Unter Instanzen zeigt der frisch installierte Adapter ein grünes Symbol. Unter Objekte tauchen erste Datenpunkte des verbundenen Geräts auf. Im Adapter-Log (Instanzen → Zahnrad → Log) darf keine connection refused- oder authentication failed-Meldung erscheinen.

Eckdaten auf einen Blick

Parameter	Wert	Hinweis
Image	`buanet/iobroker:latest-v11`	Produktions-Tag; alternativ `v11.1.0` gepinnt
GHCR-Mirror	`ghcr.io/buanet/iobroker:latest-v11`	Identischer Inhalt, alternative Registry
Architekturen	amd64, arm64v8	arm32v7 ab v11.0.2 eingestellt
Admin-Port	8081	Änderbar via `IOB_ADMINPORT`
Volume-Pfad	`/opt/iobroker`	Beim Erststart leer; kein `noexec`-Flag
Basis-Image	Debian 12 Bookworm slim, Node.js 22	Stand: v11.1.0 (05.02.2026)

Umgebungsvariable	Beispielwert	Bedeutung
`TZ`	`Europe/Berlin`	Zeitzone (Pflicht; auch: Vienna, Zurich)
`LANG`	`de_DE.UTF-8`	Spracheinstellung (Pflicht laut Doku)
`LANGUAGE`	`de_DE:de`	Sprachpräferenz (Pflicht laut Doku)
`LC_ALL`	`de_DE.UTF-8`	Locale (Pflicht laut Doku)
`SETUID`	`1026`	UID des Container-Prozessbenutzers (Pflicht)
`SETGID`	`100`	GID des Container-Prozessbenutzers (Pflicht)
`IOB_ADMINPORT`	`8081`	Admin-Port (optional; Standard 8081)
`IOB_OBJECTSDB_TYPE`	`jsonl`	Objekt-Datenbank (optional; Standard jsonl)
`IOB_STATESDB_TYPE`	`jsonl`	States-Datenbank (optional; Standard jsonl)
`PERMISSION_CHECK`	`true`	Berechtigungskorrektur beim Start (empfohlen)
`DEBUG`	`false`	Erweitertes Logging (nur zur Fehlersuche)
`AVAHI`	`false`	Avahi-Daemon für HomeKit/yahka-Adapter

Host-Netzwerk vs. Bridge: die richtige Wahl treffen

Die Frage nach dem Netzwerkmodus entscheidet über Komfort und Stabilität. Für die meisten DACH-Installationen mit MQTT-Geräten (Shelly, Tasmota) und Zigbee2MQTT als separatem Container reicht Bridge-Netzwerk mit explizitem Port-Mapping vollständig aus.

Host-Netzwerk (network_mode: host) ist sinnvoll, wenn Adapter Multicast, Broadcast oder mDNS direkt benötigen – konkret beim yahka-Adapter für HomeKit, bei Philips-Hue-Auto-Discovery oder UPnP-basierten Geräten. Im Host-Modus entfällt die ports-Sektion in der Compose-Datei; alle Container-Ports liegen direkt auf dem NAS-Host. Der Nachteil: Port 8081 oder andere ioBroker-Ports können mit laufenden Synology-Diensten kollidieren. Lösung: IOB_ADMINPORT auf einen freien Port (z. B. 8091) setzen.

Empfehlung für neue Installationen: Mit Bridge starten, auf Host wechseln, sobald ein konkreter Adapter es erfordert. Node-RED als visueller Flow-Editor für ioBroker-Automatisierungen lässt sich ebenfalls auf der Synology als separater Container betreiben – die Anleitung dazu: Node-RED auf dem Synology NAS installieren.

Troubleshooting / Typische Fehler

„EACCES: permission denied" in den Logs: SETUID oder SETGID stimmt nicht mit dem Eigentümer des Volumes überein. id deinbenutzername erneut ausführen, Werte in der Compose-Datei korrigieren, Container neu starten. Bei Named Volumes: docker volume rm iobrokerdata (nur wenn noch keine Daten vorhanden), danach neu anlegen lassen.
Admin-Oberfläche nicht erreichbar nach dem Start: Der Erststart dauert 3–5 Minuten. docker logs iobroker --follow zeigt den Fortschritt. Erst wenn „Admin adapter started on port 8081" erscheint, ist die Oberfläche zugänglich.
Leere Seite oder Verbindungsfehler unter Port 8081: ioBroker läuft noch nicht vollständig durch. Alternativursache: Reverse Proxy leitet auf den falschen internen Port weiter – Proxy-Konfiguration prüfen.
Volume nicht leer beim Erststart: Das Volume iobrokerdata enthält Reste einer früheren Installation. Container stoppen, Volume löschen (docker volume rm iobrokerdata), neu starten. Achtung: dabei gehen alle ioBroker-Daten verloren – vorher sichern.
Port 8081 bereits belegt (Host-Netzwerk-Modus): Ein anderer Synology-Dienst nutzt diesen Port. IOB_ADMINPORT=8091 in der Compose-Datei ergänzen und den Container neu erstellen.
Image-Pull schlägt fehl (arm/v7): Auf älteren ARM-NAS mit 32-Bit-CPU steht kein v11.x-Image zur Verfügung. Der letzte unterstützte Tag für arm/v7 ist buanet/iobroker:v11.0.1.
Firewall blockiert Port 8081: In der DSM-Systemsteuerung unter Sicherheit → Firewall die Regel für Port 8081 TCP ergänzen.
Adapter bricht nach Update ab: Major-Version-Wechsel (z. B. v10 → v11) kann Adapter-Inkompatibilitäten verursachen. Vor jedem manuellen Image-Update: Backup via BackItUp-Adapter erstellen, js-controller und alle Adapter auf neuesten Stand bringen.

Häufige Fragen

Welchen Netzwerkmodus soll ich für ioBroker auf Synology wählen?

Für die meisten DACH-Setups mit MQTT-Geräten und Zigbee2MQTT als separatem Container reicht Bridge-Netzwerk mit "8081:8081". Host-Netzwerk (network_mode: host) brauchst du nur, wenn ein Adapter Multicast, Broadcast oder mDNS direkt nutzt – etwa der yahka-Adapter für HomeKit, Philips-Hue-Auto-Discovery oder UPnP-Geräte. Im Zweifelsfall: mit Bridge beginnen und bei Bedarf wechseln.

Wie lange dauert der Erststart und woran erkenne ich, dass ioBroker bereit ist?

Die erste Initialisierung dauert typischerweise 3–5 Minuten. Verifizierung per SSH: docker logs iobroker --follow. Erfolgreich gestartet ist ioBroker, wenn in den Logs „ioBroker started" und „host.iobroker … admin … started on port 8081" erscheinen. Erst danach http://[NAS-IP]:8081 aufrufen.

Kann ioBroker parallel zu Home Assistant auf demselben NAS laufen?

Ja, beide laufen als vollständig unabhängige Docker-Container. Port-Konflikte vermeiden: Home Assistant nutzt Port 8123, ioBroker Port 8081. Empfehlung für Parallelbetrieb: beide Systeme über einen gemeinsamen MQTT-Broker (Mosquitto) verbinden, sodass Gerätedaten in beiden Plattformen sichtbar sind. Viele DACH-Nutzer betreiben Home Assistant für das moderne UI und ioBroker für Homematic/KNX-Automatisierungen gleichzeitig.

Was ist der Unterschied zwischen ioBroker und Home Assistant auf Synology?

Home Assistant bietet eine breitere internationale Community, ein moderneres UI/UX ab Werk und ein großes Ökosystem an Integrationen. ioBroker punktet mit tieferer Homematic-, KNX- und Busch-Jaeger-Unterstützung, flexibleren JavaScript-Skripten (JS/Blockly statt Python) und der riesigen deutschsprachigen Community auf forum.iobroker.net. Für reine Shelly- oder Tasmota-Setups sind beide gleichwertig; bei klassischer DACH-Hausautomation mit Homematic oder KNX hat ioBroker die Nase vorn.

Wie erstelle ich ein Backup und wie stelle ich es wieder her?

Der BackItUp-Adapter (iobroker.backitup) bietet automatisierte Sicherungen auf NAS-Freigaben, FTP oder Cloud und lässt sich direkt über die Admin-Oberfläche konfigurieren. Für ein manuelles Backup genügt es, das Named Volume zu sichern, während der Container gestoppt ist: docker stop iobroker, dann das Volume-Verzeichnis (auffindbar mit docker volume inspect iobrokerdata) komprimieren. Zur Wiederherstellung: neuen Container mit leerem Volume starten, Backup via Admin-Oberfläche oder ioBroker-CLI einspielen.

Wann sollte ich Redis statt jsonl als Datenbank-Backend wählen?

Das Standard-Backend jsonl reicht für die meisten Heiminstallationen mit einigen hundert Datenpunkten völlig aus. Redis (IOB_OBJECTSDB_TYPE=redis und IOB_STATESDB_TYPE=redis) verbessert die Performance spürbar bei großen Installationen mit vielen tausend Datenpunkten – erfordert aber einen zusätzlichen Redis-Container. Für den Einstieg: bei jsonl bleiben und bei Bedarf später migrieren.

Fazit

ioBroker auf dem Synology NAS als Compose-Projekt zu betreiben ist in weniger als 30 Minuten erledigt – vorausgesetzt, SETUID/SETGID stimmen und das Volume ist beim Erststart leer. Das offizielle buanet-Image mit dem Tag latest-v11 ist stabil, gut dokumentiert und schützt dich vor ungewollten Breaking Changes durch automatische Updates. Die Named-Volume-Variante ist der robustere Weg gegenüber Bind Mounts, weil sie das lästige noexec-Problem auf Synology-Volumes von vornherein ausschließt. Wer im DACH-Raum Homematic, KNX oder Busch-Jaeger-Geräte betreibt, findet in ioBroker eine Plattform, die für diese Protokolle optimiert ist und von einer riesigen deutschsprachigen Community auf forum.iobroker.net unterstützt wird.

Weiterführende Anleitungen und Quellen

Eclipse Mosquitto auf dem Synology NAS installieren: MQTT-Broker für das Smart Home – externer Broker für Shelly, Tasmota und Zigbee2MQTT
Node-RED auf dem Synology NAS installieren: Automatisierung per Flow-Editor – visueller Flow-Editor als Ergänzung zu ioBroker
Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren – Grundanleitung für alle Compose-Projekte
Docker-Ordner und Berechtigungen auf dem Synology NAS: PUID und PGID – vertiefte Erklärung zu Benutzerrechten

Offizielle Dokumentation und weiterführende Quellen: buanet ioBroker Docker Image Docs (primäre Referenz für alle ENV-Variablen und Volume-Hinweise) sowie buanet/iobroker auf Docker Hub (Image-Tags, Architekturen, Release-Übersicht).