unifi-access-dashboard/README.md

# UniFi Access Badge-In Dashboard

A Dockerised Flask + SQLite attendance dashboard that receives real-time door unlock
webhooks from one or more **UniFi Access Developer API** controllers, resolves
badge holders to real names, and displays a unified live attendance table with
first/latest badge times, source controller, and ON TIME / LATE status.

**Multi-controller:** add as many UniFi Access controllers as the host can reach.
Webhooks are auto-registered when you add a controller from the UI.

---

## Requirements

- Linux host with Docker + Docker Compose (Unraid works great)
- One or more UniFi OS consoles running **UniFi Access 1.9.1 or later**
- Network reachability from the dashboard host to each controller on port **12445**
- A **Developer API token** from each UniFi Access controller you plan to add

---

## Step 1 — Open firewall port 12445 to each controller

The UniFi Access Open API runs exclusively on **port 12445** (HTTPS, self-signed cert).
The host running the dashboard must be able to reach each controller on that port.

In UniFi Network → Settings → Firewall & Security → Firewall Rules, add a **LAN IN** rule on each controller:

| Field | Value |
|---|---|
| Action | Accept |
| Protocol | TCP |
| Destination Port | 12445 |
| Source | the subnet your dashboard host lives on |

Verify from the dashboard host:

```bash
# Linux:
nc -zv 10.0.0.1 12445

# Windows PowerShell:
Test-NetConnection -ComputerName 10.0.0.1 -Port 12445
```

---

## Step 2 — Generate a Developer API token on each controller

> ⚠️ This token is **different** from the UniFi OS / Network API token.
> Creating it in the wrong place will result in 401 Unauthorized errors.

1. Open the UniFi OS console at `https://<controller-ip>` in a browser.
2. Open the **Access** app (blue door icon).
3. Go to **Settings → General → Advanced → API Token**.
4. Click **Create New**, name it, enable **all permission scopes**, and pick a validity period.
5. Click **Create** and **immediately copy the token** — it's only shown once.

Repeat for each controller you plan to add.

---

## Step 3 — Clone the repo on the host

```bash
cd /mnt/user/appdata
git clone https://github.com/jasonMPM/unifi-access-dashboard.git unifi-access-dashboard
cd unifi-access-dashboard
```

---

## Step 4 — Create your .env file

```bash
cp .env.example .env
nano .env
```

The `UNIFI_*` and `WEBHOOK_SECRET` values are **optional**. If set, they auto-create
a "Default" controller on first boot — handy for single-controller installs. You can
leave them blank and add every controller via the UI instead.

```dotenv
# Optional: seeds a "Default" controller on first boot
UNIFI_HOST=10.0.0.1
UNIFI_PORT=12445
UNIFI_API_TOKEN=YOUR_TOKEN_HERE
WEBHOOK_SECRET=

# Required
TZ=America/Chicago
DB_PATH=/data/dashboard.db

# Optional: override the URL the dashboard uses when registering webhooks
# DASHBOARD_BASE_URL=http://10.0.0.5:8000
```

> **Never commit `.env` to git.** It is listed in `.gitignore`.

---

## Step 5 — Build and start the container

```bash
cd /mnt/user/appdata/unifi-access-dashboard
/usr/bin/docker compose up -d --build
```

The container will:
- Build the image from the local `Dockerfile`
- Start Flask on port **8000**
- Create `/data/dashboard.db` inside the container (mapped to `./data/` on the host)
- If env-var credentials are set, seed a "Default" controller and sync its users
- Schedule a user-cache refresh every 6 hours for every enabled controller

Verify it's running:

```bash
/usr/bin/docker ps
/usr/bin/docker logs -f unifi-access-dashboard
```

---

## Step 6 — Add controllers from the UI

Navigate to:

```
http://<HOST-IP>:8000/
```

Click the **⚙ Controllers** button in the header. For each UniFi Access instance you want
to receive events from, fill in:

