Wer ein UniFi-Netzwerk mit Access Points, Switches oder Gateways betreibt, braucht einen Controller: einen Ubiquiti Cloud Key, eine Cloud-Instanz oder eigene Hardware. Ein ohnehin laufendes Synology NAS übernimmt diese Aufgabe ohne zusätzliches Gerät und ohne Cloud-Abhängigkeit. Diese Anleitung nutzt das gepflegte Image linuxserver/unifi-network-application (Stand September 2026: Version 10.6.106), das einen separaten MongoDB-Container benötigt.

Voraussetzungen

Synology NAS mit DSM 7.2 oder höher und installiertem Container Manager
Mindestens 4 GB RAM (8 GB empfohlen für komfortablen Betrieb)
x86-CPU mit AVX-Unterstützung für MongoDB 5.0 und neuer; ohne AVX mongo:4.4 verwenden (siehe Troubleshooting)
Mindestens 5 GB freier Speicherplatz für Docker-Images und Datenbankwachstum
Feste lokale IP-Adresse des NAS (DHCP-Reservation im Router empfohlen)
SSH-Zugang zum NAS (aktivieren: SSH auf dem Synology NAS aktivieren und verbinden)
Grundkenntnisse im Container Manager: Docker-Compose-Projekt im Container Manager anlegen

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: Ordnerstruktur anlegen und PUID/PGID ermitteln

Alle Daten liegen unter /volume1/docker/unifi. Hintergrund zu Ordnern und Rechten finden Sie in der Anleitung zu Docker-Ordnern und PUID/PGID auf Synology.

Legen Sie per File Station folgende Ordner an:

/volume1/docker/unifi/config – persistente App-Daten, Zertifikate, automatische Backups
/volume1/docker/unifi/db – MongoDB-Datenbankdateien

Ermitteln Sie anschließend per SSH Ihre PUID und PGID:

id DEIN_BENUTZERNAME

Die Ausgabe liefert uid=1026(benutzername) gid=100(users) ; notieren Sie die Zahlen für die compose.yaml. Beim ersten angelegten Synology-Benutzer sind das meist 1026 und 100, prüfen Sie es trotzdem.

Verifizieren: ls /volume1/docker/unifi zeigt config und db; id gibt UID und GID ohne Fehlermeldung aus.

Schritt 2: MongoDB-Init-Skript erstellen

Das Init-Skript legt beim allerersten Start von MongoDB den UniFi-Datenbankbenutzer mit den nötigen RBAC-Rollen an. Es läuft nur einmal, solange /data/db noch keine Datenbankdateien enthält; es muss also vor dem ersten Start vorhanden sein.

Erstellen Sie eine Datei init-mongo.sh mit folgendem Inhalt und speichern Sie sie mit Unix-Zeilenenden (LF, nicht CRLF), z. B. in VS Code oder Notepad++:

#!/bin/bash

# Ermittelt automatisch mongo oder mongosh (je nach MongoDB-Version)
if command -v mongosh > /dev/null 2>&1; then
  MONGO_CMD=mongosh
else
  MONGO_CMD=mongo
fi

"$MONGO_CMD" -u "$MONGO_INITDB_ROOT_USERNAME" \
  -p "$MONGO_INITDB_ROOT_PASSWORD" \
  --authenticationDatabase admin \
  --eval "
    db = db.getSiblingDB('$MONGO_DBNAME');
    db.createUser({
      user: '$MONGO_USER',
      pwd: '$MONGO_PASS',
      roles: [
        { role: 'dbOwner', db: '$MONGO_DBNAME' },
        { role: 'dbOwner', db: '${MONGO_DBNAME}_stat' },
        { role: 'dbOwner', db: '${MONGO_DBNAME}_audit' },
        { role: 'dbOwner', db: '${MONGO_DBNAME}_restore' },
        { role: 'clusterMonitor', db: 'admin' }
      ]
    });
  "

Übertragen Sie die Datei per File Station nach /volume1/docker/unifi/db/init-mongo.sh und setzen Sie per SSH die Ausführberechtigung:

chmod +x /volume1/docker/unifi/db/init-mongo.sh

Verifizieren: Prüfen Sie Berechtigungen und Zeilenenden:

ls -la /volume1/docker/unifi/db/init-mongo.sh
file /volume1/docker/unifi/db/init-mongo.sh

Erwartet: x-Bit gesetzt (z. B. -rwxr-xr-x), file meldet Bourne-Again shell script ohne den Zusatz „with CRLF line terminators“.

Schritt 3: compose.yaml erstellen

