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 installing the Unifi Controller on the Raspberry Pi step-by-step in 5 minutes.
I have updated this article on October 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.
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
Also, you are going to need a MicroSD card, buy atleast a class 10 card. These are the fastest at the moment with 10MB/sec.
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
Place the MicroSD card in your computer and open Raspberry Pi Imager:
- Click Choose OS
- Select Raspberry Pi OS (other)
- Choose Raspberry Pi OS Lite (32bit)
- Click on Choose Storage
- Select your MicroSD card (check the size and drive letter!)
- Click on Write
- You will get a warning that all data will be removed, click Ok and get a coffee 😉
- Wait until the process is finished
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
So you should be able to do the following to enable SSH:
- Open your explorer and open de MicroSD card. (it’s called boot).
- Add a new text file and name it SSH
- 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 in 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:
Type the following command to open the settings page:
- 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
To connect to the Raspberry Pi we will need to know it’s IP Address. You could make a reservation in your router for it based on the mac address, but let’s assume you didn’t.
Find the Ip Address
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 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 login, the default credentials are:
Step 3 – Setting up the Raspberry Pi
Before we are going to install the Unifi Controller on the Raspberry Pi we first going to setup 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:
- 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.
- To edit the network config file type the following cmd:
sudo nano /etc/dhcpcd.conf
3. Enable to following lines by remove the # from it and set IP address to a fixed value
#Static IP configuration: interface eth0 static ip_address=192.168.1.210/24 #static ip6_address=fd51:42f8:caae:d92e::ff/64 static routers=192.168.1.1 static domain_name_servers=192.168.1.1 188.8.131.52 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.
ipaddress 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
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.
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:
[email protected]:~ $ passwd Changing password for pi. (current) UNIX password:raspberry Enter new UNIX password: Retype new UNIX password: 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.
sudo apt-get update && sudo apt-get upgrade -y && sudo apt-get autoremove && sudo apt-get autoclean
This may take a minute or two.
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:
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.
sudo apt-get install openjdk-8-jre-headless -y
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:
- Select 4. Performance Options
- P2 GPU Memory
- Change 64 to 16MB
- 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:
echo 'deb http://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/100-ubnt-unifi.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
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:
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 MongoDB instance. This would only waste resources of our Pi, so we get rid of it:
sudo systemctl stop mongodb sudo systemctl disable mongodb
5. Finished installing the Unifi Controller on the Pi
The only step left is to reboot the Pi
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 😉 )
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!
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:
unexpected end of file or stream 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:
sudo apt-get clean
You probably also like the following articles: