cve-dashboard/docs/dns-migration-plan.md

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

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):

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):

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:

cd frontend && npm run build

Step 5: Restart the backend

systemctl restart cve-backend

Step 6: Verify access

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.