Setting up a UniFi controller with Docker and Caddy

If you are having troubles finding a UniFi controller key/hardware or simply wants to use another hardware for management purposes of your UniFi access points you can make use of a Docker image. In this tutorial I will also explain how to use Caddy in case you wish to host it on a public API using a valid TLS certificate.

Installing Docker and Docker compose

Google it, there are tons of tutorials online. The official links for them at the time I write this article are:

Creating docker-compose.yml

We will use the image https://hub.docker.com/r/linuxserver/unifi-controlleropen in new window

I suggest you to create a brand new folder, so all the files related to the

Make sure to use root/sudo for all commands

useradd -r unifi
id unifi
# Take a note of the ids shown up, below an example
# uid=1000(unifi) gid=1000(unifi) groups=1000(unifi)
cd /home/unifi

Create a file called docker-compose.yml.

# Create this file at /home/unifi/docker-compose.yml
# Check all options at the official repository:
# https://hub.docker.com/r/linuxserver/unifi-controller
version: "2.1"
services:
  unifi-controller:
    image: lscr.io/linuxserver/unifi-controller:latest
    container_name: unifi-controller
    environment:
      - PUID=1000 # Replace here the User ID from id Command
      - PGID=1000 # Replace here the Group ID from id Command
      - MEM_LIMIT=1024 #optional
      - MEM_STARTUP=1024 #optional
    volumes:
      # Persist all the configs at the folder below
      - ./config:/config
    ports:
      # If you are not using Caddy, use the ports below
      #- 8443:8443
      #- 8080:8080
      #- 3478:3478/udp
      #- 10001:10001/udp

      # if you are using Caddy, use the ports below
      - 7443:8443
      - 7080:8080
      #- 3478:3478/udp
      #- 10001:10001/udp

      # These ports are option, check the repo for more details
      #- 1900:1900/udp #optional
      #- 8843:8843 #optional
      #- 8880:8880 #optional
      #- 6789:6789 #optional
      #- 5514:5514/udp #optional
    restart: unless-stopped

Starting up

Start up the container and check the results

docker-compose up -d

You should be able to see the new container when running docker ps -a.

Configuring Caddy

You don't need to install Caddy if you are running within your local network. The automatic TLS will not work unless you have a public IP and your ports 80 and 443 are open so LetsEncrypt can verify your domain. Skip this step if you don't have a public IP/DNS set up.

Check how to install Caddy at their official docs https://caddyserver.com/docs/installopen in new window.

Then after installation, configure /etc/caddy/Caddyfile (this is the default location for most distributions).

# This config assume you have set up a DNS A entry pointing to your server
# Replace the domain below
yourDomain.com:8443 {
    # Note the port 8443 is the port exposed and 7443 is the internal port, used at the docker-compose.yml
    reverse_proxy 127.0.0.1:7443 {
        transport http {
            tls
            tls_insecure_skip_verify
        }
    }
}

For a Debian based system, reload the Caddy config using service caddy restart.

Linking your UniFi APs to the controller

Time to access https://yourDomain.com:8443.

If you are not using Caddy you will see a browser security error page, just continue since you do not have a certificate configured.

For the first access UniFi will ask you to set up all details about your network, create users and etc. Finish all those steps and then click at the AP list icon shown at the left side menu (it looks like an UniFi router).

Now for every AP, log in using the default user password ubnt

ssh ubnt@192.168.0.5 # Considering 192.168.0.5 is your AP IP
# Then point your AP to your controller
# Note the port here might be 8080 or 7080
set-inform http://yourDomain.com:7080/inform

Security notes

If you are exposing the UniFi controller to the internet, make sure to configure a firewall that allows only your network APs to communicate with the controller, otherwise rogue APs (or a malicious user) can abuse of UniFi open ports.

Last update: Jun 27, 2022