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

```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.