How to Install UniFi Controller on Docker with Reverse Proxy (Traefik)?

In this guide, I will show you how to install UniFi controller on Docker with Traefik reverse proxy. UniFi devices require a controller software, which is one more thing to move and restore when switching servers/systems. With docker, all you have to do is setup the host sytem and run the docker compose all your apps with their settings can be up and running in minutes. This UniFi controller Docker guide shows how easy it is to accomplish this using Docker. Not only that, we will also put the controller software behind Traefik reverse proxy with automatic LetsEncrypt SSL certificates.

UniFi Basics

I am no expert on UniFi or networking but here are some basics for newbies. A typical home internet router packs 3 different units: an internet gateway, switch, and wireless access point. Most enterprise-class devices do not work this way. They split them up into individual units. Doing so allows for better control and scalability. For example, you can keep adding wireless access points, instead of a new router, to extend your Wifi network into new areas. There are several more advantages, but going over those is not the scope of this post.

UniFi line of networking gear is a highly recommended by many "Prosumers" even for home use. Here is an example schematic that shows a typical setup scenario with UniFi. Note that you can add as many wired access points as needed.

Unifi Controller Docker Guide - Example Unifi Setup
Example Unifi Setup

You may also add access points wirelessly (if you are unable to run ethernet cables), which create a "Mesh" network. Wired access points are always preferred over "Mesh" networks due to reliability and speed. Therefore, I prefer my UniFi setup over the Mesh products such as Google Wifi, Eero, Orbi, etc. I strong recommend this introductory video that describes the UniFi products.

Introduction to UniFi (Part 1): Why UniFi - Troy Hunt

Some may consider UniFi setup to be an overkill for home use. I was one of them. With the growth of smart home electronics, I realized the need for more control of my home network from privacy and security point of view. For example, putting your smart home devices that call home on a separate VLAN isolates it from other devices on your network providing a layer of security. In addition, they won't be able to sniff the presence of other devices on your network. My current UniFi setup includes:

  1. UniFi Security Gateway (USG)
  2. UniFi US-16-150W Switch
  3. UniFi AP AC Pro - 2 of them

UniFi access points can be powered over Ethernet (PoE). This means, if you have a CAT 6 cable connecting your AP to a PoE capable switch, then you do not need additional power source where the AP is located. Now, let's see how to install Unifi Controller software on Docker and manage your UniFi network.

UniFi Controller Software

UniFi devices require a UniFi Controller software to manage them and the network. There are multiple ways to run this software: Windows, Mac, Ubuntu/Linux. In addition, you may purchase a UniFi Cloud Key, which has the controller software embedded and plugs into the UniFi switch directly.

I first started out with running the UniFi controller software on Windows. It was a nightmare and started feeling some buyer's remorse. Then I put the controller software on my Ubuntu Home Server. Voila! It was so much more stable and worked great. This is how I was using it for a while. When Ubuntu 18.04 came out, I moved to Docker based Home Media Server. I even added a Traefik Reverse Proxy in front for privacy, convenience, security, and SSL support. I decided to extend this setup and decided to run the LinuxServer UniFi Controller image on my Docker. It was a struggle to figure out the Traefik reverse proxy part. But everything is working great now.

Unifi Docker Reverse Proxy - Unifi Controller Dashboard
Unifi Controller Dashboard

I know many of you are looking for a guide on implementing a good reverse proxy solution for UniFi Controller software. Hopefully, this UniFi Docker reverse proxy guide using Traefik is helpful. So let's get started.

Recommended Guides on Docker:

Install UniFi Controller on Docker

Step 1: Prerequisites

First, make sure that you have your Ubuntu Server setup with Docker. Next, ensure that you Traefik Reverse Proxy implemented correctly and the Traefik monitoring WebUI is active. Following, the these two guides is an absolute necessity prior to proceeding with this UniFi controller docker guide.

In this guide, we are going put UniFi controller in a separate subdomain: unifi.example.com. Ports 3478, 10001, 8080, 8081, 8443, 8880, and 6789 must be free on the host Ubuntu server. You will also need to have a domain name or a DDNS name as described in my Traefik guide. Now let's go ahead and install UniFi Controller on Docker with reverse proxy support from Traefik.

All of this is accomplished very easily using Docker Compose, which is what my Docker media server is built on. I am assuming that you have already created an external network called traefik_proxy. If not, please follow my Traefik tutorial and come back here. In addition, I am assuming that you already have a docker compose file and that it has the networks defined as follows:

networks:
  traefik_proxy:
    external:
      name: traefik_proxy
  default:
    driver: bridge

You should have this if you met all the requirements listed previously.

Step 2: Setup UniFi Controller using Docker Compose

To proxy UniFi controller behind Traefik, here is the code to add (copy-paste) in the docker-compose file (pay attention to blank spaces at the beginning of each line):

