How to Install UniFi Network Controller on Raspberry Pi

Ben
Ben
@benjislab

For network administrators and tech enthusiasts managing Ubiquiti networking equipment, running the UniFi Network Controller is essential. While Ubiquiti offers dedicated hardware controllers, you can save costs and gain flexibility by hosting the controller software on a Raspberry Pi. At Fleetstack, we understand the importance of efficient device management, and a self-hosted UniFi Controller fits perfectly with our philosophy of smart IoT deployment.

This guide will walk you through the complete process of installing and configuring the UniFi Network Controller on a Raspberry Pi, creating a reliable, low-power solution for managing your network infrastructure.

Why Run UniFi Controller on a Raspberry Pi?

Before diving into the installation, let's consider the benefits:

  • Cost-effective: Much cheaper than purchasing a dedicated UniFi Cloud Key or Dream Machine
  • Energy efficient: Raspberry Pi consumes minimal power compared to a traditional server
  • Always-on management: Provides continuous monitoring and management of your network
  • Local control: Keep your network configuration data on your premises
  • Scalable: Can manage multiple sites and dozens of devices from a single Pi
  • Integrates with other services: Can run alongside other applications with proper resource allocation

Hardware Requirements

To follow this tutorial, you'll need:

  • Raspberry Pi 4 (2GB RAM minimum, 4GB or 8GB recommended for larger networks)
  • Power supply (official 15W USB-C recommended)
  • microSD card (32GB or larger recommended)
  • Ethernet connection (Wi-Fi setup is possible but not recommended for reliability)
  • Optional: Case with cooling solution (especially for 24/7 operation)

Prerequisites

This guide assumes you have:

  • Basic familiarity with Linux command line
  • Access to your Raspberry Pi via SSH or direct connection
  • Your Pi connected to the same network as your UniFi devices
  • Raspberry Pi OS (64-bit recommended) already installed

Step-by-Step Installation Guide

1. Update Your System

Begin by ensuring your Raspberry Pi is fully updated:

sudo apt update
sudo apt upgrade -y

2. Install Required Dependencies

The UniFi Controller requires Java and several other dependencies:

sudo apt install -y openjdk-8-jre-headless jsvc libcommons-daemon-java

3. Add the UniFi Repository

To access the official Ubiquiti repository, add their source:

echo 'deb https://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.list

4. Add the Repository GPG Key

Add the Ubiquiti GPG key to verify package authenticity:

wget -O /tmp/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg
sudo apt-key add /tmp/unifi-repo.gpg

5. Install MongoDB

UniFi Controller requires MongoDB, but Ubiquiti recommends a specific version:

sudo apt install -y mongodb-server

6. Install the UniFi Controller

Now install the UniFi Network Controller:

sudo apt update
sudo apt install -y unifi

The installation may take several minutes depending on your internet speed and Pi's performance.

7. Check the Service Status

Verify that the UniFi service is running:

sudo systemctl status unifi

You should see output indicating that the service is active and running.

8. Configure Firewall Rules (Optional but Recommended)

If you're using ufw (Uncomplicated Firewall), allow the necessary ports:

sudo apt install -y ufw
sudo ufw allow 8443/tcp # Web interface
sudo ufw allow 8080/tcp # Device communication
sudo ufw allow 3478/udp # STUN service
sudo ufw allow 10001/udp # Device discovery
sudo ufw allow 1900/udp # L2 discovery
sudo ufw allow ssh # SSH access (important!)
sudo ufw enable

9. Access the Controller Interface

Once installation is complete, you can access the UniFi Controller web interface by opening a browser and navigating to:

https://raspberry-pi-ip:8443

Replace "raspberry-pi-ip" with your Pi's actual IP address. You'll likely encounter a security warning about the SSL certificate – this is normal for a self-hosted service. You can safely proceed.

10. Initial Setup

Follow the on-screen wizard to set up your controller:

  1. Create an administrator account
  2. Set up your first wireless network
  3. Configure your site details
  4. Adopt your UniFi devices

Optimizing Your UniFi Controller on Raspberry Pi

Memory Management

The UniFi Controller can be memory-intensive. Modify the Java memory allocation to optimize performance:

sudo nano /usr/lib/unifi/data/system.properties

