How to Install and Run UniFi Controller on a Raspberry Pi: Complete Guide
Sep 10,2025
How to Install the UniFi Controller on a Raspberry Pi
The Raspberry Pi UniFi Controller, now known as the UniFi Network Application, is Ubiquiti’s centralized platform for network management.The UniFi Controller, now known as the UniFi Network Application, is Ubiquiti’s centralized platform for network management. Through this software, administrators can set up, monitor, and fine-tune UniFi devices such as access points, switches, and security gateways from a unified web interface.
Running the UniFi Controller on a Raspberry Pi is an attractive alternative to Ubiquiti’s commercial Cloud Key, making it easy for beginners to install UniFi Controller on Raspberry Pi without expensive hardware. The Pi offers a low-power, cost-effective, and always-on solution that integrates seamlessly into home labs, small businesses, or even experimental setups for networking enthusiasts.
Typical use cases include:
• Coordinating several UniFi access points within a small office environment ensures seamless coverage and centralized Raspberry Pi network management.
• Experimenting with enterprise-grade WiFi management at home.
• Offering cost-efficient network control for startups or coworking spaces.
Requeriments
Hardware:
• Raspberry Pi 5 (2GB or 4GB RAM recommended, see the Get Started with Raspberry Pi tutorial)
• Official power supply (5V, 3A).
• MicroSD card (16GB or larger, Class 10) or SSD for better performance.
• Ethernet cable and stable network connection (check SunFounder's Static IP configuration guide to keep your Pi accessible).
Software:
• Raspberry Pi OS Lite (or 64-bit, download from the official Raspberry Pi OS page)
• UniFi Controller package.
• Java (OpenJDK 17).
• MongoDB (version 4.4 compatible with the UniFi release).
Installing Dependencies
1. Update your system:
sudo apt update && sudo apt upgrade -y
2. Install Java (OpenJDK 11):
sudo apt install openjdk-17-jre-headless -y
3. Install MongoDB (check compatibility with your UniFi version):
wget -qO - https://pgp.mongodb.com/server-4.4.asc | sudo apt-key add
-echo "deb [ arch=arm64,armhf ] https://repo.mongodb.org/apt/ubuntu/ focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
sudo apt update
sudo apt install mongodb -y
Start the MongoDB service:
sudo systemctl start mongod
Enable MongoDB to start on boot:
sudo systemctl enable mongod
Enable MongoDB to start on boot so the system is ready whenever you install UniFi Controller on Raspberry Pi.sudo systemctl enable mongod
4. Other required packages:
Other required packages (you can also explore the DaVinci Kit for Raspberry Pi if you want hardware practice):
sudo apt install apt-transport-https ca-certificates curl gnupg libssl1.1 -y
Installing UniFi Controller on Raspberry Pi
1. Add Ubiquiti’s repository and GPG key:
Add Ubiquiti's repository and GPG key (see the official Ubiquiti UniFi documentation for reference)
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/ubiquiti-archive-keyring.gpg] https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list >/dev/null
curl https://dl.ui.com/unifi/unifi-repo.gpg | sudo tee /usr/share/keyrings/ubiquiti-archive-keyring.gpg >/dev/null
2. Install the UniFi package:
sudo apt update
sudo apt install unifi -y
3. Verify installation:
Verify installation: The main files are stored in /var/lib/unifi and logs in /var/log/unifi/, giving you a full UniFi Cloud Key alternative Raspberry Pi setup.
The main files are stored in /var/lib/unifi and logs in /var/log/unifi/.
Accessing the Controller
Open a browser and go to: https://<your-pi-ip>:8443
Follow the setup wizard to create your first site and adopt UniFi devices. Optionally, enable remote access by linking your Ubiquiti account.
Skip the UI Account and create a local user.
Running UniFi Controller as a Service
The UniFi package installs as a systemd service by default.
• To check its status: sudo systemctl status unifi
• To enable at boot: sudo systemctl enable unifi
Backup and Maintenance
Create backups via the web interface under Settings → Backup.
Enable automatic backups to avoid losing configurations.
Update the UniFi Controller using:
sudo apt update && sudo apt upgrade -y
• Monitor logs for troubleshooting:
tail -f /var/log/unifi/server.log
Alternative: Docker Deployment (Optional)
Using Docker provides isolation and simplifies upgrades—refer to SunFounder’s Raspberry Pi Docker advanced tutorial for deeper insights.
1. Install Docker:
Install Docker (see the official Docker documentation for details)
curl -sSL https://get.docker.com | sh
2. Run a UniFi conteiner:
docker run -d --init \
--restart=unless-stopped \
-p 8080:8080 -p 8443:8443 -p 3478:3478/udp \
-v ~/unifi:/unifi \
--user unifi \
--name unifi \
jacobalberty/unifi
This ensures persistent data storage and easier upgrades.
Common Issues & Troubleshooting
Controller not starting: check systemctl status unifi for errors.
Run on terminal: journalctl -xeu unifi.service
Java or MongoDB mismatch: ensure UniFi version supports your installed versions.
Java: sudo java -version
MongoDB: mongod -version
High memory usage: Pi 3 may struggle—prefer Pi 4/5 with at least 2GB RAM.
Conclusion
Running the UniFi Controller on a Raspberry Pi is a practical and cost-effective solution for anyone who wants reliable network management without investing in expensive hardware like the UniFi Cloud Key or a dedicated server. With its low power consumption, always-on availability, and affordable price, the Raspberry Pi is well suited for home labs, small businesses, and networking enthusiasts. Whether installed natively or through Docker, the setup gives you full control over UniFi devices while keeping costs down. If you’re looking for a lightweight, flexible, and dependable way to manage your UniFi network, deploying it on a Raspberry Pi is one of the best options to try, and this guide serves as a complete UniFi Controller tutorial Raspberry Pi users can follow.
