UniFi Network: Migration von Docker zu UniFi OS Server auf Ubuntu

Wer UniFi Network bisher über einen inoffiziellen Docker-Container betreibt, hat lange gut damit gelebt, aber Ubiquiti hat mit dem UniFi OS Server eine offiziell unterstützte Alternative geschaffen, die echte Vorteile mitbringt: native Updates direkt aus der App, kein Docker-Overhead, kein unübersichtliches und unsicheres Updaten mehr.

Ich habe die Migration selbst durchgeführt und war positiv überrascht, wie unkompliziert das abläuft, vorausgesetzt man geht in der richtigen Reihenfolge vor.

Voraussetzungen

Bevor es losgeht, kurz prüfen ob der Host die Mindestanforderungen erfüllt:

• RAM: Mindestens 2 GB
• Netzwerk: 100 Mbit/s kabelgebunden
• Speicher: Mindestens 10 GB freier Platz
• Betriebssystem: Ubuntu (getestet mit Ubuntu 22.04 / 24.04)

Ich habe absichtlich denselben Ubuntu-Host genommen, auf dem bereits der Docker-Container lief, denn so bleibt die IP-Adresse des Controllers gleich und alle Geräte verbinden sich nach der Wiederherstellung ohne weitere Anpassungen.

Schritt 1: Backup der Docker-Instanz erstellen

Der erste und wichtigste Schritt: Backup sichern, bevor irgendetwas angefasst wird.

In der laufenden Docker-Instanz unter Einstellungen → System → Backups auf Download klicken.

Im Download-Dialog reicht es auf settings only und Download zu klicken. Anschließend wird die .unf-Datei lokal gespeichert.

Ich habe aktuell im Docker container die Version 8.0.24 installiert gehabt und wollte einfach mal testen ob eine direkte migration auf die (aktuell v10.x) neuste UnifiOS Version funktioniert. Kurz vorweg: es hat ohne Probleme geklappt. Hier aber nochmal der Hinweis: je näher die beiden Versionen aneinander sind, desto unwahrscheinlicher sind Probleme beim Wiederherstellen.

Schritt 2: Docker-Container herunterfahren

Wichtig: Den Container vor der Installation des UniFi OS Servers stoppen. Beide Dienste lauschen auf denselben Ports. Laufen sie gleichzeitig, gibt es Konflikte.

docker stop <container-name>

Wer Docker Compose nutzt:

docker compose down

Den Container kann hier schon gelöscht werden, am besten jedoch nach der erfolgreichen Migration.

Schritt 3: Abhängigkeiten installieren

Der UniFi OS Server läuft intern auf Basis von Podman (rootless Container-Runtime). Das Paket muss vor der Installation vorhanden sein:

sudo apt update && sudo apt upgrade -y
sudo apt-get install -y podman slirp4netns

slirp4netns ist die Netzwerkbrücke für rootless Container — ohne dieses Paket schlägt die Installation fehl.

Schritt 4: UniFi OS Server herunterladen und installieren

Den aktuellen Download-Link auf ui.com/download unter der Kategorie UniFi OS Server kopieren. In meinem Fall war das:

https://fw-download.ubnt.com/data/unifi-os-server/b828-linux-x64-5.1.19-e38d0b0e-b462-403d-9861-f57f25772106.19-x64

Einen Arbeitsordner anlegen und die Datei herunterladen:

sudo mkdir -p /opt/unifios
cd /opt/unifios
wget -O uosserver-installer "https://fw-download.ubnt.com/data/unifi-os-server/b828-linux-x64-5.1.19-..."

Ausführbar machen und starten:

chmod +x uosserver-installer
sudo ./uosserver-installer

Die Installation fragt nach einer Bestätigung mit Y. Danach läuft der Installer durch und zeigt am Ende folgende Ausgabe:

INFO Waiting for container 'uosserver' to start (timeout: 60s)
INFO Container 'uosserver' is running. (elapsed: 0.0s)
INFO Waiting for systemd to be ready (timeout: 60s)
INFO Systemd is ready. (elapsed: 3.7s)
INFO Starting uosserver systemd service...
INFO Waiting for UniFi OS Server to start...
INFO
    !!! INSTALLATION COMPLETE !!!
    To grant permission for a user to run 'uosserver' commands:
    -> Add the user to the 'uosserver' group:
       usermod -aG uosserver <username>
    -> Then log out and log back in for the changes to take effect.
    To get started with available commands, run:
       uosserver help

UniFi OS Server is running at: https://192.168.10.10:11443/

Schritt 5: Backup einspielen

Die Web-Oberfläche unter der angezeigten Adresse (Port 11443) im Browser öffnen. Das selbstsignierte Zertifikat zunächst im Browser akzeptieren.

Der Setup-Assistent erscheint mit dem Einstiegspunkt „Restore From Backup" — genau das anklicken.

Nach der Anmeldung macht der UniFi OS Server nicht automatisch einen Cloud-Sync der Konfiguration obwohl die Option "restore from backup" genutzt wurde. Das Backup muss manuell hochgeladen werden.

Den Weg dorthin nach dem ersten Login: Einstellungen → UniFi OS Server → Control Plane → Backups → Restore.

Die vorher gesicherte .unf-Datei hochladen und den Restore starten. Das System zeigt dann den Fortschritt:

Nach Abschluss des Restores landet man in einer vollständig wiederhergestellten Instanz — alle VLANs, SSIDs und Geräte-Adoptionen sind vorhanden.

Das neue Interface: Fast alles beim alten

Das interface sieht nahezu identisch zum alten aus. Der große Vorteil ist, dass man direkt über die Oberfläche zukünftige Updates einspielen kann. Vorher war es immer recht unübersichtlich und verwirrend mit dem Docker container dazu.

Häufige Fragen

Kann man jetzt auch UniFi Protect oder andere Ubiquiti-Produkte auf demselben Server betreiben?

Nein. Der UniFi OS Server auf einem generischen Linux-Host unterstützt aktuell ausschließlich UniFi Network. Protect, Access oder Talk sind weiterhin an dedizierte Ubiquiti-Hardware (UDM, UNVR etc.) gebunden.

Fazit

Die Migration von UniFi Network Docker zum offiziellen UniFi OS Server ist weniger aufwändig als sie wirkt. Der einmalige Aufwand lohnt sich vor allem wegen der vereinfachten Update-Verwaltung — kein manuelles Docker-Image-Pulling mehr, Updates direkt aus der App.

Einziger echter Nachteil: Man verliert die Docker-Flexibilität. Wer seinen Controller eng in eine Container-Infrastruktur eingebunden hat, muss das neu denken. Für alle anderen ist der Wechsel eine klare Verbesserung im täglichen Betrieb.