From dab378474261455e24aeb27df4e8994fef284f6e Mon Sep 17 00:00:00 2001 From: Jordan Ramos Date: Fri, 26 Jun 2026 09:04:05 -0600 Subject: [PATCH] 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 | 140 +++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/dns-migration-plan.md diff --git a/docs/dns-migration-plan.md b/docs/dns-migration-plan.md new file mode 100644 index 0000000..8025164 --- /dev/null +++ b/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.