docs(deploy): clarify vm vs vercel hosting split
This commit is contained in:
parent
705f58c5c5
commit
477891fb4a
@ -58,64 +58,81 @@ docker compose -f docker-compose.ecosystem.yml ps
|
||||
|
||||
---
|
||||
|
||||
## Deployment Split
|
||||
|
||||
This compose stack is the VM-hosted side of the ecosystem.
|
||||
|
||||
- **Azure VM / Docker:** backend services, shared infrastructure, internal dashboards, and internal product web surfaces
|
||||
- **Vercel:** only clearly public-facing portal web surfaces
|
||||
|
||||
Examples:
|
||||
|
||||
- keep `admin-web` and `tracker-web` on the VM
|
||||
- keep product backends on the VM
|
||||
- only deploy user-facing portal experiences to Vercel when they are intended to be public-facing browser surfaces
|
||||
|
||||
Do not assume every web app belongs on Vercel.
|
||||
|
||||
---
|
||||
|
||||
## Port Map
|
||||
|
||||
### Infrastructure
|
||||
|
||||
| Service | Port | URL |
|
||||
|---------|------|-----|
|
||||
| Cosmos DB Emulator | 8081 | http://localhost:8081 |
|
||||
| Cosmos Data Explorer | 1234 | http://localhost:1234 |
|
||||
| Azurite (Blob) | 10000 | http://localhost:10000 |
|
||||
| Mailpit SMTP | 1025 | — |
|
||||
| Mailpit UI | 8025 | http://localhost:8025 |
|
||||
| Loki | 3100 | http://localhost:3100 |
|
||||
| Grafana | 3000 | http://localhost:3000 |
|
||||
| Traefik Dashboard | 8080 | http://localhost:8080 |
|
||||
| Service | Port | URL |
|
||||
| -------------------- | ----- | ---------------------- |
|
||||
| Cosmos DB Emulator | 8081 | http://localhost:8081 |
|
||||
| Cosmos Data Explorer | 1234 | http://localhost:1234 |
|
||||
| Azurite (Blob) | 10000 | http://localhost:10000 |
|
||||
| Mailpit SMTP | 1025 | — |
|
||||
| Mailpit UI | 8025 | http://localhost:8025 |
|
||||
| Loki | 3100 | http://localhost:3100 |
|
||||
| Grafana | 3000 | http://localhost:3000 |
|
||||
| Traefik Dashboard | 8080 | http://localhost:8080 |
|
||||
|
||||
### Platform Services
|
||||
|
||||
| Service | Port | URL |
|
||||
|---------|------|-----|
|
||||
| platform-service | 4003 | http://localhost:4003/health |
|
||||
| Service | Port | URL |
|
||||
| ------------------ | ---- | ---------------------------- |
|
||||
| platform-service | 4003 | http://localhost:4003/health |
|
||||
| extraction-service | 4005 | http://localhost:4005/health |
|
||||
| mcp-server | 4007 | http://localhost:4007/health |
|
||||
| mcp-server | 4007 | http://localhost:4007/health |
|
||||
|
||||
### Platform Dashboards
|
||||
|
||||
| Dashboard | Port | URL |
|
||||
|-----------|------|-----|
|
||||
| Dashboard | Port | URL |
|
||||
| ------------- | ---- | --------------------- |
|
||||
| Admin Console | 3001 | http://localhost:3001 |
|
||||
| Issue Tracker | 3003 | http://localhost:3003 |
|
||||
|
||||
### Product Backends
|
||||
|
||||
| Product | Port | URL |
|
||||
|---------|------|-----|
|
||||
| PeakPulse | 4010 | http://localhost:4010/health |
|
||||
| ChronoMind | 4011 | http://localhost:4011/health |
|
||||
| JarvisJr | 4012 | http://localhost:4012/health |
|
||||
| NomGap | 4013 | http://localhost:4013/health |
|
||||
| MindLyst | 4014 | http://localhost:4014/health |
|
||||
| LysnrAI | 4015 | http://localhost:4015/health |
|
||||
| NoteLett | 4016 | http://localhost:4016/health |
|
||||
| FlowMonk | 4017 | http://localhost:4017/health |
|
||||
| Product | Port | URL |
|
||||
| ----------- | ---- | ---------------------------- |
|
||||
| PeakPulse | 4010 | http://localhost:4010/health |
|
||||
| ChronoMind | 4011 | http://localhost:4011/health |
|
||||
| JarvisJr | 4012 | http://localhost:4012/health |
|
||||
| NomGap | 4013 | http://localhost:4013/health |
|
||||
| MindLyst | 4014 | http://localhost:4014/health |
|
||||
| LysnrAI | 4015 | http://localhost:4015/health |
|
||||
| NoteLett | 4016 | http://localhost:4016/health |
|
||||
| FlowMonk | 4017 | http://localhost:4017/health |
|
||||
| ActionTrail | 4018 | http://localhost:4018/health |
|
||||
| LocalMemGPT | 4019 | http://localhost:4019/health |
|
||||
|
||||
### Product Web Apps
|
||||
|
||||
| Product | Port | URL |
|
||||
|---------|------|-----|
|
||||
| Product | Port | URL |
|
||||
| ----------------- | ---- | --------------------- |
|
||||
| LysnrAI Dashboard | 3002 | http://localhost:3002 |
|
||||
| ChronoMind | 3030 | http://localhost:3030 |
|
||||
| JarvisJr | 3035 | http://localhost:3035 |
|
||||
| FlowMonk | 3040 | http://localhost:3040 |
|
||||
| NoteLett | 3045 | http://localhost:3045 |
|
||||
| MindLyst | 3050 | http://localhost:3050 |
|
||||
| NomGap | 3055 | http://localhost:3055 |
|
||||
| ActionTrail | 3060 | http://localhost:3060 |
|
||||
| LocalMemGPT | 3070 | http://localhost:3070 |
|
||||
| ChronoMind | 3030 | http://localhost:3030 |
|
||||
| JarvisJr | 3035 | http://localhost:3035 |
|
||||
| FlowMonk | 3040 | http://localhost:3040 |
|
||||
| NoteLett | 3045 | http://localhost:3045 |
|
||||
| MindLyst | 3050 | http://localhost:3050 |
|
||||
| NomGap | 3055 | http://localhost:3055 |
|
||||
| ActionTrail | 3060 | http://localhost:3060 |
|
||||
| LocalMemGPT | 3070 | http://localhost:3070 |
|
||||
|
||||
---
|
||||
|
||||
@ -158,9 +175,11 @@ docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem down -v
|
||||
## Troubleshooting
|
||||
|
||||
### Cosmos emulator slow to start
|
||||
|
||||
The emulator needs 20-30s on first boot. Other services wait via `depends_on: condition: service_healthy`.
|
||||
|
||||
### Port conflicts
|
||||
|
||||
If a port is already in use (e.g., Grafana on 3000), either stop the conflicting process or override the host port:
|
||||
|
||||
```bash
|
||||
@ -170,10 +189,13 @@ docker compose -f docker-compose.ecosystem.yml --env-file .env.ecosystem up -d \
|
||||
```
|
||||
|
||||
### LocalMemGPT needs Ollama
|
||||
|
||||
LocalMemGPT connects to Ollama on the host via `host.docker.internal:11434`. Make sure Ollama is running locally.
|
||||
|
||||
### Build failures for product repos
|
||||
|
||||
Product Dockerfiles use the Gitea npm registry for `@bytelyst/*` packages. If building on a fresh machine, ensure:
|
||||
|
||||
1. `GITEA_NPM_TOKEN` is set in your environment
|
||||
2. Gitea is running at `localhost:3300`
|
||||
3. All 49 `@bytelyst/*` packages are published
|
||||
@ -222,20 +244,21 @@ sudo ./setup.sh --reset
|
||||
|
||||
### Phases
|
||||
|
||||
| Phase | Description |
|
||||
|-------|-------------|
|
||||
| 1 | System dependencies (Docker, Node.js 22, pnpm, Ollama) |
|
||||
| 2 | Gitea npm registry (container on :3300) |
|
||||
| 3 | Clone 11 repositories from GitHub |
|
||||
| 4 | Build all @bytelyst/* packages |
|
||||
| 5 | Publish packages to Gitea npm registry |
|
||||
| 6 | Generate `.env.ecosystem` config |
|
||||
| 7 | Build + deploy 30 Docker services (per-service, with fallback) |
|
||||
| 8 | Health check (30 endpoints) |
|
||||
| Phase | Description |
|
||||
| ----- | -------------------------------------------------------------- |
|
||||
| 1 | System dependencies (Docker, Node.js 22, pnpm, Ollama) |
|
||||
| 2 | Gitea npm registry (container on :3300) |
|
||||
| 3 | Clone 11 repositories from GitHub |
|
||||
| 4 | Build all @bytelyst/\* packages |
|
||||
| 5 | Publish packages to Gitea npm registry |
|
||||
| 6 | Generate `.env.ecosystem` config |
|
||||
| 7 | Build + deploy 30 Docker services (per-service, with fallback) |
|
||||
| 8 | Health check (30 endpoints) |
|
||||
|
||||
### Per-Service Build & Fallback
|
||||
|
||||
Phase 7 builds each of the 30 services individually:
|
||||
|
||||
- **Pre-built images** (infra: cosmos-emulator, azurite, etc.) are detected and skipped
|
||||
- **Failed builds** are skipped — remaining services still start
|
||||
- **Build logs** are saved per-service to `/opt/bytelyst/.setup-state/builds/<service>.log`
|
||||
|
||||
@ -11,6 +11,16 @@ Related:
|
||||
|
||||
---
|
||||
|
||||
## Deployment Rule
|
||||
|
||||
- **Azure VM / Docker:** all backend services, shared infrastructure, internal dashboards, internal portals, and internal product web surfaces
|
||||
- **Vercel:** only clearly public-facing portal web surfaces
|
||||
- `admin-web`, `tracker-web`, and similar operator-facing apps stay on the Azure VM behind the VM ingress and access controls
|
||||
- Product backend APIs do not move to Vercel by default
|
||||
- Do not treat every web app as a Vercel candidate; internal/admin/operator-facing surfaces stay on the VM unless explicitly reclassified
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Azure VM:** Ubuntu 24.04 LTS (or 22.04), **Standard_D8s_v5** (8 vCPU, 32 GB RAM) recommended
|
||||
|
||||
@ -328,12 +328,13 @@ See [`DEPLOYMENT_STATUS_2026-03-29.md`](../single_azure_vm/docker/DEPLOYMENT_STA
|
||||
|
||||
## Deployment Architecture on Vercel
|
||||
|
||||
This section only covers **public-facing portal web surfaces** that are valid Vercel candidates.
|
||||
Internal dashboards and internal portals should remain on the Azure VM.
|
||||
|
||||
### Recommended Vercel project structure:
|
||||
|
||||
```
|
||||
Vercel Organization: ByteLyst
|
||||
├── bytelyst-admin ← admin-web (common-plat monorepo)
|
||||
├── bytelyst-tracker ← tracker-web (common-plat monorepo)
|
||||
├── lysnrai-portal ← user-dashboard-web
|
||||
├── chronomind-web ← learning_ai_clock/web
|
||||
├── jarvisjr-web ← learning_ai_jarvis_jr/web
|
||||
@ -348,11 +349,11 @@ Vercel Organization: ByteLyst
|
||||
└── (skip) llm-lab-dashboard ← NOT viable on Vercel (needs local Ollama)
|
||||
```
|
||||
|
||||
### Monorepo apps (admin-web, tracker-web)
|
||||
### Internal dashboards not targeted for Vercel
|
||||
|
||||
- Single Vercel project connected to `learning_ai_common_plat` repo
|
||||
- Root directory set to `dashboards/admin-web/` or `dashboards/tracker-web/`
|
||||
- `pnpm` detected automatically; `workspace:*` deps resolved
|
||||
- `admin-web` stays on the Azure VM as an internal ops/admin surface
|
||||
- `tracker-web` stays on the Azure VM as an internal tracker surface
|
||||
- both should be fronted by the VM ingress and internal access controls, not Vercel hosting
|
||||
|
||||
### Product web apps (all others)
|
||||
|
||||
@ -368,8 +369,6 @@ Each app has a dedicated roadmap in this folder:
|
||||
|
||||
| App | Roadmap File |
|
||||
| ------------------------ | -------------------------------------------------------------- |
|
||||
| Admin Dashboard | [`ROADMAP_ADMIN_WEB.md`](./ROADMAP_ADMIN_WEB.md) |
|
||||
| Tracker Dashboard | [`ROADMAP_TRACKER_WEB.md`](./ROADMAP_TRACKER_WEB.md) |
|
||||
| User Dashboard (LysnrAI) | [`ROADMAP_USER_DASHBOARD.md`](./ROADMAP_USER_DASHBOARD.md) |
|
||||
| ChronoMind Web | [`ROADMAP_CHRONOMIND_WEB.md`](./ROADMAP_CHRONOMIND_WEB.md) |
|
||||
| JarvisJr Web | [`ROADMAP_JARVISJR_WEB.md`](./ROADMAP_JARVISJR_WEB.md) |
|
||||
|
||||
@ -1,56 +1,31 @@
|
||||
# Admin Dashboard — Vercel Deployment Roadmap
|
||||
# Admin Dashboard — VM-Hosted Internal Surface
|
||||
|
||||
> **App:** `@bytelyst/admin-web`
|
||||
> **Repo:** `learning_ai_common_plat` → `dashboards/admin-web/`
|
||||
> **Status:** ✅ Ready
|
||||
> **Status:** Do not deploy to Vercel
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
## Deployment Decision
|
||||
|
||||
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4, shadcn/ui
|
||||
- **Output:** Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`)
|
||||
- **Dependencies:** 13 `@bytelyst/*` packages via `workspace:*` (monorepo — Vercel resolves automatically)
|
||||
- **Build:** `next build --webpack`
|
||||
- **Server-side:** Azure Cosmos DB, AKV, JWT, bcryptjs
|
||||
- **No `file:` references** — all deps are workspace or npm
|
||||
- `admin-web` is an internal ops/admin console.
|
||||
- It should stay on the single Azure VM with the internal operational stack.
|
||||
- It should be exposed only through VM-managed ingress and internal access controls.
|
||||
|
||||
## Deployment Steps
|
||||
## Why It Stays On The VM
|
||||
|
||||
### Step 1: Create Vercel Project (~5 min)
|
||||
- internal/admin/operator-facing surface
|
||||
- tightly coupled to VM-hosted operational tooling and internal services
|
||||
- not a public-facing portal
|
||||
|
||||
- [ ] Connect `learning_ai_common_plat` repo to Vercel
|
||||
- [ ] Set **Root Directory** to `dashboards/admin-web`
|
||||
- [ ] Framework preset: **Next.js**
|
||||
- [ ] Build command: `pnpm build` (auto-detected)
|
||||
- [ ] Output directory: `.next` (auto-detected)
|
||||
## Hosting Rule
|
||||
|
||||
### Step 2: Configure Environment Variables (~10 min)
|
||||
- host on the Azure VM
|
||||
- keep behind internal controls
|
||||
- do not create or maintain a Vercel deployment target for this app
|
||||
|
||||
- [ ] `COSMOS_ENDPOINT` — Azure Cosmos DB endpoint
|
||||
- [ ] `COSMOS_KEY` — Azure Cosmos DB key
|
||||
- [ ] `JWT_SECRET` — JWT signing secret
|
||||
- [ ] `SEED_SECRET` — Seed endpoint secret
|
||||
- [ ] `AZURE_KEYVAULT_URL` — Azure Key Vault URL (optional — for AKV secret resolution)
|
||||
- [ ] `NODE_ENV` = `production`
|
||||
## Related Docs
|
||||
|
||||
### Step 3: Verify Build (~5 min)
|
||||
|
||||
- [ ] Trigger first deploy
|
||||
- [ ] Verify security headers are applied (CSP, HSTS, X-Frame-Options)
|
||||
- [ ] Test login flow with JWT auth
|
||||
- [ ] Verify Cosmos DB connectivity from Vercel serverless functions
|
||||
|
||||
### Step 4: Domain Configuration (~5 min)
|
||||
|
||||
- [ ] Add custom domain (e.g., `admin.bytelyst.com`)
|
||||
- [ ] Verify SSL certificate auto-provisioning
|
||||
|
||||
## Risks & Notes
|
||||
|
||||
- **Cosmos DB latency:** Vercel serverless functions run in specific regions. Ensure Cosmos DB region matches Vercel deployment region (recommend `iad1` for eastus).
|
||||
- **Cold starts:** Server-side pages that hit Cosmos will have cold start latency (~1-2s). Consider ISR for static-friendly pages.
|
||||
- **CSP headers:** Current CSP allows `connect-src` to `*.documents.azure.com` — correct for Cosmos.
|
||||
- **Webpack flag:** Build uses `--webpack` — Vercel respects this via the build command override.
|
||||
|
||||
## Estimated Total Effort: ~25 minutes
|
||||
- [`../single_azure_vm/docker/README.md`](../single_azure_vm/docker/README.md)
|
||||
- [`TRACK_A_HANDOFF_2026-03-29.md`](./TRACK_A_HANDOFF_2026-03-29.md)
|
||||
- [`GODADDY_DNS_SETUP_BYTELYST.md`](./GODADDY_DNS_SETUP_BYTELYST.md)
|
||||
|
||||
@ -1,50 +1,31 @@
|
||||
# Tracker Dashboard — Vercel Deployment Roadmap
|
||||
# Tracker Dashboard — VM-Hosted Internal Surface
|
||||
|
||||
> **App:** `@bytelyst/tracker-web`
|
||||
> **Repo:** `learning_ai_common_plat` → `dashboards/tracker-web/`
|
||||
> **Status:** ✅ Ready
|
||||
> **Status:** Do not deploy to Vercel
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
## Deployment Decision
|
||||
|
||||
- **Framework:** Next.js 16.1.6, React 19.2.3, TailwindCSS v4
|
||||
- **Output:** Vercel-aware (`process.env.VERCEL ? {} : { output: 'standalone' }`)
|
||||
- **Dependencies:** 6 `@bytelyst/*` packages via `workspace:*` (monorepo)
|
||||
- **Build:** `next build --webpack`
|
||||
- **Server-side:** AKV secret resolution only (via instrumentation.ts)
|
||||
- **No `file:` references**
|
||||
- `tracker-web` is an internal tracker surface.
|
||||
- It should stay on the single Azure VM with the internal dashboards and shared service ingress.
|
||||
- It should not be maintained as a Vercel deployment target.
|
||||
|
||||
## Deployment Steps
|
||||
## Why It Stays On The VM
|
||||
|
||||
### Step 1: Create Vercel Project (~5 min)
|
||||
- internal operational workflow surface
|
||||
- aligned with VM-hosted admin and backend services
|
||||
- not intended as a public-facing portal web app
|
||||
|
||||
- [ ] Connect `learning_ai_common_plat` repo to Vercel (or reuse org if admin-web already connected)
|
||||
- [ ] Set **Root Directory** to `dashboards/tracker-web`
|
||||
- [ ] Framework preset: **Next.js**
|
||||
## Hosting Rule
|
||||
|
||||
### Step 2: Configure Environment Variables (~5 min)
|
||||
- host on the Azure VM
|
||||
- keep behind internal controls
|
||||
- do not create or maintain a Vercel deployment target for this app
|
||||
|
||||
- [ ] `JWT_SECRET` — JWT signing secret
|
||||
- [ ] `AZURE_KEYVAULT_URL` — Azure Key Vault URL (optional)
|
||||
- [ ] `PLATFORM_SERVICE_URL` = `https://api.bytelyst.com/platform`
|
||||
- [ ] `NODE_ENV` = `production`
|
||||
## Related Docs
|
||||
|
||||
### Step 3: Verify Build (~5 min)
|
||||
|
||||
- [ ] Trigger deploy
|
||||
- [ ] Verify public roadmap page loads (`/roadmap`)
|
||||
- [ ] Test item submission and voting
|
||||
- [ ] Verify security headers
|
||||
|
||||
### Step 4: Domain Configuration (~5 min)
|
||||
|
||||
- [ ] Add custom domain (e.g., `tracker.bytelyst.com`)
|
||||
|
||||
## Notes
|
||||
|
||||
- **pretest script:** Has a `pretest` script that builds workspace deps — Vercel won't run this, but `pnpm build` in the root handles workspace resolution.
|
||||
- **Lighter footprint:** Fewer server-side deps than admin-web. Mostly a client-side app that calls platform-service APIs.
|
||||
- **Bundle size:** Has `bundlesize` checks configured — good for monitoring after deploy.
|
||||
|
||||
## Estimated Total Effort: ~20 minutes
|
||||
- [`../single_azure_vm/docker/README.md`](../single_azure_vm/docker/README.md)
|
||||
- [`TRACK_A_HANDOFF_2026-03-29.md`](./TRACK_A_HANDOFF_2026-03-29.md)
|
||||
- [`GODADDY_DNS_SETUP_BYTELYST.md`](./GODADDY_DNS_SETUP_BYTELYST.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user