Skip to content

Getting Started

Jump to bottom
lemker edited this page May 27, 2026 · 4 revisions

System Requirements

UniFi OS Server is more resource intensive than the Network Controller and requires sufficient CPU/RAM to function. Many connected devices will require more resources.

  • x86_64 or ARM64 CPU
  • At least 2GB RAM
  • 20GB free disk space
  • Docker Compose >v2
  • Linux Kernel >3.16

Installation

Docker Compose

Use the docker-compose.yaml template and update /path/to/unifi-os-server/* to your host's persistent data paths.

After starting the container, the UniFi OS Server console will be available at https://<IP>:11443.

Kubernetes

See kubernetes/.

Note that currently Kubernetes deployments require privileged: true in order to function. See #51.

Migrating

If you're changing the inform address by migrating to a different host or new IP/domain, you may want to update your UniFi devices' set-inform address before migration.

Migrating from Network Controller

The easiest way to migrate from UniFi Network Controller to UniFi OS Server is to use backup and restore:

  1. Backup Network Controller config
  2. Shutdown Network Controller
  3. Start UniFi OS Server
  4. Select Restore from Backup on the setup page and upload your .unf backup file

Migrating from UniFi OS Server Native Installation

To migrate from a standard installation of UniFi OS Server (as provided by UniFi), follow the same backup and restore steps as above.

Network Version Mismatch

If your backup file is from a newer Network version than what's bundled with UniFi OS Server, restore will not work. You will first need to:

  1. Setup UniFi OS Server without restore, using a temporary local user
  2. Navigate to Settings > Control Plane > Updates and update Network
  3. Restore backup from Settings > Control Plane > Backups > Restore

Updating

Update UniFi OS Server

To update UniFi OS Server, use docker pull ghcr.io/lemker/unifi-os-server:latest or update the pinned tag in your Docker Compose file. You may wish to setup alerts for when new releases are published on GitHub or use a GitOps method like Renovate to keep your container updated.

Update Applications

To update UniFi applications like Network, InnerSpace, etc. use the UniFi OS Server GUI: navigate to Settings > Control Plane > Updates

Clone this wiki locally