Add the following line to limit memory usage:

unifi.xms=512
unifi.xmx=1024

This sets minimum memory to 512MB and maximum to 1GB. Adjust according to your Pi model and network size.

Setting Up Automatic Backups

Configure automatic backups to prevent data loss:

  1. Create a backup directory:
sudo mkdir -p /home/pi/unifi-backups
  1. Create a backup script:
sudo nano /home/pi/backup-unifi.sh
  1. Add the following content:
#!/bin/bash
DATE=$(date +%Y-%m-%d_%H-%M)
BACKUP_DIR="/home/pi/unifi-backups"
UNIFI_DIR="/usr/lib/unifi/data/backup/autobackup"
LATEST_BACKUP=$(ls -t $UNIFI_DIR | head -1)
cp $UNIFI_DIR/$LATEST_BACKUP $BACKUP_DIR/unifi_backup_$DATE.unf
find $BACKUP_DIR -name "unifi_backup_*" -type f -mtime +30 -delete
  1. Make the script executable:
sudo chmod +x /home/pi/backup-unifi.sh
  1. Add a cron job to run the backup daily:
(crontab -l 2>/dev/null; echo "0 2 * * * /home/pi/backup-unifi.sh") | crontab -

Improving System Stability

To enhance the long-term stability of your controller:

  1. Enable automatic security updates:
sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure unattended-upgrades
  1. Add a watchdog to restart the service if it fails:
sudo nano /etc/systemd/system/unifi-watchdog.service

Add the following content:

[Unit]
Description=UniFi Controller Watchdog
After=network.target

[Service]
Type=simple
ExecStart=/bin/bash -c 'while true; do if ! systemctl is-active --quiet unifi; then systemctl restart unifi; fi; sleep 300; done'
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
  1. Enable and start the watchdog:
sudo systemctl enable unifi-watchdog
sudo systemctl start unifi-watchdog

Managing Your UniFi Controller with Fleetstack

If you're deploying multiple Raspberry Pi-based UniFi Controllers across different sites, Fleetstack can help you:

  1. Monitor system health: Track CPU, memory, and storage usage to ensure optimal performance
  2. Manage software updates: Deploy controller updates across your entire fleet
  3. Track device inventory: Keep tabs on all your controllers and connected network devices
  4. Configure remote access: Securely access your controllers from anywhere
  5. Set up alerts: Get notified of potential issues before they affect network operations

Troubleshooting Common Issues

Controller Won't Start

If the controller service fails to start:

sudo systemctl status unifi

Look for error messages in the output. Common issues include:

  • Java memory problems: Adjust memory settings as described in the optimization section
  • MongoDB issues: sudo systemctl restart mongodb
  • Port conflicts: Ensure no other service is using required ports

Devices Won't Adopt

If your UniFi devices aren't being detected or won't adopt:

  1. Ensure the devices are on the same subnet as your controller
  2. Try manual adoption using the device IP address
  3. Reset devices to factory settings if necessary
  4. Check firewall rules to ensure required ports are open

Performance Issues

If your controller becomes sluggish:

  1. Check system resources: htop
  2. Consider increasing swap space:
sudo dphys-swapfile swapoff
sudo nano /etc/dphys-swapfile
# Edit CONF_SWAPSIZE=2048 (or desired size in MB)
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Security Considerations

When running a network controller, security is paramount:

  1. Change default credentials: Use strong passwords for both your Pi and UniFi accounts
  2. Enable SSH key authentication: Disable password authentication for SSH
  3. Use a dedicated Pi: Don't run other high-risk services on the same device
  4. Consider a reverse proxy: Use Nginx with Let's Encrypt for proper SSL
  5. Regular updates: Keep both your Pi and the UniFi Controller updated
  6. Network isolation: Consider placing the controller on a management VLAN

Conclusion

Running the UniFi Network Controller on a Raspberry Pi offers an excellent balance of cost-effectiveness, performance, and flexibility. With proper setup and maintenance, your Pi can reliably manage dozens of UniFi devices across multiple sites.

At Fleetstack, we specialize in helping organizations manage their IoT device fleets efficiently. Whether you're running a single controller for your home network or dozens across multiple business locations, proper device management is key to reliable network operations.