ioBroker ist seit 2014 eine verbreitete Smart-Home-Integrationsplattform im deutschsprachigen Raum. Im Vergleich zu Home Assistant bietet ioBroker starke Unterstützung für Homematic, KNX, Busch-Jaeger und andere in Deutschland verbreitete Protokolle, ergänzt durch JavaScript- und Blockly-Automatisierungen. Das offizielle Docker-Image, gepflegt vom Maintainer „buanet“ in Zusammenarbeit mit der ioBroker GmbH, läuft auf jedem Synology NAS mit Intel/AMD- oder ARM64-CPU als Compose-Projekt. Diese Anleitung führt Sie bis zur laufenden Admin-Oberfläche.

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.1.0 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 (nötig, weil DSM die numerische UID/GID nicht anzeigt; außerdem für die Log-Beobachtung). Einrichtung: SSH auf dem Synology NAS aktivieren und verbinden
Internetzugang beim Erststart (Adapter-Download; Standard: OFFLINE_MODE=false)

Hardware für diese Anleitung

Enthält Werbelinks

Synology mit Container Manager	Container laufen nur auf Modellen mit Container Manager, vor allem der Plus-Serie. Vor dem Kauf die Kompatibilitätsliste von Synology prüfen. Bei uns läuft eine DS920+.	Synology bei Amazon (Werbelink)
NAS-Festplatten	Für den Dauerbetrieb Platten mit CMR-Technik wählen, für RAID 1 zwei gleich große.	NAS-Platten bei Amazon (Werbelink)
RAM-Erweiterung	Mehrere Container gleichzeitig brauchen Speicher. Viele Plus-Modelle lassen sich aufrüsten, das passende Modul steht im Datenblatt.	Bei Amazon ansehen (Werbelink)

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: UID und GID Ihres 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. Führen Sie per SSH auf dem NAS aus:

id BENUTZERNAME

Die Ausgabe sieht in etwa so aus:

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

Notieren Sie uid und gid für SETUID und SETGID in Schritt 2. 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, ist der Benutzername falsch; prüfen Sie ihn in der DSM-Benutzerverwaltung.

Schritt 2: Compose-Projekt im Container Manager anlegen

Wie Sie ein Container-Manager-Projekt mit einer compose.yaml anlegen, erklärt die Grundanleitung Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren. Wählen Sie als Projektname iobroker und hinterlegen Sie folgende Compose-Konfiguration:

services:
  iobroker:
    image: buanet/iobroker:latest-v12
    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:

Passen Sie SETUID und SETGID auf die in Schritt 1 ermittelten Werte an (ohne Angabe gilt 1000). Docker legt das Named Volume iobrokerdata automatisch und leer an, wie es die ioBroker-Initialisierung voraussetzt.

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; buanet nutzt sie auch im offiziellen Compose-Beispiel. Mehr zu Volumes und Berechtigungen: Docker-Ordner und Berechtigungen auf dem Synology NAS.

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

Der Tag latest wechselt bei neuen Major Releases automatisch die Node.js-Basis-Version. Mit Watchtower oder automatischen Updates springt der Container so unbeabsichtigt auf die nächste Major-Version. v12 (Debian 13, Node.js 24) ist seit dem 04.10.2026 die aktuelle Hauptversion, auf die latest inzwischen zeigt. Der Tag latest-v12 bleibt innerhalb von v12 und ist die Produktionsempfehlung von buanet. Alternativ können Sie auf buanet/iobroker:v12.0.0 festlegen (Stand: September 2026).

Verifizieren: Nach dem Anlegen 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üfen Sie zunächst die Logs (Schritt 3).

Update von v11 auf v12 (Bestandsinstallation)

Mit v12 wechselt das Basis-Image von Debian 12 (Bookworm) auf Debian 13 (Trixie). Der Hersteller empfiehlt für einen Wechsel der Major-Version ausdrücklich ein Backup und aktuelle Stände von js-controller und Adaptern; am sichersten ist eine frische Installation mit Wiederherstellung des Backups. Ein Update durch Neuerstellen des Containers ist ebenfalls möglich. Gehen Sie so vor:

Erstellen Sie mit dem BackItUp-Adapter ein Backup und laden Sie es außerhalb des NAS herunter.
Aktualisieren Sie js-controller und alle Adapter auf den neuesten stabilen Stand.
Ändern Sie im Compose-Projekt den Tag von latest-v11 auf latest-v12 und lassen Sie das Projekt im Container Manager neu erstellen. Das Named Volume iobrokerdata bleibt dabei erhalten.

Verifizieren: Im Test lief ein Stack mit latest-v11 und einem zusätzlich installierten Adapter. Nach dem Tausch auf latest-v12 antwortete die Admin-Oberfläche auf Port 8081 wieder mit 200, cat /etc/os-release im Container zeigte Debian 13 (Trixie), und iobroker list instances führte admin, backitup, discovery und den nachinstallierten Adapter unverändert auf. Einzelne Adapter benötigen nach einem Node-Wechsel mitunter eine Neuinstallation (iobroker rebuild bzw. Adapter im Admin neu installieren).

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

Der erste Start dauert 3–5 Minuten: Das Entrypoint-Script installiert ioBroker, lädt Kern-Adapter herunter und startet den Admin-Dienst. Beobachten Sie die Logs per SSH in Echtzeit (alternativ im Container Manager unter Protokoll):

docker logs iobroker --follow

