dab3784742
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.
141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
# 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.
|