unifi-access-dashboard/README.md

UniFi Access Badge-In Dashboard (V2)

A Dockerised Flask + SQLite web app that receives UniFi Access access.door.unlock webhooks, resolves UUID actor IDs to real user names via the UniFi Access API, and displays a modern dark dashboard with on-time / late status per person.

---

Features

• Receives access.door.unlock webhooks from either the UniFi Access developer API or the legacy Alarm Manager format.
• Resolves blank user_name UUIDs to real names by querying the UniFi Access REST API on a schedule (every 6 hours) and caching results in SQLite.
• Manual Sync Users button in the UI triggers an immediate cache refresh.
• Dark theme with gold accents, green ON TIME / red LATE status chips.
• Date picker + configurable "badged in by" cutoff time.
• Fully Dockerised — single container, persisted SQLite volume.

---

Project layout

.
├── app.py                 # Flask application
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example           # Copy to .env and fill in your values
├── .gitignore
└── static/
    └── index.html         # Dashboard UI

---

Step 1 — Generate a UniFi Access API token

1. Open your UniFi OS web interface.
2. Navigate to UniFi Access → Settings → Integrations (or the Developer API section).
3. Create a new API Key (Bearer Token). Copy it — you will need it below.

Use a dedicated read-only admin account to generate the token if possible.

---

Step 2 — Create your .env file

Copy .env.example to .env and fill in your values:

cp .env.example .env

UNIFI_HOST=192.168.1.1          # IP of your UniFi OS controller
UNIFI_API_TOKEN=YOUR_TOKEN_HERE
TZ=America/Chicago
DB_PATH=/data/dashboard.db

Never commit .env to git. It is listed in .gitignore.

---

Step 3 — Register the webhook with UniFi Access

Run this once from any machine on the same LAN as your controller (replace placeholders):

curl -k -X POST "https://192.168.1.1:45/api1/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Unlock Events",
    "endpoint": "http://YOUR_UNRAID_IP:8000/api/unifi-access",
    "events": ["access.door.unlock"],
    "headers": { "X-Source": "unifi-access" }
  }'

Verify it was registered:

curl -k -X GET "https://192.168.1.1:45/api1/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

You should see your webhook listed with a unique id.

Note: The UniFi Access API runs on port 45 over HTTPS with a self-signed cert. Always pass -k to curl, or verify=False in Python requests.

---

Step 4 — Deploy on Unraid

Clone from GitHub and build locally

SSH into your Unraid server:

cd /mnt/user/appdata
git clone https://github.com/<your-user>/<your-repo>.git unifi-access-dashboard
cd unifi-access-dashboard
cp .env.example .env
nano .env   # fill in UNIFI_HOST and UNIFI_API_TOKEN
docker compose up -d --build

The app is now running on port 8000.

Unraid GUI (Docker tab — Add Container)

If you prefer using the GUI after pushing an image to Docker Hub:

# On your workstation:
docker build -t <your-dockerhub-user>/unifi-access-dashboard:latest .
docker push <your-dockerhub-user>/unifi-access-dashboard:latest

Then in Unraid → Docker → Add Container:

Field	Value
Name	unifi-access-dashboard
Repository	<your-dockerhub-user>/unifi-access-dashboard:latest
Port	Host 8000 → Container 8000
Path	Host /mnt/user/appdata/unifi-access-dashboard/data → Container /data
Env: UNIFI_HOST	192.168.1.x
Env: UNIFI_API_TOKEN	your-token
Env: TZ	America/Chicago

---

Step 5 — Open the dashboard

Browse to:

http://<UNRAID-IP>:8000/

• Choose a date and set the "Badged in by" cutoff time (e.g. 09:00).
• Click Refresh to load the day's first badge-in per person.
• Green chip = on time. Red chip = late.
• Click Sync Users to immediately pull the latest user list from your UniFi Access controller.

---

Keeping the user cache fresh

The app automatically re-syncs users from UniFi Access every 6 hours in the background. If you add or rename a badge holder, click Sync Users in the dashboard or restart the container.

---

Troubleshooting

Symptom	Cause	Fix
Names show as Unknown (UUID…)	Users not yet cached	Click Sync Users or wait for the 6-hour job
Webhook not arriving	Firewall / Docker network	Ensure port 8000 is reachable from the UniFi controller
curl returns SSL error	Self-signed cert	Add -k to bypass; already handled in Python
404 on /api1/users	Firmware difference	Try /api/v1/users; check your Access app version
Duplicate events	Both Alarm Manager and API webhook active	Remove one, or they will both store rows (harmless but duplicates)
Container exits	.env missing	Ensure .env exists and docker compose up picks it up

---

Updating from GitHub

cd /mnt/user/appdata/unifi-access-dashboard
git pull
docker compose up -d --build

---

Security notes

• The .env file is excluded from git via .gitignore.
• The UniFi API token is never exposed to the frontend.
• Mount /data to persistent storage so badge history survives container restarts.
• For external access, place a reverse proxy (Nginx/Traefik) with HTTPS in front.