How to Run UniFi Controller in Docker?

Recently, I bought a UniFi USW-Lite-8-PoE switch and wanted to host my own controller. UniFi does offer a cloud-hosted controller, but it's quite expensive for my needs. Why pay for something when you can run it on your own network? You can simply get a Raspberry Pi and set it up using Docker. So, let's get started.

This blog post assumes you have some basic understanding of Docker and Docker Compose. Docker Compose is a tool that helps you define and manage multi-container Docker applications. Instead of running individual docker run commands for each container, you can use Docker Compose to describe all your services in a single docker-compose.yaml file. This makes it much easier to set up, configure, and manage your Docker environment.

---
version: "2.1"
services:
  unifi-controller:
    image: lscr.io/linuxserver/unifi-controller:latest
    container_name: unifi-controller
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - MEM_LIMIT=2048 #optional
      - MEM_STARTUP=2048 #optional
    volumes:
      - /home/suresh/Documents/unifi/unifi_data:/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

This Docker Compose file defines the setup for running the UniFi Controller in a Docker container. The file specifies the image to use (linuxserver/unifi-controller:latest) and gives the container a name (unifi-controller).

Environment variables are set to define the user ID, group ID, time zone, and memory limits for the container. The volumes section maps a directory on the host (/home/suresh/Documents/unifi/unifi_data) to a location inside the container to persist the UniFi configuration data.

The ports section defines the network ports that will be exposed to allow access to the UniFi Controller services, both standard TCP and UDP ports are included to support various features like management, device discovery, and communication. Finally, the container is set to always restart unless manually stopped, ensuring it stays active even if the system reboots.

To deploy the UniFi Controller using Docker Compose, execute the following command in the directory where your docker-compose.yaml file resides.

docker-compose up -d

Wait for a few minutes to allow all the services to start up. Once they're online, you can access the UniFi Controller by navigating to https://HOST_IP:8443 in your browser, replacing HOST_IP with the actual IP address of your Docker host. From there, you'll be able to log in and manage your UniFi devices.

UniFi Inform Host

The UniFi Controller running in Docker uses bridge networking by default, meaning it will be assigned an IP address from the Docker network (typically something like 172.x.x.x), which is different from your main network's IP range.

To ensure that your UniFi devices can properly communicate with the controller, you need to update the 'Inform Host' setting. Go to Settings > System > Advanced and override the default IP with the real IP address of the host running the UniFi container. This way, your devices will be able to find and connect to the controller without any issues.

UniFi Controller and UniFi Devices on Different Subnet

If your UniFi Controller is on a different subnet from the UniFi devices, you can create a DNS entry in your internal DNS server to resolve the hostname 'unifi' to the IP address of the controller.

Make sure that the UniFi devices are configured to use this DNS server. When a device boots up, it will try to resolve the hostname 'unifi', and if successful, it will use the resolved IP address to connect to the controller. This way, even with the controller and devices on separate subnets, they can still communicate.