Toxicantidote UniFi controller on Debian 11

UniFi controller on Debian 11

Feburary 2022

The problem

The UniFi controller software relies on various software libraries that are ridiculously out of date, causing issues when installing on newer distributions. I found that attempting to install the controller software on Debian 11 (Bullseye) following the official instructions from Ubiquiti would result in broken dependencies.

Previously I had this working on Debian 10 (Buster) using the official instructions, but with a slightly modified apt source entries, per below:


deb https://www.ui.com/downloads/unifi/debian stable ubiquiti
## unifi depends on this ancient mongodb
deb https://repo.mongodb.org/apt/debian stretch/mongodb-org/3.6 main
## ... and this jdk
deb https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ buster main
This allowed the old dependencies requried by the UniFi controller to install.

On Debian 11 I was able to force the dependencies after a few hours of tweaking. This included using the nvidia-openjdk-8-jre to provide the old Java runtime required. Following this, the controller would run, but I was unable to access the web interface as the controller was not using a modern enough SSL cipher for the HTTPS connection. As a hack, I tried reverse proxying this through an Apache webserver, but just ran in to more problems with it breaking the websocket connections used by the controller software.

The solution

After giving up trying to force the install, I started looking for an alternate method, and found that the team at LinuxServer.io had created a Docker image for the UniFi controller. This container has the controller software and all dependencies bundled. No need to contaminate my system with old packages and forced dependencies!

Installation is fairly straightforward, requiring only a few commands to get the controller software running. For these steps, I am assuming the following configuration:

To install and run:
  1. Become root. Use sudo su - if you don't have a root account or su - otherwise.
  2. If you don't already have it installed, install docker: apt install docker
  3. Make a directory for the controller to store configuration files: mkdir /etc/unifi
  4. Run the container:
    docker run -d --name=unifi-controller -v /etc/unifi:/config --restart unless-stopped -p 192.168.0.1:3478:3478/udp -p 192.168.0.1:10001:10001/udp -p 192.168.0.1:8080:8080 -p 192.168.0.1:8443:8443 -p 192.168.0.1:1900:1900/udp lscr.io/linuxserver/unifi-controller
    This will download a copy of the container the first time you run it. Subsequent runs will use the local copy.
  5. Wait a minute for the controller to start.
  6. The web interface should now be accessible on https://192.168.0.1:8443. You will be greeted with the UniFi setup wizard, which will guide you through the setup process, or allow you to load a configuration backup file.
    You will likely see a warning that the HTTPS certificate is not valid. It is safe to ignore this warning and proceed to the site. Fixing this certificate is outside of the scope of this article.

Possible issues

Devices can't be adopted/Re-adopting devices from another setup

Sometimes devices may not adopt smoothly. This can be an issue even with non-container installs of the UniFi controller software. The course of action here will depend on whether you have configured these devices previously. These steps should work for indoor wireless APs and the USG.

Configured previously

To force adoption of a previously configured device:

  1. SSH to the IP of the device.
    If you don't know the IP of your device, check the client list on your router's management interface. Look for a client with a MAC (hardware) address starting with one of the following:
    • 00:15:6D
    • 00:27:22
    • 04:18:D6
    • 18:E8:29
    • 24:5A:4C
    • 24:A4:3C
    • 44:D9:E7
    • 60:22:32
    • 68:72:51
    • 68:D7:9A
    • 70:A7:41
    • 74:83:C2
    • 74:AC:B9
    • 78:45:58
    • 78:8A:20
    • 80:2A:A8
    • 94:2A:6F
    • AC:8B:A9
    • B4:FB:E4
    • D0:21:F9
    • DC:9F:DB
    • E0:63:DA
    • E4:38:83
    • F0:9F:C2
    • F4:92:BF
    • F4:E2:C6
    • FC:EC:DA
    • 00:50:C2:B0:40:00
  2. Log in using the credentials of the controller last used to configure the device (default may be ubnt/ubnt)
  3. Run the command: set-inform http://192.168.0.1:8080/inform
  4. Leave the SSH session open, and adopt the device from the UniFi controller web interface.
  5. As soon as the interface shows 'Adopting', return to the SSH session and run the command again: set-inform http://192.168.0.1:8080/inform
  6. The device should now be adopted and visible in the UniFi controller interface after a few seconds.

New device or forgotten password

To adopt a new device or device with forgotten password:

  1. If the device is visible in the UniFi controller interface, remove (forget) it.
  2. Press and hold the reset button on the device for ten seconds. The status light should start flashing white.
  3. Once the light is solid white, adopt the device from the UniFi controller interface.

Related resources