Skip to content

UniFi Toolkit ​

UniFi Toolkit provides authenticated network-management tools using a local UniFi controller connection. Controller credentials are encrypted in its persistent SQLite database.

Prepare the guest using the host setup guide. Host-specific AI commands and private recovery details are in UniFi Toolkit · Internal Operations.

Access and configuration ​

SettingThis homelab
Host address10.120.40.100
Domainui.home.rwk.me
Normal accesshttps://ui.home.rwk.me
Direct accesshttp://10.120.40.100:8084
Project directory/docker/unifi-toolkit

For another homelab, use your own host address, domain, timezone, paths, and network policy. The addresses above describe internal access; the dashboard does not require a public router port forward.

Create the project ​

Run as a deployment account with Docker access on the prepared guest:

sh
sudo install -d -o "$(id -u)" -g "$(id -g)" -m 0750 /docker/unifi-toolkit
cd /docker/unifi-toolkit

Create compose.yaml with the following configuration. It is a documented example of the repository's pinned deployment, not a second deployment source file:

yaml
name: unifi-toolkit

services:
  unifi-toolkit:
    image: ghcr.io/crosstalk-solutions/unifi-toolkit:1.13.6@sha256:1b955163482e1434e27af8ed09a4d2366b1005b7d044fc97c9925d2b3123f9b6
    container_name: unifi-toolkit
    env_file: .env
    environment:
      DEPLOYMENT_TYPE: production
      DOMAIN: ui.home.rwk.me
      DATABASE_URL: sqlite+aiosqlite:////app/data/unifi_toolkit.db
      APP_PORT: "8000"
      LOG_LEVEL: INFO
      STALKER_REFRESH_INTERVAL: "60"
      WEBHOOK_ALLOW_PRIVATE_IPS: "false"
    ports:
      - "${SERVER_IP}:8084:8000"
    volumes:
      - ./data:/app/data
    security_opt:
      - no-new-privileges:true
    mem_limit: 2g
    cpus: 1.0
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test:
        [
          "CMD",
          "curl",
          "--fail",
          "--silent",
          "--output",
          "/dev/null",
          "http://127.0.0.1:8000/health",
        ]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s
    restart: unless-stopped

Create .env alongside it:

dotenv
SERVER_IP=10.120.40.100
TZ=America/Chicago
AUTH_USERNAME=admin
AUTH_PASSWORD_HASH=
ENCRYPTION_KEY=

Replace blank secrets and example credentials before starting. SERVER_IP must be an address assigned to the Docker host. Preserve existing keys and data when updating an installation. Protect the file with chmod 600 .env and keep it out of Git.

Configure authentication and data ​

Create local persistent storage:

sh
sudo install -d -o 1000 -g 1000 -m 0750 data

Set AUTH_USERNAME to your chosen application login. AUTH_PASSWORD_HASH must be a bcrypt hash, not the plain password; single-quote it in .env so Compose preserves dollar signs. ENCRYPTION_KEY must be a persistent Fernet key. For a new installation, the upstream setup wizard can generate these values. Run it in a separate trusted upstream checkout and transfer the values securely into this deployment's .env; retain this guide's reverse-proxy Compose layout.

Alternatively, on a host with Python bcrypt installed, generate a hash privately with python3 -c 'import bcrypt,getpass; print(bcrypt.hashpw(getpass.getpass().encode(), bcrypt.gensalt()).decode())'. Generate a Fernet-format key with python3 -c 'import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())'. Keep both generated values private and preserve the original encryption key with backups.

Change DOMAIN to the full dashboard hostname. DEPLOYMENT_TYPE=production enables authentication; the existing Nginx Proxy Manager supplies HTTPS, so a separate Caddy proxy is unnecessary. Keep private-IP webhooks disabled unless deliberately required.

Start and verify ​

Run only this Compose project:

sh
cd /docker/unifi-toolkit
docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 180
docker compose ps
docker compose logs --tail=100 unifi-toolkit

Keep logs private. Do not rerun the base guest provisioner to install or update one service; it upgrades the host and restarts Docker.

Configure DNS and HTTPS ​

Make ui.home.rwk.me resolve to Nginx Proxy Manager (10.120.40.101 in this lab). Add a proxy host:

SettingValue
Domainui.home.rwk.me
Schemehttp
Backend10.120.40.100
Port8084
WebSocketsEnabled
CertificateA certificate covering ui.home.rwk.me
Force SSL / HTTP/2Enabled

Use your own domain and certificate on another homelab. Apply a LAN/VPN access list appropriate to your users. A proxy access list does not restrict clients connecting directly to a backend port; use network filtering when the backend must be proxy-only.

Check both paths:

sh
curl --fail --silent --show-error --output /dev/null http://10.120.40.100:8084/health
curl --fail --silent --show-error --output /dev/null https://ui.home.rwk.me/health

Add the HTTPS health endpoint to Uptime Kuma, using TLS validation and a suitable check interval. Monitoring on the same VM cannot independently report that VM's outage.

Connect a controller ​

Sign in, then configure the controller's local URL, a dedicated local API key, and the actual site ID in the toolkit settings. Use Test Connection before saving. This lab's controller is https://10.120.5.1; use your own controller address rather than a cloud Site Manager URL. Prefer verified TLS; handle a self-signed certificate through an explicit, deliberate exception.

Check login/logout, rejection of unauthenticated API access, controller connectivity, and live WebSocket updates. Adding a controller does not require testing disruptive device blocks or firewall changes.

Check database migrations ​

sh
docker exec unifi-toolkit alembic current
docker exec unifi-toolkit alembic heads

The current revision must match the migration head. /health checks responsiveness, not complete schema state. Inspect startup migration errors; if initial table creation left an incomplete migration, stop the container, preserve its data, and follow the version-specific recovery instructions before restarting. Do not delete a populated database to repair it.

Maintenance and recovery ​

Preserve SQLite data, configuration, and the original Fernet key together. Losing or replacing that key makes stored controller credentials unreadable. The lab runner takes a stopped-data archive and checks migration state after updates. Restore a compatible image and database together when rolling back a schema-changing release.

The deployed files remain in the private homelab source directory. Keep these instructions aligned with source changes. Review release notes and preserve a recovery point before updating pinned images. After maintenance, repeat the checks and verify the main application function.