bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(architecture): keep internal dashboards on VM Docker

Browse Source
This commit is contained in:
root 2026-03-31 06:39:13 +00:00
parent e174335a9e
commit 5cec039905
2 changed files with 60 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/devops/vercel/CODEX_PROMPTS_TRACK_A_AZURE_VM.md
View File

@ -17,14 +17,14 @@
| --- | ------------------------ | :------------: | :--------: | :------: |
| A1 | Caddy Gateway Setup | 🟨 In progress | — | ⬜ |
| A2 | Gitea HTTPS Exposure | ⬜ Not started | — | ⬜ |
| A3 | Dashboard Frontend Split | ⬜ Not started | — | ⬜ |
| A3 | Internal Dashboard Hosting | ⬜ Not started | — | ⬜ |
| A4 | NSG Lockdown | ⬜ Not started | — | ⬜ |
**Execution order:**
```
A1: Caddy Gateway ──→ A2: Gitea HTTPS ──→ A4: NSG Lockdown
└──→ A3: Dashboard Frontends on Vercel
└──→ A3: Internal Dashboards on VM Docker
```
---
@ -37,15 +37,16 @@ These VM-hosted DNS records must exist before Caddy can obtain Let's Encrypt cer
| ---------------------- | ---- | ---------------------- | ------------------- |
| `api.bytelyst.com` | A | `<Azure VM public IP>` | Backend API gateway |
| `gitea.bytelyst.com` | A | `<Azure VM public IP>` | Gitea npm registry |
| `admin.bytelyst.com` | CNAME or A | `<Vercel deployment>` | Admin frontend |
| `tracker.bytelyst.com` | CNAME or A | `<Vercel deployment>` | Tracker frontend |
| `admin.bytelyst.com` | A | `<Azure VM public IP>` | Internal admin UI |
| `tracker.bytelyst.com` | A | `<Azure VM public IP>` | Internal tracker UI |
**Verify DNS before starting A1:**
```bash
dig +short api.bytelyst.com # must return VM IP
dig +short gitea.bytelyst.com # must return VM IP
# admin/tracker should resolve to Vercel, not the VM
dig +short admin.bytelyst.com # must return VM IP
dig +short tracker.bytelyst.com # must return VM IP
```
---
@ -222,7 +223,7 @@ AFTER COMPLETING: Notify the operator that Track B → B4 (.npmrc migration) is
---
## A3: Move admin-web and tracker-web to Vercel
## A3: Keep admin-web and tracker-web on the VM in Docker
> **Depends on:** A1 ✅ for `api.bytelyst.com`
> **Blocks:** Nothing on the VM track
@ -231,54 +232,69 @@ AFTER COMPLETING: Notify the operator that Track B → B4 (.npmrc migration) is
### Preconditions
- [ ] `api.bytelyst.com` is live on the VM with HTTPS
- [ ] `admin.bytelyst.com` and `tracker.bytelyst.com` DNS A records resolve to the Azure VM IP
- [ ] `admin-web` and `tracker-web` source code is available in the repo
- [ ] Vercel project(s) exist or can be created for the dashboards
### Prompt
```
You are working on the ByteLyst deployment split where the Azure VM hosts only self-hosted infrastructure and backend APIs, while public frontend apps deploy on Vercel.
You are working on the ByteLyst deployment split where internal web apps stay on the Azure VM in Docker, while only clearly public sites may be deployed outside the VM later.
TASK: Move admin-web and tracker-web out of the VM hosting path and make them Vercel-hosted frontends that talk to the VM backend through https://api.bytelyst.com.
TASK: Keep admin-web and tracker-web on the Azure VM as Docker-hosted internal dashboards fronted by Caddy, and document the access-control expectations for those internal tools.
CONTEXT:
- The VM should host only self-hosted and backend services
- Internal/admin/operator-facing web apps should stay on the VM
- admin-web and tracker-web are Next.js frontends from learning_ai_common_plat under dashboards/
- Their public domains should be:
- Their hostnames should be:
- https://admin.bytelyst.com
- https://tracker.bytelyst.com
- Those domains should point to Vercel, not the VM
- Those domains should point to the VM, not Vercel
- Browser/API configuration should use the VM backend entrypoint at https://api.bytelyst.com
- These dashboards are internal surfaces and should not be treated as public sites
TASK LIST:
- [ ] 1. Audit both dashboards for browser-visible backend URLs and replace VM-local assumptions with the public API hostname
- [ ] 2. Document the required Vercel env vars for both apps
- [ ] 3. Ensure `admin.bytelyst.com` and `tracker.bytelyst.com` DNS point to Vercel, not the VM
- [ ] 4. Remove dashboard host-routing assumptions from the VM/Caddy plan
- [ ] 5. Update deployment docs to record the frontend/backend split
- [ ] 1. Audit both dashboards for browser-visible backend URLs and ensure they use https://api.bytelyst.com where appropriate
- [ ] 2. Confirm both dashboard containers are part of the VM compose topology and expose only Docker-internal ports
- [ ] 3. Add Caddy host blocks for:
- admin.bytelyst.com -> admin-web:3001
- tracker.bytelyst.com -> tracker-web:3003
- [ ] 4. Ensure `admin.bytelyst.com` and `tracker.bytelyst.com` DNS A records point to the VM
- [ ] 5. Update deployment docs to record that internal dashboards stay on the VM in Docker
- [ ] 6. Document required access controls for internal dashboards:
- app auth at minimum
- optional IP allowlist/VPN/SSO recommendation
- do not treat these as public sites
VERIFICATION (run all — every check must pass):
# DNS should no longer point at the VM
# DNS should point at the VM
dig +short admin.bytelyst.com
dig +short tracker.bytelyst.com
# Expected: Vercel-managed resolution, not the VM public IP
# Expected: VM public IP for both
# Frontends load on Vercel
# Frontends load through VM Caddy
curl -sI https://admin.bytelyst.com | head -3
curl -sI https://tracker.bytelyst.com | head -3
# Expected: HTTP 200 or 302 from Vercel-hosted apps
# Expected: HTTP 200 or 302 with valid TLS
# VM backend stays the single API entrypoint
curl -sf https://api.bytelyst.com/platform/health | jq -r '.status'
# Expected: ok
SUCCESS CRITERIA:
- admin.bytelyst.com is served by Vercel
- tracker.bytelyst.com is served by Vercel
- Both frontends use https://api.bytelyst.com for backend access
- The VM no longer needs dashboard routing or public dashboard ports
# Caddy config includes dashboard host routing
rg -n "admin.bytelyst.com|tracker.bytelyst.com" /opt/bytelyst/Caddyfile
COMMIT: docs(architecture): move dashboards to Vercel and keep VM backend-only
SUCCESS CRITERIA:
- admin.bytelyst.com is served by the VM through Caddy
- tracker.bytelyst.com is served by the VM through Caddy
- Both frontends use https://api.bytelyst.com for backend access
- The dashboards remain internal VM-hosted tools with documented access controls
DO NOT:
- Move admin/tracker to Vercel
- Treat admin/tracker as public-facing web apps
- Expose raw dashboard container ports publicly
COMMIT: docs(architecture): keep internal dashboards on VM Docker
```
---
@ -388,7 +404,7 @@ done
echo "--- Gitea npm registry ---"
curl -sf https://gitea.bytelyst.com/api/packages/ByteLyst/npm/@bytelyst%2ferrors | jq '.name'
echo "--- Dashboards (Vercel-hosted) ---"
echo "--- Dashboards (VM-hosted internal tools) ---"
curl -sI https://admin.bytelyst.com | head -1
curl -sI https://tracker.bytelyst.com | head -1

