How to install the UniFi Controller on Ubuntu

POST UP TO DATE 19/08/2015

Ubiquiti UniFi is properly supported on Ubuntu and Debian, breaking away from being Windows only. Being on Linux also reduces a lot of overhead that Windows typically laid on. The installation instructions provided by Ubiquiti aren't the best so here's my take on it.

I will be using a freshly installed Ubuntu 14.04.1 LTS. I previously had issues on installing to a dirty Ubuntu image I've been using as a do-it-all template. There is a section below where I was able to work out those issues though if you are also facing them.

Add the repository and GPG keys

To install the controller you will need to add the Ubiquiti repository to your apt sources list. This one liner does that for you:

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

Next you will need to add the GNU Privacy Guard (GPG) keys for UniFi and MongoDB (used to store your users and WiFi statistics within the UniFi controller). The GPG keys verifies the genuinity of who you will be downloading from during the installation. Here's another one liner to add both (Ubiquiti first then MongoDB):

sudo apt-key adv --keyserver keyserver.ubuntu.com --recv C0A52C50 && sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10

Now perform update to ensure Ubuntu recognises the repository:

sudo apt-get update

Install UniFi

Finally the big moment - installing the UniFi controller.

sudo apt-get install unifi -y

It will install a bunch of dependencies with it including Java 6, MongoDB, Tomcat and a Java SSL certificate tool.

As of August, the unifi-beta and unifi-rapid packages are obsolete.

Access the web interface

If everything went smoothly you should be able to access the controller through your web browser: https://unifi-server-here:8443

Depending on the version installed, you will be taken to the setup wizard. You're done!

Problems

Determine the problem

A good start would be to go through the system logs and google the issue:

cat /var/log/unifi/server.log

Restart UniFi

Just like any other service in Ubuntu, UniFi can be stop, started and restarted.

# to stop the controller
$ sudo service unifi stop

# to start the controller
$ sudo service unifi start

# to restart the controller
$ sudo service unifi restart

# to view the controller's current status
$ sudo service unifi status

Java Home not found

This issue can be tricky. UniFi cannot access Java to run Tomcat (its web server). To check if you have Java, simply run:

java -version

If nothing appears you do not have Java. The latest version of UniFi supports Java 8. To install Java, follow this guide from Digital Ocean.

If you do have Java (or installed it now), you will have to edit the UniFi startup script to point out the location of Java. Open the startup script:

sudo editor /etc/init.d/unifi

Change the 'JAVA_HOME' location to your new Java location:

JAVA_HOME=/opt/jdk/jdk1.8.0_XX

Keystore file missing / java.io.FileNotFoundException

When going through the log file you may find the error:

java.io.FileNotFoundException: /usr/lib/unifi/data/keystore (No such file or directory)

This error means that the 'keystore' file is missing, resulting in Tomcat not being able to start up. The keystore file is responsible for encrypting your connection (HTTPS/SSL).

Generate a new keystore file, answering blank to every question including password:

sudo keytool -genkey -keyalg RSA -alias selfsigned -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise -validity 365 -keysize 2048 -destalias unifi

Restart UniFi when successful and try accessing the web interface again.

sudo service unifi restart