The main objective of UniFi is to simplify IT operations. This is achieved using the engineering state-of-the-art networking, communications, security, and several other solutions designed to deliver intuitive experiences. It allows one to manage deployments from both local and cloud environments.
The UniFi OS is the operating system that hosts the UniFi application suite. There are several products available in the UniFi application suite. These include:
- UniFi Network: designed for home and enterprise networks with UniFi Switches, Gateways, and Wireless Access Points that provide high performance.
- UniFi Talk: this is a fully-fledged subscription-based VoIP phone solution preferred by small to medium-sized organizations.
- UniFi Protect: this is a plug-and-play camera security solution used for surveillance with custom detection logic.
- UniFi IDentity (UID): This is a simple administration tool that allows the managing of employee roles, network permissions, door access, workflows, report hierarchies, support ticket processing e.t.c
- UniFi Access: This is a state-of-the-art access control system with electric bolts/strikes, magnetic locks, and 12V (1 Amp) with several sensors. It can be used to manage visitors, schedules, and access policies
The UniFi® Controller is a wireless network management software solution developed by Ubiquiti Networks™. It allows one to manage several wireless networks from its web UI. This tool is ideal for high-density deployments that required low latency and high uptime.
The UniFi® Controller can be installed on Linux, Mac OS X, or Microsoft Windows 7/8 by downloading the UniFi Controller software from the Ubiquiti Networks website. But this process requires one to install several dependencies such as Java Runtime Environment e.t.c
In this guide, we will learn how to Run UniFi Controller in Docker Container. This method is preferred since the container comes with all the dependencies bundles and makes it easy to run the UniFi Controller.
Other installation methods:
- Install UniFi Controller on Ubuntu 18.04 / Debian 9
- How To Install UniFi Network Application on macOS
Step 1 – Install Docker on Linux
Before we begin, you need to have the Docker Engine installed on your system. The guide below can be used to achieve this:
Once installed, ensure that the Docker service is up and running;
sudo systemctl start docker && sudo systemctl enable docker
Add your system user to the Docker group;
sudo usermod -aG docker $USER newgrp docker
Step 2 – Configure Persistent Volumes
Persistent volumes are used to store the data for the container so that it is not lost on reboot. For this guide, we will create a path to be used for data storage at /unifi_data/config
sudo mkdir -p /unifi_data/config
Set the correct permissions:
sudo chmod 775 -R /unifi_data/config
For the path to be accessible, we need to configure SELinux on RHEL-based systems as shown:
sudo setenforce 0 sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/g' /etc/selinux/config
Step 3 – Run UniFi Controller in Docker Container
Once the Docker engine has been installed, you can easily run the UniFi Controller from the docker command line.
The command has several parameters that include:
- -p for several ports. These ports are used for different services:
- 8443 – Unifi web admin port
- 3478/udp – Unifi STUN port
- 10001/udp – Required for AP discovery
- 8843 – Unifi guest portal HTTPS redirect port
- 8880 – Unifi guest portal HTTP redirect port
- 8080 – Required for device communication
- 1900/udp – Required to Make controller discoverable on L2 network option
- 6789 – For mobile throughput test
- 5514/udp – Remote Syslog port
- -e for environment variables such as:
- PUID and PGID that define the user and group permissions to avoid errors that arise between the host OS and the container due to persistent volumes/paths
- MEM_LIMIT and MEM_STARTUP is used to configure the Java memory you can set the default using the value
- -v defines the volume to store the container data.
Now you can start the UniFi Controller container with all parameters defined as shown:
docker run -d \ --name=unifi-controller \ -e PUID=1000 \ -e PGID=1000 \ -e MEM_LIMIT=1024 `#optional` \ -e MEM_STARTUP=1024 `#optional` \ -p 8443:8443 \ -p 3478:3478/udp \ -p 10001:10001/udp \ -p 8080:8080 \ -p 1900:1900/udp `#optional` \ -p 8843:8843 `#optional` \ -p 8880:8880 `#optional` \ -p 6789:6789 `#optional` \ -p 5514:5514/udp `#optional` \ -v /unifi_data/config:/config \ --restart unless-stopped \ lscr.io/linuxserver/unifi-controller:latest
Step 4 – Run UniFi Controller using Docker Compose (Recommended)
You can also run the UniFi Controller using Docker Compose. First, ensure that Docker compose is installed on your system.
Once installed, create a docker-compose file with all the parameters defined:
The file will contain the below lines:
--- version: "2.1" services: unifi-controller: image: lscr.io/linuxserver/unifi-controller:latest container_name: unifi-controller environment: - PUID=1000 - PGID=1000 - MEM_LIMIT=1024 #optional - MEM_STARTUP=1024 #optional volumes: - /unifi_data/config:/config ports: - 8443:8443 - 3478:3478/udp - 10001:10001/udp - 8080:8080 - 1900:1900/udp #optional - 8843:8843 #optional - 8880:8880 #optional - 6789:6789 #optional - 5514:5514/udp #optional restart: unless-stopped
Save the file and run the container with the command:
docker-compose up -d
The image will be pulled and the container started as shown:
[+] Running 8/8 ⠿ unifi-controller Pulled 16.2s ⠿ 7fe4e822761f Pull complete 4.2s ⠿ 5231b3c13f88 Pull complete 4.5s ⠿ ebfffaf4df3c Pull complete 7.4s ⠿ f302152db91c Pull complete 7.6s ⠿ 56b6cfbc09d3 Pull complete 14.4s ⠿ 05d9d46415f7 Pull complete 14.6s ⠿ 422e0f275a69 Pull complete 14.8s [+] Running 2/2 ⠿ Network ubuntu_default Created 0.2s ⠿ Container unifi-controller Started 1.5s
Now with whichever way you sued to run the UniFi Controller verify if the container is running:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c77f3c6e506c lscr.io/linuxserver/unifi-controller:latest "/init" 18 seconds ago Up 17 seconds 0.0.0.0:1900->1900/udp, :::1900->1900/udp, 0.0.0.0:3478->3478/udp, :::3478->3478/udp, 0.0.0.0:6789->6789/tcp, :::6789->6789/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:8443->8443/tcp, :::8443->8443/tcp, 0.0.0.0:8843->8843/tcp, :::8843->8843/tcp, 0.0.0.0:5514->5514/udp, :::5514->5514/udp, 0.0.0.0:10001->10001/udp, :::10001->10001/udp, 0.0.0.0:8880->8880/tcp, :::8880->8880/tcp unifi-controller
Step 5 – Access UniFi Controller Web UI
Now access the UniFi Controller web UI using the URL https://IP_Address:8443
Set the name of the application and proceed to sign in using your Ubiquiti account.
Configure the network.
The devices are not available since the application is running in a docker container. So skip and configure this later.
This too can be skipped and set later.
Review the configurations.
The configurations will be made as shown.
Once complete you will see the below dashboard.
Now for UniFi Controller to adopt your devices such as access points, you need to change the inform IP address. This can be done by navigating to Settings > System Settings > Other configurations.
Enable network discovery and check the Override inform host. Also, provide your IP Address or hostname on which the container is running as shown.
Once the changes have been made, apply them. Now adopt the devices manually with the command:
ssh [email protected]$device-IP set-inform http://$address:8080/inform
In the above commands, replace:
- $device-IP with the address of your device to be adopted
- $address with the IP address of your host running the UniFi Controller container
The default password for the user ubnt is
That marks the end of this guide on how to run UniFi Controller in Docker Container. You can now manage your wireless networks from the UniFi Controller web UI. I hope this was significant to you.