Ersetzen Sie SICHERES_ROOT_PASSWORT und SICHERES_UNIFI_PASSWORT durch eigene Passwörter. Sonderzeichen wie @ oder # müssen Sie im unifi-network-application-Container URL-kodieren (@ wird zu %40), im MongoDB-Container nicht. Am einfachsten verwenden Sie nur Buchstaben und Ziffern.

MongoDB ist bewusst auf 7.0 festgelegt (unterstützt ab UniFi 8.1, MongoDB 8.0 ab UniFi 9.0). Verwenden Sie nie latest: MongoDB unterstützt keine automatischen Upgrades zwischen Hauptversionen.

---
# UniFi Network Application - Synology NAS (DSM 7.2 Container Manager)
# Ordner vorher anlegen:
#   /volume1/docker/unifi/config
#   /volume1/docker/unifi/db
# init-mongo.sh nach /volume1/docker/unifi/db/ hochladen (Schritt 2)

services:
  unifi-db:
    image: docker.io/mongo:7.0
    container_name: unifi-db
    hostname: unifi-db
    environment:
      - MONGO_INITDB_ROOT_USERNAME=root
      - MONGO_INITDB_ROOT_PASSWORD=SICHERES_ROOT_PASSWORT
      - MONGO_USER=unifi
      - MONGO_PASS=SICHERES_UNIFI_PASSWORT
      - MONGO_DBNAME=unifi
      - MONGO_AUTHSOURCE=admin
    volumes:
      - /volume1/docker/unifi/db:/data/db
      - /volume1/docker/unifi/db/init-mongo.sh:/docker-entrypoint-initdb.d/init-mongo.sh:ro
    restart: unless-stopped

  unifi-network-application:
    image: lscr.io/linuxserver/unifi-network-application:latest
    container_name: unifi-network-application
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Europe/Berlin
      - MONGO_USER=unifi
      - MONGO_PASS=SICHERES_UNIFI_PASSWORT
      - MONGO_HOST=unifi-db
      - MONGO_PORT=27017
      - MONGO_DBNAME=unifi
      - MONGO_AUTHSOURCE=admin
      - MEM_LIMIT=1024
      - MEM_STARTUP=1024
    volumes:
      - /volume1/docker/unifi/config:/config
    ports:
      - 8443:8443
      - 8080:8080
      - 3478:3478/udp
      - 10001:10001/udp
      - 1900:1900/udp
      - 8843:8843
      - 8880:8880
      - 6789:6789
      - 5514:5514/udp
    restart: unless-stopped
    depends_on:
      - unifi-db

Eine Übersicht aller Ports und ihrer Bedeutung:

Port	Protokoll	Zweck	Pflicht
8443	TCP	Web-Admin-Interface (HTTPS)	Ja
8080	TCP	Inform-Port für Geräte-Kommunikation	Ja
3478	UDP	STUN-Protokoll	Ja
10001	UDP	AP-Discovery im lokalen Netz	Ja
1900	UDP	L2-Netzwerk-Discovery	Optional
8843	TCP	Gastportal HTTPS-Redirect	Optional
8880	TCP	Gastportal HTTP-Redirect	Optional
6789	TCP	Mobiler Durchsatztest	Optional
5514	UDP	Remote Syslog	Optional

Umgebungsvariable	Beispielwert	Bedeutung
PUID	1026	Linux User-ID für Dateizugriffsrechte (per SSH prüfen)
PGID	100	Linux Group-ID (Synology „users“-Gruppe)
TZ	Europe/Berlin	Zeitzone im IANA-Format; auch Europe/Vienna, Europe/Zurich
MONGO_USER	unifi	MongoDB-Benutzername für die App
MONGO_PASS	SICHERES_UNIFI_PASSWORT	Passwort; Sonderzeichen URL-enkodieren
MONGO_HOST	unifi-db	Muss dem container_name des mongo-Containers entsprechen
MONGO_PORT	27017	Standard-MongoDB-Port
MONGO_DBNAME	unifi	Name der UniFi-Datenbank
MONGO_AUTHSOURCE	admin	Authentifizierungsdatenbank
MEM_LIMIT	1024	Java-Heap in MB; bei 2 GB RAM auf 512 reduzieren

Verifizieren: MONGO_PASS ist in beiden Services identisch (bei Sonderzeichen im UniFi-Service kodiert), PUID und PGID entsprechen der Ausgabe aus Schritt 1.

Schritt 4: Compose-Projekt im Container Manager anlegen und starten

Legen Sie die compose.yaml im Container Manager als Projekt an, nicht als einzelne Container. Nur dann liegen beide Container im selben Projektnetz und erreichen sich über den Namen unifi-db. Details zum Anlegen: Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren.

Nach „Erstellen“ und „Ausführen“ lädt der Container Manager beide Images, MongoDB führt das Init-Skript aus, danach verbindet sich die UniFi Network Application. Der Start dauert 2 bis 3 Minuten.

