unifi-access-dashboard/README.md

UniFi Access Badge-In Dashboard

A small Flask + SQLite web app that receives UniFi Access access.door.unlock webhooks and shows a dark, gold-accented dashboard of daily first badge-in times.

Features

• Receives UniFi Access webhooks for access.door.unlock events and stores them in SQLite.
• Modern dark UI with black background, gold accents, and on-time (green) vs late (red) status.
• Date picker and configurable "badged in by" cutoff time.
• Dockerised for easy deployment on Unraid.

Repository layout

• app.py – Flask application and API endpoints.
• requirements.txt – Python dependencies.
• Dockerfile – Container image definition.
• docker-compose.yml – Example compose file (works on Unraid).
• static/index.html – Single‑page dashboard UI.

UniFi Access configuration

1. Ensure you have UniFi Access running (UA Ultra / UA Hub Door Mini / G3 Intercom etc.).
2. In the UniFi Access web UI, open the API / developer section and create a Webhook:[web:24][web:25]
   • Method: POST.
   • URL: http://<UNRAID-IP>:8000/unifi-access-webhook (or behind HTTPS via reverse proxy).
   • Events: at least access.door.unlock.
3. Save and trigger a test door unlock. You should see webhook hits in the container logs and rows in events.db.

Building and running on Unraid

1. Create a public GitHub repository

1. On your workstation, create a new folder and put all files from this project in it.
2. Initialize a Git repo, commit, and push to GitHub (public or private with a token):

git init
git add .
git commit -m "Initial UniFi Access dashboard"
git branch -M main
git remote add origin https://github.com/<your-user>/<your-repo>.git
git push -u origin main

2. Add a new Docker template on Unraid

You can either use the Docker tab (Add Container) or deploy via the Unraid terminal.

Option A – Using Unraid GUI

1. Go to Docker → Add Container.
2. Set Name to unifi-access-dashboard.
3. For Repository, point to your GitHub repo using the GitHub URL with the Dockerfile as build context if you build externally, or build the image locally first (Option B). Unraid’s GUI typically expects an image name on Docker Hub; easiest approach is:
   • Build and push your image from a machine with Docker:

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

• Then in Unraid, set Repository to <your-user>/unifi-access-dashboard:latest.

4. Add a Port mapping: host 8000 → container 8000.
5. Add a Path mapping for persistent DB:
   • Host path: /mnt/user/appdata/unifi-access-dashboard/
   • Container path: /data
6. Add environment variable TZ to match your timezone (e.g., America/Chicago).
7. Apply to start the container.

Option B – Using docker-compose on Unraid

If you prefer to build directly on the Unraid box and pull source from GitHub:

1. SSH into Unraid.
2. Clone your GitHub repo:

cd /mnt/user/appdata
git clone https://github.com/<your-user>/<your-repo>.git unifi-access-dashboard
cd unifi-access-dashboard

3. (Optional) Adjust docker-compose.yml ports or paths.
4. Build and start:

docker compose up -d --build

5. The app will listen on port 8000 by default.

3. Verify the app

1. In a browser, open http://<UNRAID-IP>:8000/.
2. You should see the dark dashboard with date and cutoff selectors.
3. After some badge-in activity, click Refresh and verify that users show as ON TIME (green) or LATE (red) depending on the cutoff.

Environment and volumes

• DB_PATH (optional) – path to the SQLite file inside the container (defaults to /data/events.db via Dockerfile).
• Mount /data to persistent storage on Unraid so badge history survives container restarts.

Time zones and "on time" logic

• Webhook timestamps are stored in UTC with a Z suffix.
• The "badged in by" cutoff is interpreted in 24‑hour HH:MM format and compared against the stored time string for that day.
• If you need strict local‑time handling, you can extend app.py to convert UTC to your timezone before comparison.