Appearance
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
| Setting | This homelab |
|---|---|
| Host address | 10.120.40.100 |
| Domain | ui.home.rwk.me |
| Normal access | https://ui.home.rwk.me |
| Direct access | http://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-toolkitCreate 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-stoppedCreate .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 dataSet 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-toolkitKeep 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:
| Setting | Value |
|---|---|
| Domain | ui.home.rwk.me |
| Scheme | http |
| Backend | 10.120.40.100 |
| Port | 8084 |
| WebSockets | Enabled |
| Certificate | A certificate covering ui.home.rwk.me |
| Force SSL / HTTP/2 | Enabled |
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/healthAdd 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 headsThe 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.