Verifizieren: In der Projektansicht zeigen unifi-db und unifi-network-application den Status „Wird ausgeführt“. Prüfen Sie das Log von unifi-db:

docker logs unifi-db 2>&1 | tail -20

Das Log von MongoDB 7.0 ist JSON-formatiert; es sollte Waiting for connections enthalten und keinIllegal instruction (das würde auf ein fehlendes AVX hinweisen). Im Log der UniFi Application darf keinException authenticating auftauchen.

Schritt 5: Synology-Firewall für UniFi-Ports freigeben

Ist die DSM-Firewall aktiv, geben Sie im lokalen Netz mindestens diese Ports frei: 8443/tcp, 8080/tcp, 3478/udp und 10001/udp. Den genauen Weg erklärt die Anleitung zur Synology DSM-Firewall für Docker-Container.

Port 27017 (MongoDB) wird in der compose.yaml nicht veröffentlicht und darf weder in der Firewall noch im Router freigegeben werden.

Verifizieren: Testen Sie von einem anderen Rechner im lokalen Netz:

curl -k https://NAS-IP:8443

Sie erhalten HTML oder eine Weiterleitung. Ein Timeout deutet auf eine blockierende Firewall-Regel hin, Connection refused auf einen nicht gestarteten Container.

Schritt 6: UniFi Controller einrichten

Öffnen Sie im Browser:

https://NAS-IP:8443

Bestätigen Sie die Warnung zum selbstsignierten Zertifikat. Der Einrichtungsassistent fragt Controller-Name, Admin-Konto, Land und Zeitzone ab; ein vorhandenes Backup können Sie hier wiederherstellen. Hängt die Anmeldung in einer Schleife, löschen Sie die Cookies der Seite oder verwenden Sie ein privates Fenster.

Verifizieren: Nach dem Assistenten erscheint das Dashboard oder die Anmeldeseite; die Anmeldung mit dem neuen Admin-Konto gelingt.

Schritt 7: Inform-Host setzen und Geräte adoptieren

Im Container kennt der Controller nur seine interne Docker-IP. Damit Geräte ihn finden, tragen Sie unter Settings > System > Advanced bei „Inform Host“ die IP-Adresse des NAS ein und aktivieren Override.

Geräte im selben Layer-2-Netz werden über Port 10001/udp automatisch erkannt und erscheinen unter „Pending Adoption“. Für Geräte in anderen Netzen setzen Sie den Inform-Endpunkt per SSH auf dem Gerät:

set-inform http://NAS-IP:8080/inform

Danach erscheint das Gerät im Controller unter „Pending Adoption“. Klicken Sie auf „Adopt“ und warten Sie, bis der Status auf „Connected“ wechselt. VLANs und Segmentierung beschreibt die Anleitung Zero-Trust-Netzwerksegmentierung im KMU.

Verifizieren: Im UniFi Dashboard zeigen adoptierte Geräte den Status „Connected“ (grüner Punkt). Geräte mit Status „Disconnected“ nach der Adoption deuten auf einen blockierten Port 8080 oder einen nicht gesetzten Inform-Host hin.

Schritt 8: Automatische Backups prüfen und konfigurieren

Automatische Backups legt der Controller als .unf-Dateien ab unter:

/volume1/docker/unifi/config/data/backup/autobackup

Prüfen Sie unter Settings > System > Backups, ob die automatische Sicherung aktiv ist, und legen Sie Intervall und Anzahl fest. Sichern Sie zusätzlich mit Hyper Backup:

/volume1/docker/unifi/config – Controller-Konfiguration und automatische Backups
/volume1/docker/unifi/db – MongoDB-Dateien; konsistent nur bei gestopptem Projekt, für die Wiederherstellung genügt in der Regel die .unf-Datei

Ein manuelles Backup lässt sich jederzeit über Settings > System > Backup > Download Backup erstellen und lokal speichern.

Verifizieren: Nach dem ersten Sicherungslauf enthält der Ordner Dateien:

ls -lh /volume1/docker/unifi/config/data/backup/autobackup/

Erwartet: .unf-Dateien mit aktuellem Datum.

Troubleshooting / Typische Fehler

