From 7302ece958416cfc7a9788a6f16a08cdb078c987 Mon Sep 17 00:00:00 2001
From: jramos <jordan.ramos@charter.com>
Date: Tue, 7 Apr 2026 13:43:50 -0600
Subject: [PATCH] docs: add Upgrade section and Troubleshooting TOC link to
 README

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index faf8a37..65ebc65 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,9 @@ A self-hosted vulnerability management dashboard for the NTS-AEO-STEAM and NTS-A
 - [Architecture](#architecture)
 - [Database Schema](#database-schema)
 - [Security Model](#security-model)
+- [Upgrading an Existing Deployment](#upgrading-an-existing-deployment)
 - [Migrations](#migrations)
+- [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -862,6 +864,64 @@ Applied to all responses:
 
 ---
 
+## Upgrading an Existing Deployment
+
+This procedure updates the application code and schema while preserving all existing data. The database file (`backend/cve_database.db`) is never overwritten by `git pull` — it is gitignored.
+
+```bash
+# 1. Stop the running servers
+cd /home/cve-dashboard
+./stop-servers.sh
+
+# 2. Pull latest code
+git pull origin master
+
+# 3. Install backend dependencies (picks up any new packages)
+npm install
+
+# 4. Install frontend dependencies
+cd frontend
+npm install
+cd ..
+
+# 5. Ensure SESSION_SECRET is set in backend/.env
+#    If missing:
+#    echo "SESSION_SECRET=$(openssl rand -base64 32)" >> backend/.env
+
+# 6. Run all migrations (idempotent — safe to re-run, skips already-applied changes)
+cd backend
+node migrations/add_knowledge_base_table.js
+node migrations/add_archer_tickets_table.js
+node migrations/add_ivanti_sync_table.js
+node migrations/add_ivanti_findings_tables.js
+node migrations/add_ivanti_todo_queue_table.js
+node migrations/add_card_workflow_type.js
+node migrations/add_todo_queue_ip_address.js
+node migrations/add_compliance_tables.js
+node migrations/add_finding_archive_tables.js
+node migrations/add_archer_tickets_timestamps.js
+node migrations/add_ivanti_counts_history_table.js
+node migrations/add_user_groups.js
+node migrations/add_created_by_columns.js
+cd ..
+
+# 7. Rebuild the frontend
+cd frontend
+npm run build
+cd ..
+
+# 8. Start servers
+./start-servers.sh
+```
+
+After upgrading, clear your browser cookies and log in fresh — session format changes between versions will invalidate old sessions.
+
+> **Do not re-run `node setup.js`** on an existing deployment. It is only for first-time initialization. Re-running it will not destroy data (it checks for existing tables/users), but it is unnecessary and may create a duplicate admin account.
+
+> **NODE_ENV reminder:** If you are running over plain HTTP (no TLS), make sure `NODE_ENV` is **not** set to `production` in `backend/.env`. See [Troubleshooting](#troubleshooting) for details.
+
+---
+
 ## Migrations
 
 Migrations are standalone Node.js scripts. Run them in the listed order on a fresh install. All are idempotent and safe to re-run.