From 80d80c099ff7b5eab470edcb3c8fa6012bf77a08 Mon Sep 17 00:00:00 2001
From: jramos <jordan.ramos@charter.com>
Date: Tue, 7 Apr 2026 12:09:27 -0600
Subject: [PATCH] docs: add NODE_ENV/Secure cookie warning and troubleshooting
 section to README

---
 README.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1389ca2..faf8a37 100644
--- a/README.md
+++ b/README.md
@@ -173,7 +173,7 @@ PORT=3001
 API_HOST=localhost
 CORS_ORIGINS=http://YOUR_IP:3000
 SESSION_SECRET=<generate with: openssl rand -base64 32>
-NODE_ENV=production
+# NODE_ENV=production  — see note below
 
 # Optional: NVD API key for higher rate limits (50 req/30s vs 5 req/30s)
 # Register at https://nvd.nist.gov/developers/request-an-api-key
@@ -191,6 +191,8 @@ IVANTI_SKIP_TLS=false
 
 **`SESSION_SECRET` is required.** The server will exit on startup if it is not set. Generate one with `openssl rand -base64 32`.
 
+**`NODE_ENV` and the Secure cookie flag:** When `NODE_ENV=production`, session cookies are set with the `Secure` flag, which means the browser will only send them over HTTPS connections. If you are running the application over plain HTTP (no TLS/SSL), you **must** leave `NODE_ENV` unset or set it to `development` — otherwise login will succeed but every subsequent API request will return 401 because the browser silently drops the cookie. Only set `NODE_ENV=production` when the application is served behind HTTPS (e.g., via a reverse proxy with TLS termination).
+
 ### Frontend: `frontend/.env`
 
 ```env
@@ -888,3 +890,38 @@ For deployments upgrading from an older schema, the following legacy migration s
 - `migrate-to-1.1.js` — General 1.0 → 1.1 schema update
 
 > Several columns (`fp_workflow_counts_json`, `fp_id_counts_json`, `seen_count`, `summary_json`) are added automatically via idempotent `ALTER TABLE` statements each time the server starts. No manual re-run is needed.
+
+---
+
+## Troubleshooting
+
+### Login succeeds but all pages show "Error Loading" / 401 Unauthorized
+
+**Symptom:** You can log in successfully, but the dashboard shows "Error Loading CVEs", "Failed to fetch", and the browser console shows 401 on every API call.
+
+**Cause:** The session cookie has the `Secure` flag set (because `NODE_ENV=production` in `backend/.env`), but the application is being accessed over plain HTTP. Browsers silently refuse to send `Secure` cookies over non-HTTPS connections, so every request after login arrives without a session cookie.
+
+**Fix:** Either:
+1. Remove `NODE_ENV=production` from `backend/.env` (or set it to `development`) and restart the backend, **or**
+2. Set up HTTPS (e.g., via nginx reverse proxy with TLS termination) and access the app over `https://`
+
+### Login fails with "Too many login attempts"
+
+**Cause:** The login endpoint is rate-limited to 20 attempts per 15-minute window. Wait 15 minutes or restart the backend to reset the counter.
+
+### Server refuses to start: "SESSION_SECRET environment variable must be set"
+
+**Fix:** Add a `SESSION_SECRET` to `backend/.env`:
+```bash
+echo "SESSION_SECRET=$(openssl rand -base64 32)" >> backend/.env
+```
+
+### After upgrading: "user_group" errors or missing group data
+
+**Fix:** Run the group migration:
+```bash
+cd backend
+node migrations/add_user_groups.js
+node migrations/add_created_by_columns.js
+```
+This maps existing roles to groups automatically (admin→Admin, editor→Standard_User, viewer→Read_Only).