High availability UniFi Controller

Aug. 13, 2020    Tags: raspberrypi  high available  unifi


I like having stuff high available. Everybody who works in IT knows it: Everything can fail and it most likely fails when you really need it as written in Murphy's law: "Anything that can go wrong will go wrong". Therefore I decided to cluster my UniFi Controller today. For sure it does not need to run on a server and can be started locally for configuration. But I like to have some nice stats and graphs which are also provided by the Controller and therefore it needs to be up and running constantly.

Per default UniFi Controller starts its own mongodb Database to store all needed data. It stores the Database at its homedirectory and only listens on localhost. Since UniFi Controller Version 5.3 it is possible to configure an external mongodb host and a mongo uri where you can define some replicaSet settings.

I'm using some raspberryPi for my UniFi Controller.

Some initial steps needs to be done:

  1. start unifi on one of the raspberry pis the first time
  2. configure it the first time. At least the Initial setup like login.
  3. dump the mongoDB Data
  4. stop unifi. That will also stop the local started mongodb
  5. configure a mongo replica set
  6. restore the mongodb Data
  7. configure unifi to use a replicaSet and not the local DB
  8. configure a failover IP at least used for the Accesspoints.


Unifi Setup

To install UniFi Controller on a debian System is pretty straight forward:

echo 'deb http://www.ui.com/downloads/unifi/debian stable ubiquiti' | sudo tee /etc/apt/sources.list.d/unifi.list
sudo wget -O /etc/apt/trusted.gpg.d/unifi-repo.gpg https://dl.ui.com/unifi/unifi-repo.gpg

Now it can be installed with the following command:

apt-get update; apt-get install unifi

MongoDB ReplicaSet

Creating a MongoDB ReplicaSet should at least contain three nodes.

  1. Primary MongoDB
  2. Secondary MongoDB
  3. MongoDB Arbiter

Only a replicaSet of three is able to failover in time without any big delay.

Negative fact installing a mongoDB on a raspberry pi is that they only provide mongoDB 2.4 as a debian package. If you want something more up to date you have to install it from source which is not handled by this post. Also creating a mongo ReplicaSet is well documented on mongodb website itself.

Failover IP

I'm using a pretty simple keepalived configuration to get my IP failover working. Important part is that both servers used for the IP failover must be located in the same network.

To install keepalived just use:

apt-get install keepalived

Now we can create the config files (`/etc/keepalived/keepalived.conf`) on both servers.


vrrp_instance VI_1 {
  state BACKUP
  interface eth0
  virtual_router_id 10
  priority 101
  virtual_ipaddress { brd dev eth0 label eth0:0


vrrp_instance VI_1 {
  state MASTER
  interface eth0
  virtual_router_id 10
  priority 102
  virtual_ipaddress { brd dev eth0 label eth0:0

Connect UniFi to mongodb

Per default UniFi starts its own included mongodb. If you want to have some failover cluster like we setup above, you have to tell UniFi about it.

Now we have to edit the unifi properties file at `/var/lib/unifi/system.properties` and add the following:


HOST01 and HOST02 needs to be replaced with the IPs or hostnames of your mongo cluster.