Running a Unifi Controller using Docker-Compose.

Sergei Filippov

3 min readJul 7, 2017

So you want to play around/run a Unifi Controller 5.5.19 Stable on your Windows/Linux/MacOS machine.

The simplest way to get started it using Docker-Compose.

Firstly, Install Docker & Docker Compose

Get Docker & Docker Compose installed on your system in you haven’t done so already.

Here are some typical installation instructions if you haven’t done so already.

Picking our Docker container image

Docker Hub has a number of Unifi Controller specific images available for download.

For this example, we’ll use an excellent image created by Jacob Alberty on hub.docker.com.

jacobalberty/unifi is the name of the docker image we’ll be using. However, if we just use jacobalberty/unifi as it is now, docker will automatically use the latest version of the image.

I prefer to be explicit about the version to guarantee a repeatable result, ESPECIALLY in production situations.

Let’s use jacobalberty/unifi:5.5.19. Done. 👍🏻

Persisting data using volumes

To make sure that data form the Unifi Controller application lives on even if the image is deleted/removed/upgraded we need to share it between the docker container running and the system it will be running on.

According to the Docker Hub documentation for this image, there three (3) volumes we need to make sure to define. If we don’t, these volumes will be created in the container and will be removed with the container if we remove it.

/var/lib/unifi - Configuration data
/var/log/unifi - Log files
/var/run/unifi - Run information
/var/run/data - Application data

Environment variables

We can also set some additional setting in the container using Docker Environment Variables. This will vary depending on the image being used.

Looking at the documentation for this image however, I see that we can specifically TZ variable for Timezone.

I’m in Pacific/Auckland, so I’ll use that.

Create folders for the volumes

We will setup the following folder structure:

unifi-controller
├── docker-compose.yml
├── data/ - folder
├── lib/ - folder
├── log/ - folder
└── run/ - folder

You can do all of this with one line:

mkdir -p ./unifi-controller/{data,lib,log,run}

Defining docker-compose.yml

version: '2'
services:
 unifi-controller:
   container_name: unifi.controller-5.5.19
   image: jacobalberty/unifi:5.5.19
   restart: always
   volumes:
     - './data/lib:/var/lib/unifi'
     - './data/log:/var/log/unifi'
     - './data/run:/var/run/unifi'
   ports:
     - '3478:3478/udp'
     - '10001:10001/udp'
     - '6789:6789/tcp'
     - '8080:8080/tcp'
     - '8880:8880/tcp'
     - '8443:8443/tcp'
     - '8843:8843/tcp'
   environment:
     - TZ=Pacific/Auckland
   labels:
     - 'unifi-controller'

Note: This is a yml file, so intention is important.

restart: always will automatically start this container when a system reboots and the docker process is started.

Special note for MacOS Server users

If you want to do this onMacOS Server you need to adjust some of the ports. This applies to using docker run and docker-compose.

Ports 8443 and 8843 are used by some MacOS Server services. Just update them to something like:

...
 --publish 9443:8443/tcp \
 --publish 9843:8843/tcp \
...

So now to get to the web ui you need to do something like https://awesome.unificontroller.example.com:9443/manage/account/login

Start It All Up!

Navigate to the folder that has your docker-compose.yml file and simply run:

$ cd ./unifi-controller
$ docker-compose up -d

Docker compose will look in the folder for the docker-compose.yml file, read it and use it’s instructions to create and configure the container for us.

-d flag will tell Docker Compose to run the container in the background.

Fin.