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 whole lab, hosted on sa-edge-01 — a good E200 workload (Podman-based; OPNsense keeps priority). Decided 2026-06-28, first-run automation 2026-06-29/30. Repo: unifi/provision/ (Pulumi project aorxi-unifi) plus unifi/config/ (Ansible first-run setup via the UOS HTTPS API).
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 (pinned .bin, config var uos.downloadUrl) |
| 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 is deliberate: the controller shares L2 with the UniFi devices it manages (sa-ap-01, access switches), so adoption needs no inter-VLAN OPNsense rule.
Two hard rules
UOS cannot manage Cloud Gateways — the Gateway Max and USG Pro stay self-managed as bootstrap/fallback, per the architecture rules. And never clone the VM: cloned UOS instances reuse Site Manager tokens. Rebuild fresh via Pulumi instead.
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).
Related Pages
- Initial Site Bootstrap — where the UOS VM sits in the edge-VM build order
- UniFi Handoff — how the demoted UniFi routers hang off OPNsense
- Site A Port Map — where
sa-ap-01and the access switches 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.