„Illegal instruction (core dumped)“ beim MongoDB-Start: Die CPU unterstützt kein AVX, z. B. Intel Celeron J3455, J4105 oder J4125. Lösung: In der compose.yaml das Image auf docker.io/mongo:4.4 ändern.
Init-Skript wird nicht ausgeführt, MongoDB-Benutzer fehlt: In /volume1/docker/unifi/db lagen beim ersten Start bereits Datenbankdateien. Lösung: Container stoppen, /volume1/docker/unifi/db vollständig leeren (außer init-mongo.sh), Container neu starten.
„Exception authenticating“ im UniFi-Log: Ursache A: MONGO_PASS enthält Sonderzeichen ohne URL-Enkodierung (im unifi-network-application-Container muss @ als %40 kodiert sein). Ursache B: MongoDB war beim UniFi-Start noch nicht bereit; 2 bis 3 Minuten warten und ggf. unifi-network-application-Container neu starten.
init-mongo.sh wird nicht ausgeführt (CRLF-Fehler): Datei wurde unter Windows erstellt und hat Windows-Zeilenenden. Lösung per SSH: dos2unix /volume1/docker/unifi/db/init-mongo.sh && chmod +x /volume1/docker/unifi/db/init-mongo.sh
Geräte erscheinen nicht / Adoption schlägt fehl: Inform-Host nicht gesetzt oder Port 8080/tcp durch Synology-Firewall blockiert. Lösung: Inform-Host in Settings > System > Advanced auf NAS-IP setzen, „Override“ aktivieren, Firewall-Regel für 8080/tcp prüfen.
Keine Schreibrechte (PUID/PGID): PUID/PGID in der compose.yaml stimmen nicht mit dem tatsächlichen NAS-Benutzer überein. Lösung: Per SSH id BENUTZERNAME ausführen, Werte anpassen und die Rechte nur für den App-Ordner setzen: sudo chown -R 1026:100 /volume1/docker/unifi/config (den db-Ordner verwaltet MongoDB selbst)
MongoDB startet nicht nach Container-Update: mongo:latest hat eine neue Hauptversion eingespielt. Lösung: Immer gepinnte Version verwenden (mongo:7.0 statt mongo:latest). Upgrades zwischen Hauptversionen erfolgen schrittweise: 4.4 → 5.0 → 6.0 → 7.0.

Häufige Fragen

Welche Synology-Modelle unterstützen MongoDB 7.0?

Entscheidend ist AVX. Celeron- und Pentium-CPUs vor Tiger Lake (z. B. J3455, J4125 in der DS920+) haben kein AVX; dort mongo:4.4 verwenden. AMD-Ryzen-Modelle wie die DS1522+ unterstützen AVX. Prüfen Sie im Zweifel per SSH mit grep -c avx /proc/cpuinfo (Ergebnis größer 0) oder das CPU-Modell auf ark.intel.com prüfen, ob der Eintrag „Advanced Vector Extensions (AVX)“ ausgewiesen ist.

Wie viel RAM benötigt der Controller auf dem NAS?

MongoDB und die UniFi Network Application zusammen brauchen mindestens 2 GB RAM im Betrieb. MEM_LIMIT=1024 passt für ein NAS mit 4 GB RAM; MongoDB belegt zusätzlich etwa 256 bis 512 MB. Ab etwa 20 Geräten sind 8 GB RAM sinnvoll.

Was ist der Unterschied zwischen diesem Setup und dem Ubiquiti Cloud Key?

Beide führen die UniFi Network Application aus; der Cloud Key ist eigene Hardware mit UniFi OS, das NAS-Setup nutzt vorhandene Infrastruktur und Hyper Backup. Fällt das NAS aus, läuft das UniFi-Netz weiter; der Controller wird für Konfiguration, Statistiken, Gastportal und Firmware-Updates benötigt.

Wie werden Geräte in anderen Netzsegmenten adoptiert?

Geräte im selben Layer-2-Segment werden automatisch über Port 10001/udp erkannt. Für Geräte in anderen Netzen setzen Sie per SSH set-inform http://NAS-IP:8080/inform, siehe Schritt 7.

Kann ich vom alten linuxserver/unifi-controller-Image migrieren?

Ein direktes Umstellen ist nicht möglich, weil das neue Image eine externe MongoDB nutzt. Erstellen Sie in der alten Instanz unter Settings > System > Backups eine Sicherung, richten Sie die neue Instanz nach dieser Anleitung ein und spielen Sie die Sicherung im Einrichtungsassistenten ein.

Unterstützt das Setup WPA3-Enterprise und RADIUS?

Ja, die Funktionen der UniFi Network Application hängen nicht von der Hardware ab. Die Einrichtung beschreibt die Anleitung Enterprise-WLAN mit 802.1X und RADIUS.

Fazit

Der UniFi Network Controller auf dem Synology NAS verwaltet das UniFi-Netz ohne zusätzliche Hardware. Kritisch sind drei Punkte: MongoDB-Version festlegen, Init-Skript vor dem ersten Start bereitstellen und den Inform-Host auf die NAS-IP setzen.

Weiterführende Anleitungen und Quellen

Quellen: LinuxServer.io – unifi-network-application (offizielle Dokumentation) · GitHub – linuxserver/docker-unifi-network-application