Sobald der Log den Start des Hosts und des Admin-Adapters auf Port 8081 meldet, öffnen Sie im Browser:

http://[NAS-IP]:8081

Beim ersten Aufruf fragt ein Einrichtungsassistent Sprache, Netzwerk und optionale Cloud-Registrierung ab.

Verifizieren: Die Admin-Oberfläche lädt vollständig und zeigt das ioBroker-Dashboard mit Systemstatus. Erscheint stattdessen „Verbindung abgelehnt“ oder eine leere Seite, läuft die Installation noch; warten Sie 1 bis 2 Minuten und laden Sie 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

Eine aktive DSM-Firewall blockiert neue Ports. Wie Sie Port 8081 (TCP) freigeben, beschreibt die Grundanleitung DSM-Firewall: Ports für Docker-Container freigeben.

Verifizieren: Rufen Sie die Admin-Oberfläche von einem anderen Gerät im Netzwerk auf (nicht vom NAS selbst). Lädt sie, ist die Firewallregel aktiv. Sonst fehlt bei laufendem Container die Freigabe oder die NAS-IP ist falsch.

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

Öffnen Sie in der Admin-Oberfläche Adapter und suchen Sie 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 Shelly-Geräte per MQTT: Installieren Sie zuerst einen externen Mosquitto-Broker (Anleitung: Eclipse Mosquitto auf dem Synology NAS installieren), dann den ioBroker-MQTT-Client-Adapter und verbinden Sie ihn mit dem Mosquitto-Container über dessen internen Hostnamen im selben Docker-Netzwerk.

Klicken Sie nach der Adapter-Installation 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-v12`	Produktions-Tag; alternativ `v12.0.0` gepinnt
GHCR-Mirror	`ghcr.io/buanet/iobroker:latest-v12`	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 13 Trixie, Node.js 24	Stand: v12.0.0 (04.10.2026, Builds fortlaufend)

Umgebungsvariable	Beispielwert	Bedeutung
`TZ`	`Europe/Berlin`	Zeitzone (optional, Standard Europe/Berlin; auch Vienna, Zurich)
`LANG`	`de_DE.UTF-8`	Spracheinstellung (optional, Standard de_DE.UTF-8)
`LANGUAGE`	`de_DE:de`	Sprachpräferenz (optional, Standard de_DE:de)
`LC_ALL`	`de_DE.UTF-8`	Locale (optional, Standard de_DE.UTF-8)
`SETUID`	`1026`	UID des Container-Prozessbenutzers (Standard 1000)
`SETGID`	`100`	GID des Container-Prozessbenutzers (Standard 1000)
`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 (Standard true)
`DEBUG`	`false`	Erweitertes Logging (nur zur Fehlersuche)
`AVAHI`	`false`	Avahi-Daemon für HomeKit/yahka-Adapter

Host-Netzwerk vs. Bridge: die richtige Wahl treffen

Für die meisten Installationen mit MQTT-Geräten (Shelly, Tasmota) und Zigbee2MQTT als separatem Container reicht Bridge-Netzwerk mit Port-Mapping 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 läuft ebenfalls als separater Container: 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 BENUTZERNAME 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: Erststart abwarten und Log beobachten, siehe Schritt 3.
Leere Seite oder Verbindungsfehler unter Port 8081: ioBroker startet noch (siehe Schritt 3), oder ein Reverse Proxy leitet auf den falschen internen Port weiter.
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 weder ein v11.1- noch ein v12-Image zur Verfügung. Der letzte Tag mit arm/v7 ist buanet/iobroker:v11.0.1.
Adapter bricht nach Update ab: Ein Major-Version-Wechsel (z. B. v11 → v12) kann Adapter-Inkompatibilitäten verursachen. Vorgehen siehe Abschnitt „Update von v11 auf v12“.

Häufige Fragen

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

Bridge-Netzwerk mit "8081:8081", Host-Netzwerk nur für Multicast, Broadcast oder mDNS (siehe Abschnitt Host-Netzwerk vs. Bridge).

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

3 bis 5 Minuten. Meldet docker logs iobroker --follow den Start des Admin-Adapters auf Port 8081, ist ioBroker bereit (siehe Schritt 3).

Kann ioBroker parallel zu Home Assistant auf demselben NAS laufen?

Ja, beide laufen als unabhängige Docker-Container ohne Port-Konflikt (Home Assistant 8123, ioBroker 8081). Über einen gemeinsamen MQTT-Broker (Mosquitto) sind Gerätedaten in beiden Plattformen sichtbar. Manche Nutzer betreiben Home Assistant für die Oberfläche und ioBroker für Homematic/KNX-Automatisierungen.

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, JavaScript/Blockly statt Python und der deutschsprachigen Community auf forum.iobroker.net. Für reine Shelly- oder Tasmota-Setups sind beide gleichwertig; bei Homematic oder KNX ist ioBroker oft die bessere Wahl.

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 Heiminstallationen mit einigen hundert Datenpunkten. Redis (IOB_OBJECTSDB_TYPE=redis und IOB_STATESDB_TYPE=redis) verbessert die Performance 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 als Compose-Projekt auf dem Synology NAS ist in rund 30 Minuten eingerichtet, sofern SETUID/SETGID stimmen und das Volume beim Erststart leer ist.

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 (ENV-Variablen, Volumes) sowie buanet/iobroker auf Docker Hub (Tags, Architekturen).