UniFi Network Controller on Raspberry Pi: Complete 2026 Setup Guide

Step 1 — Install Raspberry Pi OS

Use Raspberry Pi OS Lite (Bookworm, 64-bit) — no desktop, less bloat. Flash it via the official Pi Imager. In the Imager’s “Advanced options” (gear icon):

• Set hostname (e.g., unifi-controller)
• Enable SSH
• Set username/password
• Configure your Wi-Fi if needed (or skip and use ethernet)
• Set locale/timezone

Boot the Pi, SSH in: ssh [email protected]

Step 2 — Update + base packages

sudo apt update && sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl gnupg apt-transport-https

Step 3 — Install Java 17 (required by UniFi 8.x)

UniFi Network Application 8.x requires Java 17. Java 7/8/11 will not work:

sudo apt install -y openjdk-17-jre-headless
java -version  # should show "17.x"

Step 4 — Install MongoDB

MongoDB doesn’t ship a native ARM64 build for newer versions on Debian, so we use the version bundled in Pi OS (compatible with UniFi 8.x):

sudo apt install -y mongodb-server-core

Step 5 — Add Ubiquiti’s APT repo (modern GPG keyring method)

The old apt-key command is deprecated since Debian 11. Use the new keyring method:

# Download Ubiquiti's signing key into the modern keyring location
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://dl.ui.com/unifi/unifi-repo.gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/unifi.gpg

# Add the repo (signed-by points to our keyring)
echo "deb [signed-by=/etc/apt/keyrings/unifi.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti" | \
  sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

sudo apt update

Step 6 — Install UniFi Network Application

sudo apt install -y unifi
sudo systemctl enable unifi
sudo systemctl start unifi

# Watch it start (first run takes 60-90 seconds)
sudo journalctl -u unifi -f

When you see Starting unifi: STARTED, hit Ctrl+C and visit https://<pi-hostname-or-ip>:8443 in your browser. You’ll get a self-signed cert warning — accept it, then walk through the UniFi setup wizard.

Step 7 — Verify the service is listening

netstat is deprecated in modern Pi OS. Use ss:

sudo ss -tlnp

You should see UniFi listening on these ports:

• 8080 — device communication (UDP also)
• 8443 — admin web UI (HTTPS)
• 8843 — guest portal HTTPS
• 8880 — guest portal HTTP redirect
• 27117 — UniFi-bundled MongoDB (localhost only)

Step 8 — Log rotation (optional but recommended)

UniFi logs to /var/log/unifi/ and grows fast. Add log rotation:

sudo tee /etc/logrotate.d/unifi > /dev/null <<'EOF'
/var/log/unifi/*.log {
    daily
    rotate 7
    missingok
    compress
    delaycompress
    notifempty
    copytruncate
}
EOF

Bonus 1 — HTTPS on port 443 (instead of :8443)

Tired of typing :8443? Redirect ports 80 → 8080 and 443 → 8443 with nftables (modern replacement for iptables on Bookworm):

sudo apt install -y nftables
sudo systemctl enable --now nftables

sudo tee /etc/nftables.conf > /dev/null <<'EOF'
#!/usr/sbin/nft -f
flush ruleset

table inet nat {
    chain prerouting {
        type nat hook prerouting priority dstnat;
        tcp dport 80 redirect to :8080
        tcp dport 443 redirect to :8443
    }
}
EOF

sudo systemctl restart nftables

Now https://unifi-controller.local works without the port. Verify with sudo nft list ruleset.

Bonus 2 — Replace the self-signed cert

The browser warning gets old. Two paths depending on whether your controller is reachable from the internet:

Option A — Let’s Encrypt (controller exposed to internet)

Use the popular le-unifi-os script or certbot + manual import. The certificate import flow:

sudo apt install -y certbot
sudo certbot certonly --standalone -d unifi.example.com

# Import into UniFi's Java keystore
cd /var/lib/unifi
sudo java -jar /usr/lib/unifi/lib/ace.jar import_cert \
  /etc/letsencrypt/live/unifi.example.com/fullchain.pem \
  /etc/letsencrypt/live/unifi.example.com/privkey.pem
sudo systemctl restart unifi

Then add a cron job to auto-renew + re-import every 60 days.

Option B — Internal CA (LAN-only controller)

Generate a CSR, sign it with your homelab CA (or use mkcert for laptop-trusted certs), then import:

cd /usr/lib/unifi
sudo java -jar lib/ace.jar new_cert \
  unifi.lan "Mustafa Homelab" Dubai DXB AE
# Sign the CSR at /var/lib/unifi/unifi_certificate.csr.pem
# Then import the resulting cert + chain
sudo java -jar lib/ace.jar import_cert \
  /var/lib/unifi/unifi.cert.pem \
  /var/lib/unifi/intermediate.cert.pem \
  /var/lib/unifi/root.cert.pem
sudo systemctl restart unifi

Bonus 3 — Auto-backups

Configure UniFi to auto-backup to an external location. In the UI: Settings → System → Backup → Auto Backup → Enable. Then sync /var/lib/unifi/backup/autobackup/ to a NAS or cloud:

# Daily rsync to a Synology / NAS at 3am
sudo crontab -e
# Add:
0 3 * * * rsync -a /var/lib/unifi/backup/autobackup/ [email protected]:/volume1/backups/unifi/

Common issues

Alternatives to a Pi controller

• UniFi Cloud Key Gen2 / Plus — official appliance, $200, just works, but you’re paying for a glorified Pi with a UPS battery
• UniFi Dream Machine SE / Pro — gateway + controller in one, $400-700, ideal if you also need a router upgrade
• Docker on a NAS / homelab — linuxserver/unifi-network-application image runs anywhere Docker does. Great if you already have a Synology / Proxmox server
• Standalone mode (no controller) — for 1-3 APs at home, see our UniFi standalone guide

FAQ

Related guides

• 📡 Setup UniFi AP standalone (no controller needed)
• 🛜 UniFi WiFi 6 vs WiFi 7 comparison
• 🐳 Install Portainer on Synology (great companion for managing the UniFi Docker option)

Last updated: 2026-04-22. Tested on Raspberry Pi 5 8GB running Pi OS Bookworm 64-bit, Java 17, UniFi Network Application 8.5.