UniFi OS Server on Debian Linux

README.md

UniFi OS Server on Debian (Podman)

Deploys UniFi OS Server in a Podman container on Debian.

---

Requirements

• Debian 12 or 13
• Root access
• Internet access

---

Install

chmod +x install-unifi.sh
sudo ./install-unifi.sh

The script will:

• Install Podman
• Create required directories under /opt/unifi-os-server
• Pull the container image
• Start the container

---

Access

https://<server-ip>:11443

Complete setup via the web UI.

---

Update

chmod +x update-unifi.sh
sudo ./update-unifi.sh

Pulls the latest image, replaces the running container, and leaves all data intact. Does not reinstall Podman or recreate directories.

---

Directory Structure

/opt/unifi-os-server/
├── data/               # UniFi application data
├── persistent/         # Persistent config
├── srv/
├── var-lib-mongodb/    # MongoDB data
├── var-lib-unifi/      # UniFi library data
├── var-log/            # Logs
└── etc-rabbitmq-ssl/   # RabbitMQ SSL certs

---

Ports

Port	Protocol	Purpose
11443	TCP	Web UI (HTTPS)
8443	TCP	UniFi HTTPS
8080	TCP	Device inform
8880	TCP	HTTP portal redirect
8881	TCP	HTTPS portal
8882	TCP	HTTPS portal alt
8444	TCP	Portal HTTPS
9543	TCP	UniFi Talk
6789	TCP	Speed test
5671	TCP	MQTT (TLS)
5005	TCP	Remote debug
11084	TCP	UniFi Talk TURN
3478	UDP	STUN
5514	UDP	Syslog
10003	UDP	Throughput

---

Basic Commands

Command	Purpose
podman ps	Running containers
podman ps -a	All containers
podman logs unifi-os-server	View logs
podman restart unifi-os-server	Restart
podman stop unifi-os-server	Stop

---

Auto Start

The container runs with --restart=always and will restart automatically after a reboot if Podman's restart policy is honoured by the init system.

For explicit systemd management:

podman generate systemd --name unifi-os-server --files --new
mv container-unifi-os-server.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now container-unifi-os-server

---

Notes

• Do not install the unifi apt package on Debian 12/13 — it conflicts
• MongoDB runs inside the container; no host MongoDB needed
• Host firewall must allow the ports listed above

---

Troubleshooting

Container not running

podman ps -a
podman logs unifi-os-server

Check for port conflicts

ss -tulnp | grep 11443

install-unifi.sh

#!/bin/bash

set -e

if [[ $EUID -ne 0 ]]; then
    echo "Error: must be run as root" >&2
    exit 1
fi

ContainerName="unifi-os-server"
Image="ghcr.io/lemker/unifi-os-server:latest"
BaseDir="/opt/unifi-os-server"

# -- Install -------------------------------------------------------------------

echo "== Installing Podman =="
apt update
apt install -y podman

echo "== Enabling Podman restart on boot =="
systemctl enable --now podman-restart.service

# -- Directories ---------------------------------------------------------------

echo "== Creating directories =="
mkdir -p \
    "$BaseDir/persistent" \
    "$BaseDir/var-log" \
    "$BaseDir/data" \
    "$BaseDir/srv" \
    "$BaseDir/var-lib-unifi" \
    "$BaseDir/var-lib-mongodb" \
    "$BaseDir/etc-rabbitmq-ssl"

# -- Container -----------------------------------------------------------------

echo "== Pulling image =="
podman pull "$Image"

echo "== Removing old container =="
podman rm -f "$ContainerName" 2>/dev/null || true

echo "== Creating container =="

TZ=$(cat /etc/timezone 2>/dev/null || timedatectl show -p Timezone --value 2>/dev/null || echo "UTC")

podman run -d \
    --name "$ContainerName" \
    --restart=always \
    --cgroupns=host \
    --cap-add=NET_ADMIN \
    --cap-add=NET_RAW \
    --tmpfs /run:exec \
    --tmpfs /run/lock \
    --tmpfs /tmp:exec \
    --tmpfs /var/lib/journal \
    --tmpfs /var/opt/unifi/tmp:size=64m \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -v "$BaseDir/persistent:/persistent" \
    -v "$BaseDir/var-log:/var/log" \
    -v "$BaseDir/data:/data" \
    -v "$BaseDir/srv:/srv" \
    -v "$BaseDir/var-lib-unifi:/var/lib/unifi" \
    -v "$BaseDir/var-lib-mongodb:/var/lib/mongodb" \
    -v "$BaseDir/etc-rabbitmq-ssl:/etc/rabbitmq/ssl" \
    -e TZ="$TZ" \
    -e UOS_SYSTEM_IP="$(hostname -I | awk '{print $1}')" \
    -p 8443:8443 \
    -p 11443:443 \
    -p 8080:8080 \
    -p 3478:3478/udp \
    -p 10003:10003/udp \
    -p 6789:6789 \
    -p 5005:5005 \
    -p 9543:9543 \
    -p 8444:8444 \
    -p 5514:5514/udp \
    -p 11084:11084 \
    -p 5671:5671 \
    -p 8880:8880 \
    -p 8881:8881 \
    -p 8882:8882 \
    "$Image"

echo "== Done =="
echo "Access: https://<server-ip>:11443"

update-unifi.sh

#!/bin/bash

set -e

if [[ $EUID -ne 0 ]]; then
    echo "Error: must be run as root" >&2
    exit 1
fi

ContainerName="unifi-os-server"
Image="ghcr.io/lemker/unifi-os-server:latest"
BaseDir="/opt/unifi-os-server"

# -- Update --------------------------------------------------------------------

echo "== Pulling latest image =="
podman pull "$Image"

echo "== Stopping and removing old container =="
podman stop "$ContainerName" 2>/dev/null || true
podman rm "$ContainerName" 2>/dev/null || true

echo "== Starting updated container =="

TZ=$(cat /etc/timezone 2>/dev/null || timedatectl show -p Timezone --value 2>/dev/null || echo "UTC")

podman run -d \
    --name "$ContainerName" \
    --restart=always \
    --cgroupns=host \
    --cap-add=NET_ADMIN \
    --cap-add=NET_RAW \
    --tmpfs /run:exec \
    --tmpfs /run/lock \
    --tmpfs /tmp:exec \
    --tmpfs /var/lib/journal \
    --tmpfs /var/opt/unifi/tmp:size=64m \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -v "$BaseDir/persistent:/persistent" \
    -v "$BaseDir/var-log:/var/log" \
    -v "$BaseDir/data:/data" \
    -v "$BaseDir/srv:/srv" \
    -v "$BaseDir/var-lib-unifi:/var/lib/unifi" \
    -v "$BaseDir/var-lib-mongodb:/var/lib/mongodb" \
    -v "$BaseDir/etc-rabbitmq-ssl:/etc/rabbitmq/ssl" \
    -e TZ="$TZ" \
    -e UOS_SYSTEM_IP="$(hostname -I | awk '{print $1}')" \
    -p 8443:8443 \
    -p 11443:443 \
    -p 8080:8080 \
    -p 3478:3478/udp \
    -p 10003:10003/udp \
    -p 6789:6789 \
    -p 5005:5005 \
    -p 9543:9543 \
    -p 8444:8444 \
    -p 5514:5514/udp \
    -p 11084:11084 \
    -p 5671:5671 \
    -p 8880:8880 \
    -p 8881:8881 \
    -p 8882:8882 \
    "$Image"

echo "== Done =="
echo "Access: https://<server-ip>:11443"