Let’s Install Ubiquiti UniFi Network Controller on Linux Mint (Ubuntu/Debian)

The “Ubiquiti UniFi Network Controller” is a software application that runs on a UniFi OS Console or a self-hosted server and allows you to manage and monitor UniFi devices in your network, for example Routers, Switches, Access Points etc. In this article we shall focus on the self-hosted server option and by the end of this exercise, you will have setup a web portal which you can access remotely and use to configure, update, monitor, and troubleshoot UniFi devices in your network.

This tutorial will be based on Linux Mint (LM) as seen in the version screen shot below:

However, this tutorial can also be followed for installations on Ubuntu and Debian distributions because Linux Mint is based on Ubuntu, and Ubuntu is based on Debian as seen in the distro family tree below:

I will be running all the example commands with “sudo” privileges, so to avoid having to type “sudo” at every command, I typed “sudo su -” and entered my root password at the beginning of this exercise. Also seen from the snapshots is the # prompt instead of $ because i have root privileges to my server.

Step 1: Make sure your server has the latest software updates and patches installed, use the commands below to complete base software updates and patching.

Step 2: Let’s install some important packages that we shall rely on to install and run UniFi Network Controller and it’s dependencies.

You might already have some of these packages on your system, in which case you can skip this step. But if you are working on a new installation you definitely will need these packages; “curl”, “gpg”, “haveged”, “openjdk-8-jre-headless”.

Here is command you can run to check if you have these already installed on your server?

Here is a brief description of these packages so you can know what you are about to install:

Curl: is a Linux package that provides a command-line tool for transferring data from or to a server using various network protocols. Curl can be used to download or upload files, test APIs, communicate with web servers, and more. Curl supports protocols such as HTTP, HTTPS, FTP, SFTP, SCP, IMAP, POP3, SMTP, and others.

GPG: is a Linux package that provides a command-line tool for encrypting and decrypting files with a key. GPG stands for GNU Privacy Guard, which is an implementation of the OpenPGP standard for secure communication and data storage. GPG can be used to encrypt files with a shared symmetric key or with asymmetric key pairs (also known as public-key cryptography). To use GPG, you need to generate a key pair, which consists of a public key and a private key. The public key can be shared with anyone who wants to encrypt a file for you or verify your signature. The private key is kept secret and used to decrypt files or sign them.

To generate a key pair, you can use the following command:

To list your keys, you can use the following command:

Haveged: is a Linux entropy source using the HAVEGE algorithm. Entropy is a measure of randomness that is needed for various cryptographic applications, such as generating keys or certificates. Haveged is a userspace entropy daemon that does not depend on the standard mechanisms for harvesting randomness from the system, such as keyboard or mouse input. This is useful for systems that have high entropy needs or limited user interaction, such as headless servers or embedded devices.

OpenJDK-8-JRE-Headless: is a package that contains the Java Runtime Environment (JRE) for the OpenJDK 8 version of Java. It is called headless because it does not include any graphical user interface (GUI) components, such as fonts or graphics libraries. It is mainly used for running Java applications on servers or embedded devices that do not need a GUI.

Run the command below to install all the above mentioned packages on to your server at once:

Step 3: Install LibSSL1.1 package and here is why?

Ubiquiti UniFi Network controller uses MongoDB and the version of MongoDB preferred for this web application is MongoDB 3.6 which uses an older version of LibSSL. LibSSL is a Linux package that provides the client and server-side implementations for SSL and TLS protocols. SSL and TLS are cryptographic protocols that enable secure communication over the Internet. LibSSL is part of the OpenSSL project, which also includes libcrypto, a general-purpose cryptographic library. LibSSL1.1 is available through the Ubuntu archive and can be downloaded and installed using the following commands:

Step 4: We are going to add the GPG keys for both UniFi and MongoDB repos.

“Repos” stands for “Repositories”. A Linux repository is a storage location from which your system retrieves and installs OS updates and applications. Each repository is a collection of software hosted on a remote server and intended for a specific distribution or version of Linux. Repositories make it easier to find, install and update software, without having to manually compile the source code.

To list the repositories on your Linux system, you need to use the package manager that is compatible with your distribution. For example, on Debian-based distributions, such as Ubuntu or our Linux Mint, you can use the Advanced Packaging Tool (APT). On Red Hat-based distributions, such as CentOS, you can use the Yellowdog Updater Modified (YUM).

To list the repositories with APT, you can use the following command:

This will show all of the repositories configured on your system and whether they are enabled or not. You can also view the contents of the /etc/apt/sources.list file and the /etc/apt/sources.list.d directory, which contain the repository locations for APT.

To download the UniFi GPG key to our server, use the command below:

To download the MongoDB key to our server, use the command below:

Once we have successfully added the UniFi and MongoDB GPG keys to our server, we are good for the next step which is adding the UniFi and MongoDB repos.

Step 5: Adding the UniFi repo and MongoDB repo

Use the following command to add the UniFi repository:

Use the following command to add the MongoDB repository (Note that we are interested in the older version of MongoDB which is 3.6 and you have to be specific when adding this repo):

Use the following command to view your repo list:

Step 6: Perform a package list update.

Because we have now made changes in our repo-list (package sources list) we need to run “apt update” otherwise the package manager will not recognize the newly added repos!

Use the command below to complete this task:

Step 7: Installing the database server “MongoDB”, starting the mongod service and also enabling it to start through any server reboots.

Ubiquiti UniFi Network Controller uses MongoDB to store and retrieve data. MongoDB is a cross-platform document-oriented database program. It is classified as a NoSQL database program, which means it does not use the traditional relational model of tables and rows, but rather stores data in JSON-like documents with optional schemas. MongoDB is developed by MongoDB Inc. and licensed under the Server-Side Public License (SSPL). MongoDB offers a scalable and flexible way to store and access data, as it supports ad-hoc queries, secondary indexing, and real-time aggregations to provide powerful ways to analyze your data. MongoDB also supports various network protocols, such as HTTP, HTTPS, FTP, SFTP, SCP, IMAP, POP3, SMTP, and others.

To install MongoDB server, run the following command (Since we already specified the version = 3.6 when adding the MongoDB repo, there will be no need to specify the version here):

Use the command below to start MongoDB server on your system:

Use the command below to ensure MongoDB always starts at boot time (making the service persistent through server reboots):

Step 8: Installing the UniFi Network Controller

Finally, you get to install your UniFi Network controller on your server. Run the following command to download and install unifi:

Use the command below to check the status of your UniFi Network Controller Service:

Step 9: Create an account on Ubiquiti Official Website which you will use to complete the setup of your UniFi Network Controller web portal.

Step 10: Access your new UniFi Network Controller web portal via your server’s IP address on port 8443 to complete the setup.

Use your web browser to access the web portal: https://[your-server-ip-here]:8443

Follow the prompts at the web portal to complete the setup and add your first devices.

I hope this article has been helpful to enable you setup your first UniFi Network Controller. If you are working in a Wireless Internet Service Provider (WISP) environment with 1000s of Ubiquiti devices, this application will go a long way in easing your deployments, managing, and monitoring your network. If you have any questions, please use our Q & A forum on this website and I will be happy to assist you.