user auth documentation changes

2026-05-27 09:12:45 -05:00
parent 97be2d2908
commit 08401afd28
4 changed files with 116 additions and 31 deletions
@@ -152,6 +152,31 @@ Click **Add another Path, Port, Variable, Label or Device** for each:
 | Key | `DB_PATH` |
 | Value | `/data/cpas.db` |

+**Variable 3 — Admin Username**
+
+| Setting | Value |
+|---|---|
+| Config Type | `Variable` |
+| Name | `Admin Username` |
+| Key | `ADMIN_USERNAME` |
+| Value | `admin` |
+
+**Variable 4 — Admin Password**
+
+| Setting | Value |
+|---|---|
+| Config Type | `Variable` |
+| Name | `Admin Password` |
+| Key | `ADMIN_PASSWORD` |
+| Value | *(set a strong password — do not leave the default)* |
+
+> **Important:** The app requires login. The admin account is created from
+> `ADMIN_USERNAME` / `ADMIN_PASSWORD` on every start. **Always set a strong
+> `ADMIN_PASSWORD`** — the image ships with a placeholder (`changeme`) that must
+> be overridden. To rotate the admin password later, change this value and
+> **Restart** the container. Additional user accounts are created in-app by an
+> admin (top-right **Users** button) and are not affected by restarts.
+
 ---

 ### 5.6 Apply
@@ -167,8 +192,10 @@ Click **Add another Path, Port, Variable, Label or Device** for each:
 1. Docker tab → **cpas-tracker** should show a green icon
 2. Click the container icon → **WebUI**
   Or open: `http://[YOUR-UNRAID-IP]:3001`
-3. Confirm **● API connected** appears in the header
-4. Health check: `http://[YOUR-UNRAID-IP]:3001/api/health`
+3. A **login screen** appears. Sign in with the `ADMIN_USERNAME` / `ADMIN_PASSWORD`
+   you set in step 5.5.
+4. Confirm **● API connected** appears in the header
+5. Health check (no login required): `http://[YOUR-UNRAID-IP]:3001/api/health`
   → `{"status":"ok","timestamp":"..."}`

 ---
@@ -197,6 +224,8 @@ docker save cpas-tracker | gzip > cpas-tracker.tar.gz
 | Problem | Fix |
 |---|---|
 | Container won't start | Docker tab → container icon → **Logs** |
+| Can't log in / forgot admin password | Edit Container → set a new `ADMIN_PASSWORD` → **Restart**. The admin password re-syncs from this variable on every start. |
+| "ADMIN_PASSWORD not set" in logs | Add the `ADMIN_PASSWORD` variable (step 5.5) and restart — without it the admin account is not created. |
 | Port 3001 conflict | Change Host Port to `3002` in Edit Container |
 | "API unreachable" in UI | Confirm green icon, check Logs, try Restart |
 | DB permission error | Terminal: `chmod 755 /mnt/user/appdata/cpas/db` |
@@ -9,7 +9,7 @@
      html, body { margin: 0; padding: 0; height: 100%; }
      #root { height: 100%; }
    </style>
-    <script type="module" crossorigin src="/assets/index-CkShUZiL.js"></script>
+    <script type="module" crossorigin src="/assets/index-C1XYfYmx.js"></script>
    <link rel="stylesheet" crossorigin href="/assets/index-BoQf6yV_.css">
  </head>
  <body>
@@ -83,6 +83,33 @@ Internal tool for CPAS violation documentation, workforce standing management, a

 ---

+## Authentication & User Accounts
+
+The application is protected by a login screen. Every page and every API action requires a valid signed-in session — unauthenticated visitors cannot view or edit any CPAS data.
+
+### Signing in
+
+Open the app and enter your username and password in the login popup. A session lasts **7 days**, after which you'll be asked to sign in again. Use the **Logout** button in the top-right of the nav bar to end your session immediately.
+
+### The bootstrap admin
+
+A single admin account is created automatically from the container's environment variables (\`ADMIN_USERNAME\` / \`ADMIN_PASSWORD\`). Notes:
+
+- Its password is **owned by the Docker environment** — it re-syncs on every container start. To rotate it, change \`ADMIN_PASSWORD\` in the container settings and restart. It cannot be changed from the UI (a UI change would be overwritten on the next restart).
+- Set a strong \`ADMIN_PASSWORD\` at deploy time. The image ships with a placeholder default that must be overridden.
+
+### Managing users (admin only)
+
+Admins see a **Users** button in the nav bar that opens the user-management panel. From there you can:
+
+- **Add a user** — username, password (min 6 characters), and a role of **User** or **Admin**.
+- **Reset a password** for any account.
+- **Delete a user** — they lose access immediately. You cannot delete your own account.
+
+Roles: **Admin** can manage users plus everything a User can do; **User** can view and edit CPAS data but cannot manage accounts. Login attempts and all account changes are written to the audit log.
+
+---
+
 ## How Scoring Works

 Every violation carries a **point value** set at the time of submission. Points count toward an employee's score only within a **rolling 90-day window** — once a violation is older than 90 days it automatically drops off and the score recalculates.
@@ -264,6 +291,7 @@ Toasts auto-dismiss after a few seconds (errors persist longer). Each toast has
 - Acknowledgment signature field — employee name + date on form and PDF
 - Toast notification system — global feedback for all user actions
 - Backfill Snapshots — per-employee repair tool that rebuilds the prior-points snapshot on every violation when older PDFs drift from current data
+- Authentication — login screen gating all routes, env-bootstrapped admin account, and admin-managed user accounts with admin/user roles

 ---

@@ -272,7 +300,7 @@ Toasts auto-dismiss after a few seconds (errors persist longer). Each toast has
 These are well-scoped additions that fit the current architecture without major changes.

 - **CSV export** — one endpoint returning violations or dashboard data as a downloadable CSV for payroll or external reporting.
- **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments without requiring full auth.
+- **Supervisor-scoped view** — filter the dashboard to a single supervisor's team via URL param; useful in multi-supervisor environments.

 ---

@@ -291,7 +319,7 @@ Larger features that require more design work or infrastructure.

 These require meaningful infrastructure additions and should be evaluated against actual operational need before committing.

- **Multi-user auth** — role-based login (admin, supervisor, read-only). Currently the app assumes a trusted internal network with no authentication layer.
+- **Expanded roles** — finer-grained permissions beyond the current admin/user split (e.g. supervisor-scoped or read-only roles).
 - **Tier escalation alerts** — email or in-app notification when an employee crosses into Tier 2+, automatically routed to their supervisor.
 - **Scheduled digest** — weekly email summary to supervisors showing their employees' current standings and any approaching thresholds.
 - **Automated DB backup** — scheduled snapshot of the database to a mounted backup volume or remote destination.