UniFi OS Server (UOS) Controller
One self-hosted UniFi controller for the whole lab: sa-uos-01 on VLAN 10, pinned UOS 5.1.19, Pulumi-provisioned with API-driven first-run setup.
One self-hosted UniFi OS Server controller for the lab, hosted on
sa-edge-01. The 2026-07-26 redesign makes it the controller for all Site A
switches and APs, including the three-switch L2 fabric. Site B standalone gear
later adopts over WireGuard.
Topology
| Value | |
|---|---|
| VM | sa-uos-01 on sa-edge-01 |
| Bootstrap address | temp-LAN static 192.168.1.40 (Pulumi uos.ip) |
| Final address | 10.10.10.40/24 (VLAN 10, .40-.49 service band), GW 10.10.10.1 |
| Specs | 4 vCPU / 8 GB / 64 GB, Ubuntu 24.04, Podman + slirp4netns |
| Version | UOS 5.1.19 base image; UniFi Network application must be 9.1.120+ before Switch Pro XG adoption |
| Web UI | :11443 (self-signed cert); device ports TCP 8080 (inform) + UDP 3478 (STUN) |
| Site B | No second controller: Site B gear adopts over WireGuard (L3 adoption against 10.10.10.40) |
VLAN 10 placement keeps the controller on the same management network as the Site A switches and sa-ap-01. Its target vNIC moves from temporary vmbr0 to PVE-tagged VLAN 10 on vmbr2, one VM at a time with console access.
Controller Boundary
Adopt all Site A switches and APs to sa-uos-01. The retired Site A Gateway Max is not part of the target. Site B's USG Pro remains self-managed because UOS does not manage Cloud Gateways. Never clone the UOS VM; rebuild fresh via Pulumi to avoid copied Site Manager identity.
Provisioning Posture
components/uos.py → UosServer (built on the shared aorxi_core Vm/CloudImage blocks), gated by the aorxi-unifi:uos config block (default enabled: false, so a no-config preview is a safe no-op). cloud-init installs Podman, fetches the pinned .bin, runs it unattended, and enables uosserver. First boot deliberately ends at deviceState: notSetup: owner creation belongs to the config phase (make unifi-config-setup).
downloadUrl governs the initial install only; upgrades come from the UOS Update Manager once running. Controller-down is non-disruptive: adopted devices keep forwarding, only management pauses. Boot ordering on the E200: OPNsense first, sa-uos-01 behind it (on_boot=true).
Operating Contract
| Area | Decided posture |
|---|---|
| Device scope | sa-sw-01/02/03 and sa-ap-01 adopt to UOS; sb-sw-02 adopts later over WireGuard. Gateway Max, USG Pro, and Netgear sb-sw-01 remain outside UOS. |
| Local adoption | Site A devices share VLAN 10 with sa-uos-01; UniFi Network 9.1.120 or later is required before Switch Pro XG adoption. |
| Site B reachability | L3 adoption targets 10.10.10.40; TCP 8080 inform reachability must cross WireGuard. UOS also exposes UDP 3478 for STUN. |
| Controller outage | Adopted devices retain their applied forwarding configuration; adoption, telemetry, and configuration changes pause. |
| Startup | OPNsense starts first on sa-edge-01; sa-uos-01 starts behind it with on_boot=true. |
| Upgrade path | The running server upgrades through UOS Update Manager or Site Manager. downloadUrl controls only a fresh install. |
| Recovery posture | Rebuild fresh through Pulumi. Never clone the VM because cloned instances reuse Site Manager identity. |
Open Operating Decisions
Controller Backup and DR Are Not Designed
UOS autobackups exist, but backup destination, retention, export cadence, restore testing, and disaster-recovery procedure are not decided. Do not describe the controller as recoverable until that contract is designed and tested.
Network-application automation, device-adoption automation, Ubiquiti SSO/Site Manager linking, and TLS beyond the current self-signed certificate also remain deferred. Until those items are implemented, the Site A L2 fabric is configured manually under change control.
Related Pages
- Initial Site Bootstrap: where the UOS VM sits in the edge-VM build order
- Site A L2 Fabric: controller, VLAN, RSTP, routing-owner, and failure boundaries
- Site A Port Map: where all Site A UniFi devices connect
Secrets: OpenBao
Two independent OpenBao instances (sa-bao-01, sb-bao-01) on the edge E200s: secret tiers, cross-site transit auto-unseal, AppRole consumers, and the break-glass fallback.
Kafka & Database Performance
Kafka blue/green cutover patterns, ordered consumer processing strategy, and PostgreSQL observability and transaction tuning guidance.