diff --git a/docs/devops/ECOSYSTEM_DEPLOYMENT.md b/docs/devops/ECOSYSTEM_DEPLOYMENT.md index 08435be0..08e6c526 100644 --- a/docs/devops/ECOSYSTEM_DEPLOYMENT.md +++ b/docs/devops/ECOSYSTEM_DEPLOYMENT.md @@ -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/.log` diff --git a/docs/devops/single_azure_vm/docker/README.md b/docs/devops/single_azure_vm/docker/README.md index 64c20e0c..17c79eb0 100644 --- a/docs/devops/single_azure_vm/docker/README.md +++ b/docs/devops/single_azure_vm/docker/README.md @@ -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 diff --git a/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md b/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md index b3c8577a..510f9368 100644 --- a/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md +++ b/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md @@ -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) | diff --git a/docs/devops/vercel/ROADMAP_ADMIN_WEB.md b/docs/devops/vercel/ROADMAP_ADMIN_WEB.md index dfbee81c..79979771 100644 --- a/docs/devops/vercel/ROADMAP_ADMIN_WEB.md +++ b/docs/devops/vercel/ROADMAP_ADMIN_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) diff --git a/docs/devops/vercel/ROADMAP_TRACKER_WEB.md b/docs/devops/vercel/ROADMAP_TRACKER_WEB.md index 95795a8d..be9cadd8 100644 --- a/docs/devops/vercel/ROADMAP_TRACKER_WEB.md +++ b/docs/devops/vercel/ROADMAP_TRACKER_WEB.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)