Add DNS migration plan for aegis.charterlab.com

Document the step-by-step plan to transition from IP:port access to
friendly DNS names (aegis.charterlab.com for production,
aegis-uat.charterlab.com for UAT). Covers cert regen, port change,
CORS update, CI/CD changes, and rollback procedure.

docs/dns-migration-plan.md

@@ -0,0 +1,140 @@
+# DNS Migration Plan — aegis.charterlab.com
+
+## Overview
+
+Transition from IP-based access to friendly DNS names for both production and UAT environments. No application architecture changes — Express continues to serve API + frontend on a single port over HTTPS.
+
+## DNS Entries Requested
+
+| Hostname | Points To | Environment |
+|---|---|---|
+| aegis.charterlab.com | 71.85.90.6 | Production |
+| aegis-uat.charterlab.com | 71.85.90.9 | UAT / Staging / Dev |
+
+## Pre-Migration State
+
+| Environment | Current Access | Port | TLS |
+|---|---|---|---|
+| Production | https://71.85.90.6:3001 | 3001 | Self-signed (CN=cve-dashboard.local) |
+| UAT | https://71.85.90.9:3001 | 3001 | Self-signed (CN=cve-dashboard.local) |
+
+## Target State
+
+| Environment | Access URL | Port | TLS |
+|---|---|---|---|
+| Production | https://aegis.charterlab.com | 443 | Self-signed (CN=aegis.charterlab.com) |
+| UAT | https://aegis-uat.charterlab.com | 443 | Self-signed (CN=aegis-uat.charterlab.com) |
+
+Users access the dashboard without specifying a port number.
+
+## Steps — Per Environment
+
+Execute these steps on each VM after the DNS entries are active.
+
+### Step 1: Verify DNS resolution
+
+```bash
+nslookup aegis.charterlab.com
+# Should resolve to 71.85.90.6 (production)
+
+nslookup aegis-uat.charterlab.com
+# Should resolve to 71.85.90.9 (UAT)
+```
+
+### Step 2: Regenerate TLS certs with correct CN and SAN
+
+**Production (71.85.90.6):**
+```bash
+cd /home/cve-dashboard/backend/certs
+openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
+  -subj '/CN=aegis.charterlab.com' \
+  -addext 'subjectAltName=DNS:aegis.charterlab.com,IP:71.85.90.6'
+```
+
+**UAT (71.85.90.9):**
+```bash
+cd /home/cve-dashboard/backend/certs
+openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes \
+  -subj '/CN=aegis-uat.charterlab.com' \
+  -addext 'subjectAltName=DNS:aegis-uat.charterlab.com,IP:71.85.90.9'
+```
+
+### Step 3: Update backend .env — change port and CORS
+
+**Production (`/home/cve-dashboard/backend/.env`):**
+```
+PORT=443
+CORS_ORIGINS=https://aegis.charterlab.com,https://71.85.90.6:3001,http://71.85.90.6:3000
+```
+
+**UAT (`/home/cve-dashboard/backend/.env`):**
+```
+PORT=443
+CORS_ORIGINS=https://aegis-uat.charterlab.com,https://71.85.90.9:3001,http://71.85.90.9:3000
+```
+
+> Keep the old IP-based origins in CORS for a transition period so existing bookmarks still work.
+
+### Step 4: Update frontend .env (if using absolute API base)
+
+Check `frontend/.env`:
+- If `REACT_APP_API_BASE=/api` (relative) — no change needed
+- If absolute (e.g., `https://71.85.90.6:3001/api`) — update to `https://aegis.charterlab.com/api` and rebuild:
+
+```bash
+cd frontend && npm run build
+```
+
+### Step 5: Restart the backend
+
+```bash
+systemctl restart cve-backend
+```
+
+### Step 6: Verify access
+
+```bash
+curl -sk https://aegis.charterlab.com/api/health
+# Should return: {"status":"ok","timestamp":"..."}
+
+curl -sk https://aegis-uat.charterlab.com/api/health
+# Should return: {"status":"ok","timestamp":"..."}
+```
+
+### Step 7: Update CI/CD pipeline variables
+
+In `.gitlab-ci.yml`, update the environment URLs and health check endpoints:
+
+| Variable | Old | New |
+|---|---|---|
+| Production environment URL | http://71.85.90.6:3001 | https://aegis.charterlab.com |
+| Staging environment URL | http://71.85.90.9:3100 | https://aegis-uat.charterlab.com |
+| Health check URLs in verify jobs | http/https with IP:port | https://hostname (port 443) |
+
+### Step 8: Update steering files
+
+Update `.kiro/steering/tech.md` Ports table to reflect new URLs.
+
+## VM Hostname
+
+No change needed. The VM hostname (OS-level `hostnamectl` value) is unrelated to DNS resolution. It only affects the shell prompt and syslog. Changing it is optional cosmetic preference — not a functional requirement.
+
+## Rollback
+
+If DNS causes issues, revert by changing `PORT=443` back to `PORT=3001` in `.env` and restarting. Users access via the old IP:port URL. DNS entries can remain — they just won't route to port 443 if the service isn't listening there.
+
+## Timeline
+
+1. Request DNS entries from network team
+2. Wait for propagation (verify with nslookup)
+3. Execute steps 2–6 on UAT first, verify
+4. Execute steps 2–6 on production
+5. Update CI/CD (step 7) and push
+6. Communicate new URLs to users
+
+## Notes
+
+- No reverse proxy (nginx) is needed. Express binds directly to port 443 since the service runs as root.
+- Self-signed certs will still trigger browser warnings. Users accept once and the warning does not recur. For a clean experience, request a cert from your internal CA for `aegis.charterlab.com`.
+- The old IP:port URLs will continue to work if port 3001 is kept in CORS. To fully decommission, remove the old port binding after confirming all users have switched.
+- Port 3001 will no longer be active after the change. If you want both to work during transition, bind to both ports (requires a code change to listen on two ports) or keep port 3001 temporarily by not changing PORT until all users have migrated.