Wer ein UniFi-Netzwerk mit Access Points, Switches oder Gateways betreibt, braucht einen Controller – entweder als Ubiquiti Cloud Key, als Cloud-Instanz oder eben auf eigener Hardware. Das Synology NAS, das in vielen KMU-Netzen und Homelabs ohnehin läuft, ist dafür die eleganteste Wahl: kein zusätzliches Gerät, kein monatliches Abo, volle Datenkontrolle. Das aktuelle linuxserver/unifi-network-application-Image (Version 10.4.57, Stand Juni 2026) ersetzt das veraltete jacobalberty/unifi-Image und benötigt zwingend einen separaten MongoDB-Container – dafür ist es aktiv gepflegt, Multi-Arch-fähig und offiziell dokumentiert.

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)
Intel-CPU – bevorzugt Atom C3000-Serie oder neuer mit AVX-Unterstützung (für MongoDB 7.0); ohne AVX: mongo:4.4 verwenden (Details im 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

Schritt 1: Ordnerstruktur anlegen und PUID/PGID ermitteln

Lege die benötigten Verzeichnisse über die Synology File Station an. Alle Daten landen unter /volume1/docker/unifi. Eine Übersicht der Volumes und ihrer Bedeutung findest du in der Anleitung zu Docker-Ordnern und PUID/PGID auf Synology.

Lege per File Station folgende Ordner an:

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

Ermittle anschließend per SSH deine PUID und PGID. Verbinde dich mit dem NAS und führe aus:

id DEIN_BENUTZERNAME

Die Ausgabe liefert uid=1026(benutzername) gid=100(users) – die Zahlen 1026 und 100 notierst du für die compose.yaml. Beim Synology-Erstbenutzer sind das typischerweise UID 1026 und GID 100, aber prüfe es immer selbst, da abweichende Werte zu Berechtigungsfehlern führen.

Verifizieren: Öffne die File Station und navigiere zu /volume1/docker/unifi. Du solltest die Unterordner config und db sehen. Die id-Ausgabe zeigt deine UID und GID ohne Fehlermeldung.

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, wenn /data/db komplett leer ist – also muss es vor dem ersten Container-Start vorhanden sein.

Erstelle auf deinem PC eine Datei namens init-mongo.sh mit folgendem Inhalt. Achte auf Unix-Zeilenenden (LF, nicht CRLF) – nutze VS Code oder Notepad++ und speichere explizit mit LF:

#!/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' }
      ]
    });
  "

Übertrage die Datei per SFTP oder Synology File Station nach /volume1/docker/unifi/db/init-mongo.sh. Setze anschließend per SSH die Ausführberechtigung:

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

Verifizieren: Prüfe Berechtigungen und Zeilenenden per SSH:

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

Erwartete Ausgabe: Berechtigungen -rwxr-xr-x oder ähnlich (x-Bit gesetzt). Der file-Befehl sollte Bourne-Again shell script, ASCII text executable ausgeben, nicht „with CRLF line terminators“ – das würde auf Windows-Zeilenenden hinweisen und den Start sabotieren.

Schritt 3: compose.yaml erstellen

Wähle sichere Passwörter für SICHERES_ROOT_PASSWORT und SICHERES_UNIFI_PASSWORT. Enthält das Passwort Sonderzeichen wie @, # oder !, musst du es in den Umgebungsvariablen des unifi-network-application-Containers URL-enkodieren (@ wird zu %40). Im MongoDB-Container selbst werden die Werte unenkodiert als Klartext übergeben.

Die Image-Version für MongoDB ist bewusst auf 7.0 gepinnt – niemals latest verwenden, da MongoDB keine automatischen Major-Version-Upgrades unterstützt und ein unbeabsichtigtes Update von 4.4 auf 7.0 die Datenbank unbrauchbar macht:

---
# 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: Öffne die compose.yaml in einem Editor und stelle sicher, dass beide Passwörter identisch in der Datei und im Init-Skript stehen. PUID und PGID müssen mit der SSH-Ausgabe aus Schritt 1 übereinstimmen.

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

Importiere die compose.yaml im Container Manager als Projekt – nicht als einzelnen Container. Nur als Projekt funktioniert die interne Docker-Netzwerkkommunikation zwischen unifi-db und unifi-network-application zuverlässig, weil beide Container sich dann über den Hostnamen unifi-db erreichen. Details zum Anlegen: Container Manager: Docker-Compose-Projekt anlegen, starten und aktualisieren.

