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
+3. A **login screen** appears. Sign in with the `ADMIN_USERNAME` / `ADMIN_PASSWORD`
-4. Health check: `http://[YOUR-UNRAID-IP]:3001/api/health`
+   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.