How To Run UniFi Controller in Docker Container

Posted on 116 views

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:

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 default
  • -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:

vim docker-compose.yml

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

UniFi-Controller-in-Docker-Container

Set the name of the application and proceed to sign in using your Ubiquiti account.

UniFi-Controller-in-Docker-Container-1

Configure the network.

UniFi-Controller-in-Docker-Container-2

The devices are not available since the application is running in a docker container. So skip and configure this later.

UniFi-Controller-in-Docker-Container-3

This too can be skipped and set later.

UniFi-Controller-in-Docker-Container-4

Review the configurations.

UniFi-Controller-in-Docker-Container-5-1024x611

The configurations will be made as shown.

UniFi-Controller-in-Docker-Container-6

Once complete you will see the below dashboard.

UniFi-Controller-in-Docker-Container-7-1024x724

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.

UniFi-Controller-in-Docker-Container-8-1024x507

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 ubnt.

Closing Thoughts

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.

coffee

Gravatar Image
A systems engineer with excellent skills in systems administration, cloud computing, systems deployment, virtualization, containers, and a certified ethical hacker.