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.

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.

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.

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:

• The Docker Book: Containerization is the new virtualization
• Docker Cookbook: Solutions and Examples

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):

  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:

• The Docker Book: Containerization is the new virtualization
• Docker Cookbook: Solutions and Examples

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.

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.