| Field | Value |
|---|---|
| **Name** | Friendly label shown in the Source column (e.g. "Main Office", "Warehouse") |
| **Host / IP** | Controller IP, e.g. `10.0.0.1` |
| **Port** | `12445` (don't change unless your controller is non-standard) |
| **Developer API Token** | Token from Step 2 |

Click **Add Controller**. The dashboard will:

1. Call the controller's `POST /webhooks/endpoints` with this dashboard's URL.
2. Store the returned webhook secret so it can verify incoming events (HMAC-SHA256).
3. Immediately sync the controller's user list to resolve names.

If the controller can't reach this dashboard at the URL shown in the form hint
(it uses `window.location.origin` by default), set `DASHBOARD_BASE_URL` in `.env`
and restart.

Per-controller actions in the modal:

| Action | Description |
|---|---|
| **Test** | Hits the controller's `/users` endpoint to confirm the token works |
| **Sync** | Pulls latest users from this controller right now |
| **Enable / Disable** | Pause ingestion + sync without deleting the controller |
| **Remove** | Deletes the webhook from the controller and wipes all its badge events from the dashboard |

---

## Dashboard controls

| Control | Description |
|---|---|
| **Date picker** | Choose which day to view |
| **Badged in by** | Set your on-time cutoff (HH:MM) |
| **Controller** | Filter the table to one controller, or show All |
| **Refresh** | Reload the table |
| **Sync Users** | Pull latest users from every enabled controller |
| **⚙ Controllers** | Add / manage controllers |
| **Reset Day** | Delete all badge records for the selected date (respects the Controller filter — testing only) |

### Dashboard columns

| Column | Description |
|---|---|
| **#** | Row number |
| **Name** | Resolved display name from UniFi Access |
| **Source** | Controller this badge event came from |
| **First Badge In** | Earliest door entry for the day — never changes once set |
| **Latest Badge In** | Most recent entry — shows *"— same"* if only one badge event |
| **Actor ID** | First 8 characters of the UniFi user UUID |
| **Status** | ON TIME (green) or LATE (red) based on first badge vs cutoff |

> The same physical person on two different controllers will appear as two rows
> (different controllers issue different user UUIDs). They're distinguishable
> by the Source column.

---

## Updating from GitHub

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

The SQLite database in `./data/` persists across rebuilds. On first start after
upgrading from a single-controller install, existing badge events are
automatically attached to the seeded "Default" controller — nothing to migrate
by hand.

---

## API reference

All endpoints are unauthenticated by design — this app assumes a LAN-only
deployment. Do not expose port 8000 to the internet without putting a
reverse proxy with auth in front of it.

| Method | Path | Params / Body | Description |
|---|---|---|---|
| `POST` | `/api/unifi-access/<controller_id>` | webhook body | Receives UniFi Access webhook for that controller |
| `POST` | `/api/unifi-access` | webhook body | Legacy alias — routes to the oldest controller |
| `GET` | `/api/first-badge-status` | `date`, `cutoff`, `controller_id?` | Returns first + latest badge per user |
| `GET` | `/api/controllers` | — | List configured controllers |
| `POST` | `/api/controllers` | `name`, `host`, `port`, `api_token` | Add a controller (also registers webhook) |
| `PATCH` | `/api/controllers/<id>` | `name?`, `enabled?` | Rename or enable/disable a controller |
| `DELETE` | `/api/controllers/<id>` | — | Remove a controller (deletes webhook + its events) |
| `POST` | `/api/controllers/<id>/test` | — | Test controller reachability + token |
| `POST` | `/api/controllers/<id>/sync` | — | Sync one controller's user cache immediately |
| `GET` | `/api/sync-users` | — | Sync every enabled controller |
| `DELETE` | `/api/reset-day` | `date`, `controller_id?` | Delete badge records for a date (optionally scoped to one controller) |

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| Add Controller fails with "webhook registration rejected" | Token invalid or wrong scope | Regenerate token in Access → Settings → General → API Token with all scopes enabled |
| Add Controller fails with a connection error | Host unreachable on port 12445 | Verify firewall rule from Step 1; `nc -zv <ip> 12445` from the dashboard host |
| Events arrive but signature is rejected | Webhook secret missing or stale | Remove the controller and re-add it (the dashboard re-registers and gets a fresh secret) |
| Source column says "—" | Pre-migration row with no controller_id | Restart the container; the migration runs on every boot |
| Names show as `Unknown (xxxxxxxx...)` | Users not synced yet for that controller | Click **Sync** in the Controllers modal |
| Webhook URL stored in controller points to the wrong address | Browser's origin isn't reachable from the controller | Set `DASHBOARD_BASE_URL` in `.env`, remove + re-add the controller |
| `Port 12445 connection refused` | Firewall blocking port | Add LAN IN firewall rule in UniFi Network (Step 1) |
| Dashboard shows stale names after a user rename | Cache not refreshed | Click **Sync Users** or wait for the 6-hour auto-sync |

---

## Security notes

- `.env` is excluded from git via `.gitignore` — never commit it.
- API tokens are stored **in plaintext** in the SQLite DB; the dashboard
  assumes a LAN-only deployment. Filesystem permissions on `./data/dashboard.db`
  are the only thing protecting them.
- All admin endpoints (`/api/controllers/*`, `/api/sync-users`, `/api/reset-day`)
  are **unauthenticated**. Do not expose port 8000 publicly. If external access
  is required, place Nginx, Traefik, or Caddy with HTTPS + auth in front of port `8000`.
- Each controller's `webhook_secret` is enforced via HMAC-SHA256 on incoming
  events so spoofed webhook posts from outside the LAN are rejected.