unifi

UniFi Network Application

guide-by-example

Purpose & Overview

Ubiquiti managment software for wifi access points and other ubiquiti hardware.

• Official site
• linuxserver github

UniFi is a web based managment software for Ubiquiti devices.
It is written in Java, utilizing the Spring Framework and using MongoDB as a database.
Docker image used here is provided by linuxserver.io

Migration from UniFi Controller

• Do the manual backup of your old instance, through webgui settings.
• Down the old container.
• Spin the new stuff
• Restore the backup

Extra Info & Rant

Previously called UniFi Controller

Ubiquiti morons decided to change the name to UniFi Network Application. Then also tried to go for name UniFi Network Server with a claim that its for selfhosted version. In docs and even in downloads they mostly use the application.
Though love that inside the webgui version its just Network 8.0.28

With this name change, linuxserver.io also changed the deployment so that mongo database is now a separate container.
Would not be a big issue, if mongo would not suck big time at initiating databases in new deployments, making it unnecessary complicated. Or if linuxserver.io could make a decision and write cleaner instructions instead of trying to teach to fish.
Also linuxserver.io official stance is to use older version of mongo v3.6 - v4.4
Reports are that raspberry pi 4 users need to go for that v3.6

Big help to get this going cleanly was this repo, from this reddit post.
First time Ive seen configs used in compose this way, saved a bother of doing a separate mounting of mongo-init.js, that for some reason did not work for me. Here it is improved a bit by using variables, so stuff can be set just in .env

Files and directory structure

/home/
└── ~/
    └── docker/
        └── unifi/
            ├── 🗁 mongo_db_data/
            ├── 🗁 unifi_data/
            ├── 🗋 .env
            └── 🗋 docker-compose.yml

• mongo_db_data/ - database data
• unifi_data/ - unifi configuration and other data
• .env - a file containing environment variables for docker compose
• docker-compose.yml - a docker compose file, telling docker how to run the containers

You only need to provide the files.
The directory is created by docker compose on the first run.

docker-compose

Compose should not need any changes, theres .env file for that.

Worth noting is use of configs to bypass the need for separate mongo-init.js file.
The use comes from this repo.

latest unifi version tag - here

docker-compose.yml

services:

  unifi-db:
    image: mongo:4
    container_name: unifi-db
    hostname: unifi-db
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./mongo_db_data:/data/db
    expose:
      - 27017
    configs:
      - source: init-mongo.js
        target: /docker-entrypoint-initdb.d/init-mongo.js

  unifi-app:
    image: lscr.io/linuxserver/unifi-network-application:8.4.59
    container_name: unifi-app
    hostname: unifi-app
    restart: unless-stopped
    env_file: .env
    depends_on:
      - unifi-db
    volumes:
      - ./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

networks:
  default:
    name: $DOCKER_MY_NETWORK
    external: true

configs:
  init-mongo.js:
    content: |
      db.getSiblingDB("$MONGO_DBNAME").createUser({user: "$MONGO_USER", pwd: "$MONGO_PASS", roles: [{role: "$MONGO_ROLE", db: "$MONGO_DBNAME"}]});
      db.getSiblingDB("${MONGO_DBNAME}_stat").createUser({user: "$MONGO_USER", pwd: "$MONGO_PASS", roles: [{role: "$MONGO_ROLE", db: "${MONGO_DBNAME}_stat"}]});

.env

# GENERAL
DOCKER_MY_NETWORK=caddy_net
TZ=Europe/Bratislava

#UNIFI LINUXSERVER.IO
PUID=1000
PGID=1000
MEM_LIMIT=1024
MEM_STARTUP=1024
MONGO_USER=unifi
MONGO_PASS=N9uHz2ct
MONGO_HOST=unifi-db
MONGO_PORT=27017
MONGO_DBNAME=unifi_db
MONGO_ROLE=dbOwner
# MONGO_TLS= #optional
# MONGO_AUTHSOURCE= #optional

Reverse proxy

Caddy v2 is used, details here.

Caddyfile

unifi.{$MY_DOMAIN} {
        encode gzip
        reverse_proxy unifi-app:8443 {
                transport http {
                        tls
                        tls_insecure_skip_verify
                }
        }
}

Adoption

The controller might see your APs during initial setup, but it can not adopt them before you set your docker host IP as Override Inform Host.

• Inform Host check the Override checbox
  Settings > System > Advanced
  
• enter docker-host IP
• adopt devices

Some Settings

• Disable "Connects high performance clients to 5 GHz only"
  Old interface > Settings > Wireless Networks > Edit > Advanced Options
  When enabled it forces devices to ignore 2.4GHz which obviously causes problems at range. Fucking monstrous stupidity to be default on, but I guess globaly they have power to cleanup 2.4GHz a bit.
• 802.11 DTIM Period - sets to 3
  Settings > Wifi > Edit > Advanced
  For apple devices
  

Migration

• old controller - settings - system - somewhere backup - just settings - you get a unf file
• new controller - on the first run theres an option to restore from backup, pick the file
• done

Config autobackup

config files should be in ~/unifi/unifi_data/data/backup

Encountered issues

Because I had ./mongo_db_data:/data as bind mount instead of ./mongo_db_data:/data/db, there was an issue. Everything worked fine for weeks, even shutdown of the docker host or sudden power outage... but on downing of the container and then upping, login would stop working with the notice "invalid username and/or password".

Update

Manual image update:

• docker-compose pull
  
• docker-compose up -d
  
• docker image prune