UniFi OS Server for Docker Compose

Run UniFi OS Server in a Docker container with persistent storage, systemd support, and multi-architecture images.

Overview

This repository provides a Docker Compose setup for running UniFi OS Server on a Linux host.

The image is built from the official UniFi OS Server software distributed by Ubiquiti. The included Compose file contains the required runtime settings for systemd, persistent storage, capabilities, temporary filesystems, and exposed ports.

For normal use, start with:

docker-compose.yaml

Security Notice

[!WARNING] Trivy scans may report HIGH or CRITICAL vulnerabilities in this image.

This project packages the official UniFi OS Server software from Ubiquiti. Many findings originate from upstream vendor components and cannot be fixed directly in this repository.

Security fixes must come from Ubiquiti upstream releases and can only be included here after a new upstream version is available.

Update Jun 10, 2026: We have reviewed the information you provided and discussed the findings internally with our development team. The issue has been reported to the responsible teams, and fixes for the affected packages are planned for a future UniFi OS Server release.

Requirements

• Linux host
• Docker Engine
• Docker Compose plugin
• Free host ports for UniFi OS Server
• Persistent storage for UniFi data

Check Docker Compose availability:

docker compose version

Technical Build Flow

flowchart TD
    A["docker/build.sh"] --> B["Load configuration"]
    B --> C["Resolve installer URLs"]
    C --> D["Validate requested platforms"]
    D --> E["For each platform: amd64 / arm64"]

    subgraph ARCH_BUILD["Per-architecture build"]
        direction TB
        F["1 · Build extractor image"]
        G["2 · Run extractor container"]
        H["Run official Ubiquiti installer"]
        I["Installer imports internal uosserver image into Podman"]
        J["Export /output/uosserver.tar"]
        K["3 · Load extracted image into Docker"]
        L["Tag uosserver:version-arch"]
        M["4 · Build runtime image"]
        N["Final image: image:version-arch"]
        O["5 · Validate runtime image"]
        P["Write provenance metadata"]

        F --> G --> H --> I --> J --> K --> L --> M --> N --> O --> P
    end

    E --> ARCH_BUILD
    P --> Q{"PUSH = true?"}

    Q -->|No| R["Keep local images only"]
    Q -->|Yes| S["Push architecture images"]

    S --> T{"Single arch or multi arch?"}
    T -->|Single arch| U["Tag and push: version + latest"]
    T -->|Multi arch| V["Create and push Docker manifests: version + latest"]

    R --> W["Build complete"]
    U --> W
    V --> W

flowchart TB
    subgraph HOST["Docker host / CI runner"]
        direction TB
        A["docker/build.sh"] --> B["Dockerfile.extractor"]
        B --> C["Extractor image"]

        subgraph EXTRACTOR["Extractor container"]
            direction TB
            D["Official UniFi OS Server installer"]
            E["Installer runs non-interactively"]
            F["Podman storage"]
            G["Internal uosserver image"]
            H["Exported archive: /output/uosserver.tar"]

            D --> E --> F --> G --> H
        end

        C --> EXTRACTOR
        H --> I["docker load"]
        I --> J["Extracted base image: uosserver:version-arch"]
        J --> K["Dockerfile.runtime"]
        K --> L["Runtime image: image:version-arch"]
        L --> M["Runtime validation"]
        M --> N["Push arch image"]
        N --> O["Multi-arch manifest: version + latest"]
    end

GitHub Actions Automation

This repository includes two GitHub Actions workflows:

• check-updates.yml
• docker-build.yml

check-updates.yml

• Runs on schedule and manual dispatch
• Checks the official Ubiquiti download API for a new Linux x64/arm64 release pair
• Is resilient to temporary API outages/timeouts (skips safely instead of failing the whole workflow)
• Dispatches docker-build.yml with a pinned release version and pinned installer URLs

docker-build.yml

Manual dispatch supports these inputs:

Build safety rules:

• Build version extraction fails hard if no valid semantic version is found
• amd64 and arm64 versions must match before publishing a multi-arch manifest
• Release metadata updates normalize name, draft, and prerelease

Publishing behavior in GitHub Actions:

• Per-architecture jobs push :<version>-amd64 and :<version>-arm64
• :<version> is created only by the manifest job after both architectures succeed
• :latest is updated only when promote_latest resolves to true
• Manual dispatch currently exposes only the multi-architecture platform pair

Release notes behavior:

• GitHub Releases include an "Official UniFi Release Notes" section
• Notes are fetched from Ubiquiti metadata + UniFi Community GraphQL data
• External note fetch calls use explicit request timeouts

Security scan behavior:

• Trivy always runs for HIGH and CRITICAL
• Default mode is non-blocking (enforce_trivy_gate=false) due to upstream vendor CVEs
• Set enforce_trivy_gate=true to make findings blocking

Quick Start

1. Clone or enter the project directory

cd unifi-os-server

2. Create persistent data directories

mkdir -p data/{persistent,var-log,data,srv,var-lib-unifi,var-lib-mongodb,etc-rabbitmq-ssl}

3. Configure UOS_SYSTEM_IP

Edit docker-compose.yaml and set the address that UniFi devices should use to reach this server.

environment:
  - UOS_SYSTEM_IP=unifi.example.com

You can use either a DNS name or an IP address.

4. Start UniFi OS Server

docker compose up -d

5. Open the web interface

https://<your-host>:11443

Runtime Settings

The provided docker-compose.yaml already includes the required runtime settings.

These settings are required for UniFi OS Server to start and shut down correctly:

• cgroup: host
• NET_RAW
• NET_ADMIN
• systemd-compatible tmpfs mounts
• persistent data mounts under ./data/...
• correct stop signal handling
• required TCP and UDP port mappings

Do not remove these settings unless you know exactly which UniFi OS component no longer needs them.

Important Environment Variables

UOS_SYSTEM_IP

Address used by UniFi devices and controllers to reach the server.

environment:
  - UOS_SYSTEM_IP=unifi.example.com

HARDWARE_PLATFORM

Optional setting for Synology-specific runtime patches.

environment:
  - HARDWARE_PLATFORM=synology

Use this only when running on Synology hardware or when the documented Synology patch behavior is required.

UOS_SHOW_JOURNAL

Controls whether the full systemd journal is forwarded to Docker logs. The default is false, so docker logs shows only the startup banner and entrypoint summary. Set it to true for verbose service logs.

environment:
  - UOS_SHOW_JOURNAL=true

Ports

The Compose file already defines the required port mappings.

Commonly used ports:

Optional services may expose additional ports depending on your UniFi setup. Unused optional mappings can be removed from docker-compose.yaml.

Updating

Pull the latest image and recreate the container:

docker compose pull
docker compose up -d

Persistent data under ./data/... remains intact.

Stopping

Stop the container:

docker compose down

This does not delete persistent data.

Troubleshooting

Device adoption does not work

Check the following:

• UOS_SYSTEM_IP points to the correct reachable hostname or IP address
• 8080/tcp is reachable from the device network
• 3478/udp is not blocked by a firewall or NAT
• 10003/udp is available if discovery is required
• the host firewall allows the mapped ports

Web interface is not reachable

Check container status:

docker compose ps

Check logs:

docker compose logs -f

Verify that the host port is listening:

ss -tulpen | grep 11443

Data Persistence

Persistent data is stored below:

./data/

Do not delete this directory unless you intentionally want to reset UniFi OS Server data.

Recommended backup target:

./data/

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Ubiquiti Inc. UniFi and Ubiquiti are trademarks or registered trademarks of Ubiquiti Inc.

License

See LICENSE.