How to install the Unifi Cloud Appliance

Installing the Unifi cloud appliance can be a lot of fun, especially if you read Ubiquiti’s disclaimers where they basically use as much anti-sysadmin language as possible to put you off.

But in reality they could have just provided basic instructions and we’d all be happily running the appliance.

This is a real world installation done in September 2022.

The date is important because if you look at their documentation is seems it was created in 2016. There are a number of serverely outdated dependencies for their software but if you want to get it working you have to live with it. For example, MongoDB 3.6 end of life was April 2021, but their .DEB file insists on having a version lower than 4.0. So save yourself a lot of trouble and choose an older operating system.

The VM for this appliance was 2vCPU and 2GB RAM. The end-user wanted around 30 devices. We’ll update this document if this spec wasn’t enough, because the documentation from UBNT make you think you need a mainframe.

So here are the easy instructions:

Install Ubuntu 18.04

Minimal installation

Ignore their notes on UFW. UFW comes with Ubuntu but it’s not enabled on that version.

Install MongoDB 3.6

Instructions from here.

sudo apt-key adv --keyserver hkp:// --recv 2930ADAE8CAF5059EE73BB4B58712A2291FA4AD5
echo "deb [ arch=amd64,arm64 ] xenial/mongodb-org/3.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list
sudo apt-get update
sudo apt-get install -y mongodb-org mongodb-org-server
sudo systemctl start mongod
sudo systemctl status mongod
sudo systemctl enable mongod

Install Java 8

sudo apt-get install openjdk-8-jdk

Install Binutils

sudo apt-get install binutils

Install Unifi

Download Unifi

dpkg -i downloaded.DEB

Now continue the installation:


Ignore SSL warning Tomcat doesn’t have it by default.

By default the appliance wants to use a Unifi cloud username and password, but by checking the advanced box and then unchecking remote boxes you can bypass that.


Most likely you’re trying to install the appliance using the incorrect versions of software. Stick with the formula above.

Other Linux troubleshooting commands:

Check service status:

service unifi status

Check server log file:

tail -f /usr/lib/unifi/logs/server.log

There are more logs in the above location, for example the remote directory has logs and MongoDB also writes there.

Check if you have a swap file and enough RAM:

free -m

Typical Server Errors

WARN system - Country Code is not configured for Site with ID=

WARN sanitize - Invalid key exists in Setting payload, key=interval

ERROR api - Failed to update permissions: I/O error on POST request for "http://localhost:11081/api/permissions/network": Connect to localhost:11081

Leave us a comment about your experiences installing the Ubiquiti Unifi appliance on your self hosted environment.



Share this article

Leave a Reply

Your email address will not be published. Required fields are marked *

Scroll to Top