Nach dem Klick auf „Erstellen“ und „Ausführen“ zieht der Container Manager beide Images. MongoDB startet zuerst und führt beim allerersten Start das Init-Skript aus. Die UniFi Network Application startet danach und verbindet sich mit MongoDB. Der gesamte Startvorgang dauert 2–3 Minuten.

Verifizieren: Öffne im Container Manager die Projektansicht – beide Container (unifi-db und unifi-network-application) müssen den Status „Wird ausgeführt“ zeigen. Prüfe die Logs des unifi-db-Containers:

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

Im Log sollte waiting for connections on port 27017 erscheinen und kein Illegal instruction (das würde auf ein fehlendes AVX hinweisen). Im Log der UniFi Application darf kein Exception authenticating auftauchen.

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

Die Synology DSM-Firewall blockiert standardmäßig alle Ports, die nicht explizit erlaubt sind. Für den UniFi Controller müssen mindestens diese Ports im lokalen Netz freigegeben werden: 8443/tcp, 8080/tcp, 3478/udp und 10001/udp. Den genauen Weg erklärt die Anleitung zur Synology DSM-Firewall für Docker-Container.

Wichtig: Port 27017 (MongoDB) darf nicht nach außen freigegeben werden – weder in der Synology-Firewall noch im Router. MongoDB ist ausschließlich für die interne Container-Kommunikation gedacht.

Verifizieren: Teste vom lokalen Netz aus (nicht vom NAS selbst), ob Port 8443 erreichbar ist:

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

Du erhältst HTML-Inhalt oder eine Weiterleitungsantwort. Ein Connection refused deutet auf eine blockierende Firewall-Regel hin.

Schritt 6: UniFi Controller einrichten

Öffne Firefox – nicht Chrome. Chrome hat bei selbstsignierten Zertifikaten im Einrichtungsassistenten bekannte Probleme mit Authentifizierungsschleifen. Navigiere zu:

https://NAS-IP:8443

Bestätige die Browser-Warnung zum selbstsignierten Zertifikat. Der Einrichtungsassistent führt dich durch die Grundkonfiguration: Controller-Name, Admin-Account anlegen, Land und Zeitzone wählen. Du kannst bestehende Geräte im nächsten Schritt adoptieren oder zunächst überspringen.

Verifizieren: Nach Abschluss des Assistenten siehst du das UniFi Network Dashboard. Falls du direkt zur Login-Seite weitergeleitet wirst, ist die Einrichtung erfolgreich abgeschlossen. Melde dich mit dem gerade angelegten Admin-Account an.

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

Damit UniFi-Geräte deinen Controller finden, muss der Inform-Host auf die NAS-IP gesetzt werden. Navigiere im Controller zu Settings > System > Advanced und trage unter „Inform Host“ die IP-Adresse deines NAS ein. Aktiviere die Option 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 (z. B. hinter einem VLAN-Trunk) verbinde dich per SSH auf das Gerät und setze den Inform-Endpunkt manuell:

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

Danach erscheint das Gerät im Controller unter „Pending Adoption“. Klicke auf „Adopt“ und warte, bis der Status auf „Connected“ wechselt. Wie du danach VLANs und Netzwerksegmentierung mit UniFi sauber umsetzt, 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

Der UniFi Controller erstellt standardmäßig tägliche automatische Backups unter:

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

Passe die Aufbewahrungsdauer unter Settings > System > Backup an (Standard: 3 Tage). Für eine vollständige Datensicherung empfiehlt sich Synology Hyper Backup auf beide Verzeichnisse:

/volume1/docker/unifi/config – Controller-Konfiguration und automatische Backups
/volume1/docker/unifi/db – MongoDB-Datenbankdateien

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

Verifizieren: Prüfe per SSH, ob der Backup-Ordner Dateien enthält (nach dem ersten automatischen Backup-Zyklus, typischerweise in der ersten Nacht):

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

Du solltest .unf-Dateien mit aktuellem Datum sehen.

Troubleshooting / Typische Fehler