31
docs/devops/vercel/TRACK_A_HANDOFF_2026-03-29.md
View File

@ -4,9 +4,9 @@ This handoff captures the current state of Track A on the Azure VM at `/opt/byte
Architecture decision after this handoff:
- The VM should host only self-hosted infrastructure and backend APIs
- `api.bytelyst.com` and `gitea.bytelyst.com` should point to the VM
- `admin.bytelyst.com` and `tracker.bytelyst.com` should be Vercel-hosted frontends, not VM-hosted services
- The VM should host self-hosted infrastructure, backend APIs, and internal web tools in Docker
- `api.bytelyst.com`, `gitea.bytelyst.com`, `admin.bytelyst.com`, and `tracker.bytelyst.com` should point to the VM
- Only clearly public-facing sites should be considered for Vercel later
## What Was Completed
@ -37,12 +37,7 @@ At the time of the original session, these records did not resolve from the VM:
- `admin.bytelyst.com`
- `tracker.bytelyst.com`
For the revised architecture:
- `api.bytelyst.com` and `gitea.bytelyst.com` must resolve to the VM
- `admin.bytelyst.com` and `tracker.bytelyst.com` should resolve to Vercel, not the VM
Only the VM-hosted records are prerequisites for A1/A2/A4.
For the current architecture, all four records must resolve to the VM.
### 2. Azure CLI is installed, but the active subscription context still needs validation
@ -81,7 +76,7 @@ dig +short gitea.bytelyst.com
curl -sf https://api.ipify.org && echo
```
3. Point `admin.bytelyst.com` and `tracker.bytelyst.com` at Vercel, not the VM.
3. Point `admin.bytelyst.com` and `tracker.bytelyst.com` at the VM, not Vercel.
4. Verify Azure account context and switch to the correct active subscription if needed:
```bash
@ -162,10 +157,16 @@ gitea-npm-registry
### A3
1. Do not treat `admin-web` and `tracker-web` as VM-hosted production surfaces.
2. Deploy them to Vercel and configure them to use `https://api.bytelyst.com`.
3. Point `admin.bytelyst.com` and `tracker.bytelyst.com` to Vercel.
4. Do not add dashboard routes to `/opt/bytelyst/Caddyfile`.
1. Keep `admin-web` and `tracker-web` as VM-hosted internal dashboards.
2. Configure them to use `https://api.bytelyst.com` for browser/backend access.
3. Add Caddy host routing for:
- `admin.bytelyst.com` -> `admin-web:3001`
- `tracker.bytelyst.com` -> `tracker-web:3003`
4. Point `admin.bytelyst.com` and `tracker.bytelyst.com` DNS to the VM.
5. Document access controls for these internal dashboards:
- app auth at minimum
- optional IP allowlist, VPN, or SSO
- no public raw container port exposure
### A4
@ -184,5 +185,5 @@ Suggested commits:
- `feat(gateway): replace Traefik with Caddy for HTTPS path routing`
- `feat(gateway): expose Gitea npm registry via HTTPS at gitea.bytelyst.com`
- `docs(architecture): move dashboards to Vercel and keep VM backend-only`
- `docs(architecture): keep internal dashboards on VM Docker`
- `chore(security): lock down Azure NSG to 22/80/443 only`