Note: In my GitHub repo (which should be your main source of reference for docker-compose examples as it has the most up-to-date information), I use several domain names: DOMAINNAME_HOME_SERVER (for my Docker Home Server on Synology), DOMAINNAME_CLOUD_SERVER (for my Dedicated Server in a Datacenter, with Proxmox), DOMAINNAME_SHB (domain name for this website), and DOMAINNAME_KHUB (domain name of another non-WordPress website I host). You may find any of these domain variables in my examples. Make sure to substitute this variable with your own.
  unifi:
    hostname: unifi
    image: linuxserver/unifi:latest
    restart: always
    container_name: "unifi"
    volumes:
      - ${USERDIR}/docker/unifi:/config
      - ${USERDIR}/docker/shared:/shared
    ports:
      - target: 3478
        published: 3478
        protocol: udp
        mode: host
      - target: 10001
        published: 10001
        protocol: udp
        mode: host
      - target: 8080
        published: 8080
        protocol: tcp
        mode: host
      - target: 8081
        published: 8081
        protocol: tcp
        mode: host
      - target: 8443
        published: XXXX
        protocol: tcp
        mode: host
      - target: 8880
        published: 8880
        protocol: tcp
        mode: host
      - target: 6789
        published: 6789
        protocol: tcp
        mode: host
    networks:
      - traefik_proxy
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
    labels:
      - "traefik.enable=true"
      - "traefik.tags=frontend"
      - "traefik.frontend.passHostHeader=true"
      - "traefik.admin.backend=unifi"
      - "traefik.admin.frontend.rule=Host:unifi.${DOMAINNAME}"
      - "traefik.admin.port=8443"
      - "traefik.admin.protocol=https"
      - "traefik.frontend.headers.SSLRedirect=true"
      - "traefik.frontend.headers.STSSeconds=315360000"
      - "traefik.frontend.headers.browserXSSFilter=true"
      - "traefik.frontend.headers.contentTypeNosniff=true"
      - "traefik.frontend.headers.forceSTSHeader=true"
      - "traefik.frontend.headers.SSLHost=example.com"
      - "traefik.frontend.headers.STSIncludeSubdomains=true"
      - "traefik.frontend.headers.STSPreload=true"
      - "traefik.frontend.headers.frameDeny=true"

Replace/Configure:

  1. XXXX - This is the port on which your UniFi controller will be available at using the web browser. It could be the same port as the container: 8443 (must be free). This setting is optional. Review other key points listed here.
  2. If you do not want to Traefik reverse proxy, you may remove the "networks" block and "labels" block or just set traefik.enable label to false.
  3. USERDIR, DOMAINNAME, PUID, PGID, and TZ are environmental variables that are set as described in my Traefik tutorial
  4. ${USERDIR}/docker/unifi is the location of the UniFi controller software data
  5. {USERDIR}/docker/shared is optional. This is where I store some of the files common to several containers.

Save your docker-compose.yml and exit.

Step 3: Additional Setup Steps for Traefik

There was one additional change I had to for Unifi Docker reverse proxy to work. I had to add the following line to my traefik.toml:

InsecureSkipVerify = true 

This is explained in my Traefik tutorial linked previously.

Step 4: Run Docker Compose and Verify

Next, run your docker compose file and check the logs for any errors:

docker-compose -f ${USERDIR}/docker/docker-compose.yml up -d ; docker-compose logs -tf --tail="50" unifi

If you see no error messages, press Ctrl C to exit. UniFi WebUI should be available at https://unifi.example.com.

Recommended Guides on Docker:

Importing Previous Settings and Troubleshooting

I was able to successfully import my previous settings. However, my access points went into an "adoption loop". In other words, they never finished adopting. Here is what I had to do to fix the adoption loop.

I had to to to UniFI settings->Controller, enable Override inform host with controller hostname/IP, and provide the LAN IP address of the host system running UniFi controller in Docker, as shown in the screenshot below.

Override Inform Hostname / Ip  - Install Unifi Controller On Docker
Override Inform Hostname / Ip

I recreated the UniFi docker container and I was back in business. My full Docker compose file for UniFi Controller is available on my GitHub page.

UniFi Controller Docker Guide - Closing Remarks

Installing and running Unifi Controller using Docker significantly simplifies the process of setting up UniFi controller software. To increase security, you may add an additional layer of HTTP Authentical using the traefik.frontend.auth.basic Traefik label. My setup has been running without any issues for 3 months now. And UniFi controller Docker upgrade process is automatic if you setup Watchtower as described in my Traefik reverse proxy guide for Docker. I am slowly becoming a big fan of UniFi products. Getting the UniFi controller software up and running was challenging but with Docker it has been a cakewalk. So go ahead install UniFi controller on Docker and check it out.

Be the 1 in 200,000. Help us sustain what we do.
25 / 150 by Dec 31, 2024
Join Us (starting from just $1.67/month)

Anand

Anand is a self-learned computer enthusiast, hopeless tinkerer (if it ain't broke, fix it), a part-time blogger, and a Scientist during the day. He has been blogging since 2010 on Linux, Ubuntu, Home/Media/File Servers, Smart Home Automation, and related HOW-TOs.