From 8aef51b59a185fca93a2ab76a7924edc9f768be6 Mon Sep 17 00:00:00 2001
From: jramos <jramos@apophisnetworking.net>
Date: Wed, 1 Apr 2026 12:47:50 -0600
Subject: [PATCH] fix(compliance): use PYTHON_BIN env var for venv support

Modern Debian/Ubuntu enforces PEP 668 which blocks system-wide pip
installs. The backend now reads PYTHON_BIN from the environment
(defaulting to 'python3') so each server can point to a venv.
Updates README with venv setup instructions.
---
 README.md                    | 22 +++++++++++++++++++---
 backend/routes/compliance.js |  3 ++-
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index e5a3709..4aaa0c2 100644
--- a/README.md
+++ b/README.md
@@ -68,7 +68,7 @@ The application provides:
 
 - Node.js 18 or later
 - npm
-- Python 3 with `pandas` and `openpyxl` (required for compliance xlsx parsing)
+- Python 3 with a venv containing `pandas` and `openpyxl` (required for compliance xlsx parsing)
 
 ---
 
@@ -97,13 +97,29 @@ npm install
 
 ### 4. Install Python dependencies
 
+Modern Debian/Ubuntu systems enforce PEP 668 and block system-wide pip installs. Create a virtual environment instead:
+
 ```bash
-cd backend/scripts
-pip install -r requirements.txt
+# Install venv support if needed
+apt install -y python3-venv python3-full
+
+# Create the venv (once per server, from the app root)
+python3 -m venv /home/cve-dashboard/venv
+
+# Install packages into the venv
+/home/cve-dashboard/venv/bin/pip install -r backend/scripts/requirements.txt
 ```
 
 Required packages: `pandas>=2.0.0`, `openpyxl>=3.0.0`
 
+Then set the `PYTHON_BIN` environment variable so the backend uses the venv Python:
+
+```bash
+export PYTHON_BIN=/home/cve-dashboard/venv/bin/python3
+```
+
+Add this to the server's startup environment (e.g., your systemd unit or `.env` file) so it persists across restarts. If `PYTHON_BIN` is not set, the backend falls back to the system `python3`.
+
 > The bulk notes import script (`import_notes_from_csv.py`) uses only Python stdlib and does **not** require these packages.
 
 ### 5. Initialize the database
diff --git a/backend/routes/compliance.js b/backend/routes/compliance.js
index 7299ef3..a9262e5 100644
--- a/backend/routes/compliance.js
+++ b/backend/routes/compliance.js
@@ -17,6 +17,7 @@ const fs       = require('fs');
 const { spawn } = require('child_process');
 
 const PARSER_SCRIPT = path.join(__dirname, '../scripts/parse_compliance_xlsx.py');
+const PYTHON_BIN    = process.env.PYTHON_BIN || 'python3';
 const TEMP_DIR      = path.join(process.cwd(), 'uploads', 'temp');
 const ALLOWED_TEAMS = new Set(['STEAM', 'ACCESS-ENG', 'ACCESS-OPS', 'INTELDEV']);
 
@@ -47,7 +48,7 @@ function dbAll(db, sql, params = []) {
 // ---------------------------------------------------------------------------
 function parseXlsx(filePath) {
     return new Promise((resolve, reject) => {
-        const py = spawn('python3', [PARSER_SCRIPT, filePath]);
+        const py = spawn(PYTHON_BIN, [PARSER_SCRIPT, filePath]);
         let out = '';
         let err = '';
         py.stdout.on('data', d => { out += d; });