„Illegal instruction (core dumped)“ beim MongoDB-Start: Deine CPU unterstützt kein AVX – tritt bei Synology-Modellen mit Intel Celeron J3455, J4105 oder J4125 auf. Lösung: In der compose.yaml das Image auf docker.io/mongo:4.4 ändern.
Init-Skript wird nicht ausgeführt, MongoDB-Benutzer fehlt: Das Verzeichnis /volume1/docker/unifi/db war beim ersten Start nicht leer. Das Init-Skript läuft nur bei komplett leerem /data/db. 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 noch nicht bereit beim UniFi-Start – 2–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.
Chrome-Authentifizierungsloop beim Setup: Bekanntes Problem mit selbstsignierten Zertifikaten in Chrome. Lösung: Firefox für die Ersteinrichtung verwenden.
PUID/PGID-Berechtigungsfehler – keine Schreibrechte: 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, Ordnerrechte neu setzen: chown -R 1026:100 /volume1/docker/unifi
MongoDB startet nicht nach Container-Update: Automatisches Upgrade von mongo:latest hat eine neue Major-Version eingespielt. Lösung: Immer gepinnte Version verwenden (mongo:7.0 statt mongo:latest). Major-Version-Upgrades müssen schrittweise erfolgen: 4.4 → 5.0 → 6.0 → 7.0.

Häufige Fragen

Welche Synology-Modelle unterstützen MongoDB 7.0?

Alle Synology-Modelle mit Intel Atom C3000-Serie (z. B. DS920+, DS1522+) und neueren CPUs unterstützen AVX und damit MongoDB 7.0. Ältere Modelle mit Celeron J3455, J4105 oder J4125 (vor Tiger Lake) unterstützen kein AVX – hier mongo:4.4 verwenden. Im Zweifel 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. Empfehlung: MEM_LIMIT=1024 bei NAS mit 4 GB RAM, MEM_LIMIT=512 bei 2 GB RAM. MongoDB belegt zusätzlich rund 256–512 MB. Für größere Installationen mit mehr als 20 Geräten sind 8 GB RAM komfortabler.

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

Funktional identisch – beide führen dieselbe UniFi Network Application aus. Der Cloud Key ist dedizierte Hardware mit Backup-Akku. Das NAS-Setup ist günstiger (keine Zusatzhardware), läuft auf vorhandener Infrastruktur und ermöglicht einfachere Datensicherung über Hyper Backup. Nachteil: Bei NAS-Ausfall kein Controller-Zugriff. Das UniFi-Netz läuft jedoch weiter – der Controller wird nur für Konfigurationsänderungen 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 hinter einem VLAN-Trunk verbindest du dich per SSH auf das Gerät und setzt den Inform-Endpunkt manuell: set-inform http://NAS-IP:8080/inform. Danach erscheint das Gerät unter „Pending Adoption“.

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

Ein In-Place-Upgrade ist nicht möglich, da das neue unifi-network-application-Image eine andere Verzeichnisstruktur verwendet. Erstelle in der alten Instanz unter Settings > System > Backup ein vollständiges Backup, richte die neue Instanz nach dieser Anleitung auf, und importiere das Backup beim ersten Start über den Einrichtungsassistenten.

Unterstützt das Setup WPA3-Enterprise und RADIUS?

Ja – die UniFi Network Application auf dem NAS ist funktional identisch mit der Cloud-Variante. Wie du WPA3-Enterprise mit RADIUS und dynamischer VLAN-Zuweisung konfigurierst, beschreibt die Anleitung Enterprise-WLAN mit 802.1X und RADIUS.

Fazit

Der UniFi Network Controller auf dem Synology NAS ist die kosteneffizienteste Lösung für KMU und Homelabs, die ihre UniFi-Infrastruktur selbst verwalten wollen. Das aktuelle linuxserver/unifi-network-application-Image ist aktiv gepflegt, Multi-Arch-fähig und offiziell dokumentiert. Der einzige kritische Punkt gegenüber einfacheren Setups ist der zwingend separate MongoDB-Container – der dafür aber auch eine saubere Trennung von Datenbank und Applikation bietet und professionelle RBAC-Berechtigungen ermöglicht. Wer die MongoDB-Version gepinnt hält, das Init-Skript korrekt vorbereitet und die Synology-Firewall richtig konfiguriert, hat einen stabilen Controller ohne laufende Kosten.

Weiterführende Anleitungen und Quellen

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