Installing Ubiquiti's UniFi Controller on Ubuntu

Last week I had to install a UniFi Controller on a Raspberry Pi 3B running Ubuntu 18. Despite the belief that this would not be good enough for a small amount of machines and the rate of pay I was making, I did it anyways.

The following instructions will work for Ubuntu 16 - 18 on both x86_64 devices and armhf devices.


  • A VM or Dedicated Machine with:
    • Gigabit Networking (100MB Minimum)
    • 4GB of RAM (2GB Minimum)
    • 4 Cores (2 Minimum)
    • A x86_64 Proccessor (ARM is Minimum)
    • 20GB of Free Space (10GB Minimum)

From Ubiquiti’s Support Page
NOTE: Actual Storage, CPU, RAM, and Network speed requirements will depend on many factors including the number of UniFi devices managed by the controller, number of clients, features enabled, and data retention settings. For database repair, you require free space equal to the current database size, plus 2GB.

Step 1 - Specific Instructions?

If Your Installing This On A Raspberry Pi-like Device

Make sure your installing this with a fresh install of Raspian or Ubuntu Server.
SSH into your Pi and take care of the first-time setup stuff like expanding your file system and renaming your pi for your local network. Make sure to assign a static IP while your at it.

sudo raspi-config # Expand File System, Set Static IP, Rename the Pi 
sudo reboot now

After this, you may continue the guide.

If Your Installing This On A Normal Server

I recommend you don’t run anything you don’t have to on this server. You should dedicate this server just to your controller software.

To set your server to a static IP, I recommend setting up a static ip in your dhcp server or you can change Ubuntu’s interfaces file to use one. I recommend HowToGeek’s Article on How to implement a static ip address on Ubuntu.

You may continue to Step 2.

Step 2 - Updating and Installing UniFi Controller
First as all tutorials go, update your system as follows.

sudo apt update # Check for new repository updates.
sudo apt upgrade -y # Update any outdated packages automagically.

Next, we need to install some dependencies required by the UniFi Controller.
UniFi depends on the OpenJDK 8 Headless JRE and MongoDB

You can install them as follows:

sudo apt install -y openjdk-8-jre-headless mongodb-server

We now need to disable mongodb to save system resources, because UniFi runs its own copy.

sudo service mongodb stop
sudo service mongodb disable

Lets now add Ubiquiti’s Source to our APT Lists and install the controller software.

echo "deb stable ubiquiti" | sudo tee /etc/apt/sources.list.d/100-ubnt.list
sudo apt-key adv --keyserver --recv C0A52C50
sudo apt-get update
sudo apt install -y unifi

Before we do anything with UniFi, we want to setup log rotation to avoid disk space issues because sometimes these logs can get pretty big.

sudo wget -O /etc/logrotate.d/unifi

We now need to generate a CSR, if you know how you can generate a certificate using your own CA, you can or you can buy a certificate from a public Certificate Authority (CA). You could also

sudo java -jar /usr/lib/unifi/lib/ace.jar new_cert "My Company Name" City State Country

The CSR (Certificate Signing Request) will be placed here: /var/lib/unifi/unifi_certificate.csr.pem.

If you got your certificates generated, you should move them here: /var/lib/unifi/.
And you can import them like so:

cd /var/lib/unifi
sudo java -jar /usr/lib/unifi/lib/ace.jar import_cert unifi_certificate.cert.pem intermediate.cert.pem root.cert.pem
sudo service unifi restart

You may not have a intermediate, so your mileage may very.

(Optional) Step 3 - Access the controller on web ports.
We can make it so we can access the UniFi Controller on port 80 & 443 instead of the 8443 we normally would of used. Thanks to IPTables we can do this because there is no native configuration from the UniFi configuration to do this.

We need to install iptables and iptables-persistent.

sudo apt install iptables iptables-persistent

We can then install these rules to pre route, all traffic to the new ports.

sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443

Step 4 - Continue installation through the panel.

If you did step 3, you can now access your panel using your domain.
https://<YOUR DOMAIN>.com
If you did not, and did not setup SSL, you can access your panel at 8080 or 8443 if you did secure the panel.

Your done! Go celebrate!

1 Like

Are you certain mongodb has to be separately installed in step 2?

Specifically, no. The UniFi install adds this automatically, but I have seen some cases where its just better to add it before installing the controller because it throws out missing dependencies errors. Specifically for the Raspberry Pi’s.