UniFi OS Server

Run UniFi OS Server directly in Docker or Kubernetes.

The UniFi OS Server is the new standard for self-hosting UniFi, replacing the legacy UniFi Network Server. While the Network Server provided basic hosting functionality, it lacked support for key UniFi OS features like Organizations, IdP Integration, or Site Magic SD-WAN. With a fully unified operating system, UniFi OS Server now delivers the same management experience as UniFi-native–including CloudKeys, Cloud Gateways, and Official UniFi Hosting–and is fully compatible with Site Manager for centralized, multi-site control.

https://help.ui.com/hc/en-us/articles/34210126298775-Self-Hosting-UniFi

Installation

Docker Compose

See docker-compose.yaml

Home Assistant

1. In Home Assistant, go to Settings → Apps → App store, click ⋮ → Repositories, fill in https://github.com/lemker/unifi-os-server, and click Add → Close. Or click the Add repository button below, then click Add → Close.

   

2. Click the UniFi OS Server app, click Install, and wait until it's installed.

3. Optionally, set UOS_SYSTEM_IP on the Configuration tab. If left empty, the app uses Home Assistant's IP address.

4. On the Info tab, click Start, wait a few minutes, and click Open Web UI.

For storage, ports, and security notes, see ha-app/DOCS.md.

Kubernetes

See kubernetes

Deployment example uses ingress-nginx for the ingress and longhorn for storage.

Your ingress controller must be modified to accept extra ports. For example, ingress-nginx Helm values:

tcp:
  5005: "unifi/unifi-os-server-rtp-svc:5005" # Optional
  9543: "unifi/unifi-os-server-id-hub-svc:9543" # Optional
  6789: "unifi/unifi-os-server-mobile-speedtest-svc:6789" # Optional
  8080: "unifi/unifi-os-server-communication-svc:8080"
  8444: "unifi/unifi-os-server-hotspot-secured-svc:8444" # Optional
  28082: "unifi/unifi-os-server-support-files:28082" # Optional
  5671: "unifi/unifi-os-server-aqmps-svc:5671" # Optional
  8880: "unifi/unifi-os-server-hotspot-redirect-0-svc:8880" # Optional
  8881: "unifi/unifi-os-server-hotspot-redirect-1-svc:8881" # Optional
  8882: "unifi/unifi-os-server-hotspot-redirect-2-svc:8882" # Optional
udp:
  3478: "unifi/unifi-os-server-stun-svc:3478"
  5514: "unifi/unifi-os-server-syslog-svc:5514" # Optional
  10003: "unifi/unifi-os-server-discovery-svc:10003"

Parameters

Environment Variables

Environment	Description
UOS_SYSTEM_IP	Hostname or IP for UniFi OS Server
HARDWARE_PLATFORM	Manually set hardware platform

UOS_SYSTEM_IP

Set UniFi OS Server hostname (recommended) or IP address for inform. To adopt device:

1. SSH into device with username/password: ubnt/ubnt

2. Set inform address:

   set-inform http://$UOS_SYSTEM_IP:8080/inform

HARDWARE_PLATFORM

Overrides your detected hardware platform. Accepted values are: synology.

Ports

Protocol	Port	Direction	Usage
TCP	11443	Ingress	UniFi OS Server GUI/API
TCP	5005	Ingress	RTP (Real-time Transport Protocol) control protocol
TCP	9543	Ingress	UniFi Identity Hub
TCP	6789	Ingress	UniFi mobile speed test
TCP	8080	Ingress	Device and application communication
TCP	8444	Ingress	Secure Portal for Hotspot
UDP	3478	Both	STUN for device adoption and communication (also required for Remote Management)
UDP	5514	Ingress	Remote syslog capture
UDP	10003	Ingress	Device discovery during adoption
TCP	28082	Ingress	Device support files download
TCP	5671	Ingress	AQMPS
TCP	8880	Ingress	Hotspot portal redirection (HTTP)
TCP	8881	Ingress	Hotspot portal redirection (HTTP)
TCP	8882	Ingress	Hotspot portal redirection (HTTP)

Frequently Asked Questions

What is the difference between images?

The uosserver image is provided by UniFi, extracted from the installation binary. The unifi-os-server image provides better compatibility for Docker and Kubernetes with directory fixes and configuration through environment variables.

Why does the container need specific settings for cgroup and tmpfs?

The underlying structure of UniFi OS Server runs every component as systemd services which requires access to the host cgroup.

Legal

This project is not affiliated with, endorsed by, or supported by Ubiquiti Inc. UniFi, the UniFi logo, and UniFi OS are trademarks of Ubiquiti Inc. and are used here only to identify the software this project runs.

This project is licensed under the GNU Affero General Public License v3.0. UniFi OS Server itself is proprietary software owned by Ubiquiti Inc. and is subject to its own license terms.