How to Run the Unifi Controller via LinuxServer.io’s Docker Image

In late 2019, I decided to upgrade my home network to use Ubiquity’s line of Unifi equipment. Hardwiring several access points to cover my sprawled-out, L-shaped ranch house has gone a long way to improving WiFi coverage. I’m also using a fair amount of the Unifi routing and switching equipment.

Today, I’ll explain how I set up my system to run the Unifi controller software via the LinuxServer.io Unifi controller image on a Docker host in my basement.

About LinuxServer.io

LinuxServer.io is an organization that provides quite a few open-source packages as Docker images. From their homepage:

We are a group of like-minded enthusiasts from across the world who build and maintain the largest collection of Docker images on the web, and at our core are the principles behind Free and Open Source Software. Our primary goal is to provide easy-to-use and streamlined Docker images with clear and concise documentation.

I’ve been using LinuxServer.io images for a couple of years; they are certainly easy-to-use, clear, and concisely documented. I tend to check here first when I need a new image.

Unifi Controller Container Configuration

I tend to use docker compose to build and run my images & containers. Here are the contents of the docker-compose.yml for this project:

version: '3.7'

networks:
  default:
    name: unifi-controller

services:
  unifi-controller:
    container_name: unifi-controller
    image: linuxserver/unifi-controller:5.13.32-ls65
    restart: unless-stopped

    environment:
      - PUID=XYZ # user account id on the system
      - PGID=ABC # group id group on the system
      - TZ=America/Detroit
    ports:
      - 3478:3478/udp
      - 10001:10001/udp
      - 8080:8080
      - 8081:8081
      - 8443:8443
      - 8843:8843
      - 8880:8880
      - 6789:6789
    volumes:
      - /volume1/docker/unifi-controller:/config

Let’s step through some of the interesting bits here — much of which is derived from the instructions in the image’s README file: image: linuxserver/unifi-controller:5.13.32-ls65

My personal preference is to lock images down to a specific version, if at all feasible. This way I won’t be surprised when, say, a new version of an image requires or breaks the current configuration. LinuxServer is great about providing versioned images over time.

In the case of the Unifi controller image, I tend not to update it unless I need a new version of the controller, perhaps because I have a new piece of equipment.

environment:
  - PUID=XYZ # user account id on the system
  - PGID=ABC # group id group on the system
  - TZ=America/Detroit

LinuxServer has a great system for setting user and group permissions. In this case, I have PUID and PGID set to the user and group number on my host system. (I have the comment there so that, when I look at this file again three months later, I can remember why I have some hardcoded numbers typed into the file.)

ports:
  - 3478:3478/udp
  - 10001:10001/udp
  - 8080:8080
  - 8081:8081
  - 8443:8443
  - 8843:8843
  - 8880:8880
  - 6789:6789

These ports are recommended by the image’s README file. The README documents what all of them are for. In my case, I’m running this on a system secured behind my firewall, so I’m not concerned about making them available. I am also lucky that these ports don’t conflict with anything else on my system.

volumes:
  - /volume1/docker/unifi-controller:/config

Last are my volume mappings. In this case, there is only one — a persistent place for the container to store its configuration.

That Wasn’t Too Bad

The Unifi controller container is pretty straightforward to run. Other containers in my home environment are not so easy, and I plan to post about them in the future. This particular image is a great place to start.