Skip to main content
Home Network

Install Unifi Controller On Raspberry Pi in 5 min

By January 17, 2023No Comments

I have some smart products at home and one of the things I wanted to do is read out the connected WiFi devices. To do this I need to Unifi Controller to be running 24/7, so I needed a device to run the Unifi Controller on, something small, cheap, and with low running costs. That’s where the Raspberry Pi comes in. In this article, I will help you install the Unifi Controller on the Raspberry Pi step-by-step in 5 minutes.

I have updated and tested this article on November 18th, 2021. The default Java version that is installed on the Raspberry isn’t supported anymore by the Unifi Controller (^ 5.10.x). So we are going to replace it with OpenJDK. And we will install an older version of MongoDB, because the latest version isn’t supported by the Unifi Controller.

We will also add haveged to the installation. This will fix the slow start-up issue of the Unifi Controller on the Raspberry Pi.

What do we need for the Unifi Controller and Raspberry Pi?

Before we can start with installing the Unifi Controller on the Raspberry Pi we need to get some parts and download some software. Of course, we need to buy a Raspberry Pi. You can use a model 2, but if you have to buy one new I recommend getting a Model 3B or Model 4B

Also, you are going to need a MicroSD card, buy atleast a class A2 card. These are the fastest at the moment with 10MB/sec.

  • Raspberry Pi 3 B+ on Amazon
  • MicroSD Card class A2
  • Raspberry Pi Power Adapter
  • Raspberry Pi kit
  • Case and heatsink for Model 4B

Download the following software so to get started:

  • Raspbian Pi Imager (direct download link)
  • Advanced IP Scanner – to find the IP address of the PI
  • Putty – to connect to the Pi with SSH

Step 1 – Getting the Raspberry Pi up and running

First, we are going to start by installing Raspbian on de MicroSD card. We can now use the Raspberry Pi Imager to easily install the correct Raspbian OS version. We are going to install the lite version of Raspberry Pi OS, this version comes without a desktop which we don’t need.

Place the MicroSD card in your computer and open Raspberry Pi Imager:

  1. Click Choose OS
  2. Select Raspberry Pi OS (other)
  3. Choose Raspberry Pi OS Lite (32bit)
  1. Click on Choose Storage
  2. Select your MicroSD card (check the size and drive letter!)
  3. Click on Write
  4. You will get a warning that all data will be removed, click Ok and get a coffee 😉
  5. Wait until the process is finished

Activate SSH

We don’t want to connect a keyboard and monitor to our Raspberry Pi everything we need to update or change something. So the first thing we do is enable SSH so we can connect remotely to the PI.

Now the following steps should work also on a Windows machine, but I had multiple times that I was unable to open de SD card in Windows Explorer. Don’t waste your time trying if you have the same, just follow the Alternative way to enable SSH below.

So you should be able to do the following to enable SSH:

  1. Open your explorer and open de MicroSD card. (it’s called boot).
  2. Add a new text file and name it SSH
  3. Make sure you remove .txt from the file name. So you are left with a file just named SSH.

If you have trouble opening the SDCard in Windows you can try to use another computer or skip this part. You will then need to connect a monitor (or TV) and keyboard to the Pi and follow the step under Alternative way to enable SSH

Plug the MicroSD card into the Rasberry Pi and connect the power and ethernet cable. The PI will now startup.

Alternative way to enable SSH

Make sure you have a keyboard and monitor/tv connected. Login to the Pi with the following login:

Username: pi
Password: raspberry

Type the following command to open the settings page:

1.  sudo raspi-config
  • Select 5. Interfacing Options
  • Scroll down to 2. SSH and press enter to enable it
  • When down press ESC to exit the settings page.

You have now enabled SSH and can continue the follow this guide.

Step 2 – Connecting with SSH

You can connect to your Raspberry Pi using the default hostname raspberrypi.local. Sometimes this doesn’t work, due to your network configuration. In that case, you will need to look up the IP Address of your Pi.

Find the Ip Address – optional

We need to find the IP Address of the PI. Open Advanced IP Scanner and click on scan.

In the results, you will see the Raspberry Pi, note the IP Address, in my case, it’s 192.168.1.210.

Connecting to the PI with Putty

Open Putty that you downloaded earlier. Enter raspberrypi.local or the IP Address that we found in the Advanced Ip Scanner and click on Open

You will get a warning if we trust the host. We do so click yes

You will need to log in, the default credentials are:

Username: pi
Password: raspberry

Step 3 – Setting up the Raspberry Pi

Before we are going to install the Unifi Controller on the Raspberry Pi we first going to set up the Raspberry Pi self. You can copy-paste the command in Putty. Just copy from this article and right-click in Putty.

Set a static IP Address

By default, the Pi is using DHCP to get an Ip address. This means that a reboot can cause it to get a new Ip address, which will make it hard to manage it with SSH or to open the Unifi Controller.

So we are going to set a static Ip Address on the network interface:

  1. First, let’s check the current network details. Type: ifconfig
    In the result you will see eth0 and in that block inet: 192.168.x.x. This is the current ip address.
  2. To edit the network config file type the following cmd:
1.  sudo nano /etc/dhcpcd.conf

3. Enable to following lines by removing the # from it and set an IP address to a fixed value

1.  #Static IP configuration:<font></font>
2.  interface eth0<font></font>
3.  static ip_address=192.168.1.210/24<font></font>
4.  #static ip6_address=fd51:42f8:caae:d92e::ff/64<font></font>
5.  static routers=192.168.1.1<font></font>
6.  static domain_name_servers=192.168.1.1 1.1.1.1 fd51:42f8:caae:d92e::1

In this case, we set the IP address to 192.168.1.210 and the address of the internet router is 192.168.1.1. You also need to set the domain_name_servers, by default entering the router’s address is enough.

Which ip address should you pick? If you don’t know your network layout, keep the first 3 parts of the address the same and choose a value between the 200 and 240 at the end.

When done save and close the file by pressing ctrl + x and choose Y to save it.

Now we need to restart the network interface to apply the settings. Simply reboot the Pi with the cmd below. Wait a minute and connect to the PI with Putty on the new IP Address.

1.  sudo reboot

Change the default Password

Just with every (network)device you have, you should change the default password. To change the password you will need to enter the current password first and then enter the new password twice:

Enter the cmd passwd:

1.  pi@raspberrypi:~ $ passwd<font></font>
2.  Changing password for pi.<font></font>
3.  (current) UNIX password:raspberry<font></font>
4.  Enter new UNIX password:<font></font>
5.  Retype new UNIX password:<font></font>
6.  passwd: password updated successfully

Updating your Raspberry

Before we start installing software on the PI, we will make sure the Raspberry Pi is up-to-date. With the cmd below we will update the firmware, software and clean up unused and old software.

1.  sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get autoremove && sudo apt-get autoclean

This may take a minute or two.

Install haveged

Not really necessary, but the startup of the Unifi Controller can take a bit long on a Raspberry Pi due to the fact there is no user interaction. Now your Pi should be running 24/7, so it’s not a big deal, but we can speed it up anyway.

Install haveged to solve the issue with the following cmd:

1.  sudo apt-get install haveged -y

Update Java 8

This step is pretty important with the newer release of the Unifi Controller. Starting with version 5.10.x the old Java version that comes with Raspbian isn’t supported anymore. So we are going to replace it with OpenJDK 8.

1.  sudo apt-get install openjdk-8-jre-headless -y

Split memory

If you run the Raspberry Pi without a monitor connected you can safely reduce the amount of ram used by the GPU. By default, the Pi has assigned 64MB RAM to the GPU. Because we are using CLI (Command Line Interface) to work on the Pi, we can reduce that amount for RAM, leaving more RAM available for the Pi self.

Open the Raspberry Pi config with the following command:

1.  sudo raspi-config
  1. Select 4. Performance Options
  2. P2 GPU Memory
  3. Change 64 to 16MB
  4. Hit Enter and use Esc to close the config screen.

Make sure you reboot the Pi to apply the changes.

Step 4 – Installing the Unifi Controller Raspberry Pi

So with our Raspberry Pi ready we can start with installing the Unifi Controller on the Raspberry Pi.

1. Add the repository for the Unifi Controller

All Linux distros come with a source list, repository, of available packages to install. Unifi Controller is not listed in the default repositories, so we need to add it first:

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

Fix MongoDB version

The latest version of MongoDB isn’t supported by the Unifi Controller. When installing the Unifi Controller you will probably get the following error:

1.  Some packages could not be installed...<font></font>
2.  <font></font>
3.  The following packages have unmet dependencies:<font></font>
4.  unifi : Depends: mongodb-server (>= 2.4.10) but it is not installable or etc.

To avoid this we need to change the repository for MongoDB:

1.  echo 'deb http://archive.raspbian.org/raspbian stretch main contrib non-free rpi' | sudo tee /etc/apt/sources.list.d/raspbian_stretch_for_mongodb.list

2. Authenticate the software

To install the Unifi Controller software we need to authenticate the software that it’s the real software from Ubiquiti. This can be done with a GPG key so we can authenticate the software.

1.  sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ubnt.com/unifi/unifi-repo.gpg

3. Install the Unifi Controller

We now have added the software to our list of available software and have the ability to check its authenticity. So let’s download the software and install the Unifi Controller on the Raspberry Pi:

1.  sudo apt-get update; sudo apt-get install unifi -y

4. Cleanup MongoDB

The installation may take a couple of minutes to complete. When done, we need to remove the default database that comes with the MongoDB instance. This would only waste resources of our Pi, so we get rid of it:

1.  sudo systemctl stop mongodb <font></font>
2.  sudo systemctl disable mongodb

5. Finished installing the Unifi Controller on the Pi

The only step left is to reboot the Pi

Wrapping up

After the reboot, you can log in to the Raspberry Pi with your browser. Go to the Ip address you set earlier (for example https://192.168.1.210:8443)

The setup wizard page will be displayed allowing you the create a new site or restore a backup. Check this post for some tips on how to optimize your controller or how to add the access points.

Make sure you backup your Unifi Controller properly. Updates can brick your controller or even Pi, so the best solution is to backup your controller to cloud storage, like Dropbox. You can read this article on how to set it up (it only take another 5 minutes 😉 )

You may also like this article where I will guide you through installing Home Assistant on your Raspberry Pi using Docker.

Keeping the Unifi Controller up to date

It’s important to keep your network products up-to-date. New firmware contains important security fixes, fixes bugs in the software, and can enhance the performance of a device. Check out this post on how to update the Unifi Controller and signup for the newsletter. I will drop you an email when there is a new version available!

Common errors

During the installation, you might get an error. It happens sometimes with Linux-based systems. You can check the comments below for issues others have run into. One of the problems I had during the installation was this:

1.  unexpected end of file or stream<font></font>
2.  abort-upgrade: please reinstall previous version

One of the first things you can try is to clean up the downloaded list from APT. This way the files will be downloaded again, solving any issue with corrupt files during the download:

1.  sudo apt-get clean

404 error – not found

If you have installed the Unifi Controller get a 404 error after you have restored the Pi then there is a problem with the Unifi services.

You can check the status of all services on your Raspberry Pi with the following command:

1.  sudo service --status-all

All services that are running are listed with a + in front of it. The Unifi service may be turned off, or even maybe listed as running, but clearly malfunctioning.

We can easily fix this by (re)starting the services:

1.  service unifi start

You may need to enter your password again, but after that, the Unifi Controller should be running.

You probably also like the following articles:

  • Unifi Protect Review
  • Best Home Network Setup
  • Backup your Unifi Controller
  • Setting up the Unifi Guest Portal
  • Install Unifi Controller on Synology NAS
  • Monitor your Home Network for Free
Close Menu