docs(vercel): cross-reference Azure VM Caddy gateway — concrete gitea.bytelyst.com and api.bytelyst.com URLs across all roadmaps

2026-03-29 16:05:57 -07:00 · 2026-03-29 16:05:57 -07:00 · 8dd0036fc4
commit 8dd0036fc4
parent e6b625f4e2
13 changed files with 131 additions and 47 deletions
--- a/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md
+++ b/docs/devops/vercel/ECOSYSTEM_WEB_APPS_INVENTORY.md
@ -283,18 +283,47 @@

 ---

-## Prerequisite: Gitea NPM Registry on Azure VM
+## Prerequisite: Gitea NPM Registry via HTTPS on Azure VM

-All 12 product web apps (everything except admin-web and tracker-web which use `workspace:*`) pull `@bytelyst/*` packages from the local Gitea npm registry. Currently Gitea runs at `http://localhost:3300`, which Vercel can't reach.
+All 12 product web apps (everything except admin-web and tracker-web which use `workspace:*`) pull `@bytelyst/*` packages from the Gitea npm registry. Currently Gitea runs at `http://localhost:3300` on the Azure VM, which Vercel can't reach during builds.

-**Once Gitea is deployed to the Azure VM with a public HTTPS URL** (e.g., `https://gitea.bytelyst.com`), this blocker is eliminated for all apps simultaneously:
+### Solution: Expose Gitea via Caddy reverse proxy

-1. Update `.npmrc` in each repo: `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`
-2. Set `GITEA_NPM_TOKEN` as a Vercel environment variable per project
-3. All 49 `@bytelyst/*` packages are already published — no re-publishing needed
+The Azure VM deployment will use **Caddy** as the HTTPS gateway (see [`SECURE_API_EXPOSURE.md`](../single_azure_vm/docker/SECURE_API_EXPOSURE.md) for the full decision). Caddy provides automatic Let's Encrypt TLS and simple path/subdomain routing.
+
+**Gitea needs its own subdomain** because the npm registry API (`/api/packages/.../npm/`) expects to be at root:
+
+```
+https://gitea.bytelyst.com  →  gitea:3300  (Caddy reverse proxy, auto-TLS)
+https://api.bytelyst.com/*  →  backend services (path-based routing)
+```
+
+### Concrete steps to unblock all 12 apps
+
+1. **DNS:** Add `A` records for `api.bytelyst.com` and `gitea.bytelyst.com` pointing to the Azure VM IP
+2. **Caddy:** Add `gitea.bytelyst.com { reverse_proxy gitea:3300 }` to the Caddyfile
+3. **`.npmrc`** in each repo:
+   ```
+   @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+   //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+   ```
+4. **Vercel:** Set `GITEA_NPM_TOKEN` as an environment variable per project
+5. All 49 `@bytelyst/*` packages are already published — no re-publishing needed

 **This is the single highest-leverage fix in the ecosystem.** Once done, the per-app registry access gap disappears from every roadmap.

+### Backend API URLs for Vercel apps
+
+Apps that call backend APIs at runtime (not just at build time) will also benefit from the Caddy gateway. Instead of hardcoding `http://<vm-ip>:<port>`, apps will use:
+
+| Env Var                   | Value                                 |
+| ------------------------- | ------------------------------------- |
+| `PLATFORM_SERVICE_URL`    | `https://api.bytelyst.com/platform`   |
+| `EXTRACTION_SERVICE_URL`  | `https://api.bytelyst.com/extraction` |
+| `NEXT_PUBLIC_BACKEND_URL` | `https://api.bytelyst.com/<product>`  |
+
+See [`DEPLOYMENT_STATUS_2026-03-29.md`](../single_azure_vm/docker/DEPLOYMENT_STATUS_2026-03-29.md) for current VM status and verified healthy backends.
+
 ---

 ## Deployment Architecture on Vercel
--- a/docs/devops/vercel/ROADMAP_ACTIONTRAIL_WEB.md
+++ b/docs/devops/vercel/ROADMAP_ACTIONTRAIL_WEB.md
@ -32,9 +32,13 @@

 ### Gap 2: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 3 (optional): SSE Compatibility
@ -58,7 +62,7 @@ Vercel serverless functions have a 25-second timeout (Hobby) / 300s (Pro). SSE s

 ### Step 4: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_BACKEND_URL` — ActionTrail backend endpoint (port 4018)
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/actiontrail`

 ### Step 5: Verify (~10 min)

--- a/docs/devops/vercel/ROADMAP_CHRONOMIND_WEB.md
+++ b/docs/devops/vercel/ROADMAP_CHRONOMIND_WEB.md
@ -36,9 +36,13 @@ Both packages are already published to Gitea registry.

 ### Gap 2: Registry Access on Vercel (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL (e.g., `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`)
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 3: Serwist PWA Service Worker (~10 min)
--- a/docs/devops/vercel/ROADMAP_EFFORISE.md
+++ b/docs/devops/vercel/ROADMAP_EFFORISE.md
@ -48,7 +48,7 @@ The SPA proxies `/api` to the Fastify backend. On Vercel, options:

 - [ ] Choose proxy strategy
 - [ ] Update `vercel.json` or API client accordingly
- [ ] Set `VITE_BACKEND_URL` env var for API base URL
+- [ ] Set `VITE_BACKEND_URL` = `https://api.bytelyst.com/efforise`

 ### Gap 3: SPA Client-Side Routing (~5 min)

@ -58,9 +58,13 @@ The SPA proxies `/api` to the Fastify backend. On Vercel, options:

 ### Gap 4: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 5: Build Output Directory (~5 min)
--- a/docs/devops/vercel/ROADMAP_FLOWMONK_WEB.md
+++ b/docs/devops/vercel/ROADMAP_FLOWMONK_WEB.md
@ -33,9 +33,13 @@

 ### Gap 2: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 3 (optional): Add TailwindCSS
@ -58,7 +62,7 @@ Not a deployment blocker, but the app lacks TailwindCSS unlike all other ecosyst

 ### Step 4: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_BACKEND_URL` — FlowMonk backend endpoint (port 4017)
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/flowmonk`

 ### Step 5: Verify (~5 min)

--- a/docs/devops/vercel/ROADMAP_JARVISJR_WEB.md
+++ b/docs/devops/vercel/ROADMAP_JARVISJR_WEB.md
@ -29,6 +29,17 @@
 - [ ] Run `pnpm install`
 - [ ] Verify `pnpm build` passes

+### Gap 2: Registry Access on Vercel (~5 min)
+
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.
+
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
+- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
+
 ## Deployment Steps

 ### Step 1: Fix `file:` ref (~5 min)
@ -43,8 +54,8 @@

 ### Step 4: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — JarvisJr backend endpoint (port 4012)
+- [ ] `NEXT_PUBLIC_PLATFORM_URL` = `https://api.bytelyst.com/platform`
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/jarvisjr`

 ### Step 5: Verify (~5 min)

@ -54,8 +65,6 @@

 ### Step 6: Domain (~5 min)

-3
-
 - [ ] Add custom domain (e.g., `app.jarvisjr.app`)

-## Estimated Total Effort: ~40 minutes
+## Estimated Total Effort: ~30 minutes
--- a/docs/devops/vercel/ROADMAP_LLM_LAB.md
+++ b/docs/devops/vercel/ROADMAP_LLM_LAB.md
@ -46,7 +46,11 @@

 ### Gap 3: Registry Access (~5 min)

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 4: Disable/stub server-side routes (~30 min)
--- a/docs/devops/vercel/ROADMAP_LOCALMEMGPT_WEB.md
+++ b/docs/devops/vercel/ROADMAP_LOCALMEMGPT_WEB.md
@ -43,9 +43,13 @@

 ### Gap 3: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 4: Backend Connectivity (⚠️ Architecture concern)
@ -76,7 +80,7 @@ The web app is a thin client — all data comes from the local Fastify backend (

 ### Step 5: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_BACKEND_URL` — user's self-hosted backend URL
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/localmemgpt` (or user's self-hosted URL)

 ### Step 6: Verify (~5 min)

--- a/docs/devops/vercel/ROADMAP_MINDLYST_WEB.md
+++ b/docs/devops/vercel/ROADMAP_MINDLYST_WEB.md
@ -21,9 +21,13 @@

 ### Gap 1: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 2: Nested Root Directory (~2 min)
@ -52,9 +56,9 @@ Uses `tsconfig.build.json` for typecheck (`tsc --noEmit -p tsconfig.build.json`)
 - [ ] `MINDLYST_USER_ID` — Default user ID
 - [ ] `SEED_SECRET` — Seed endpoint secret
 - [ ] `OPENAI_API_KEY` — OpenAI API key (for triage)
- [ ] `EXTRACTION_SERVICE_URL` — extraction-service endpoint (port 4005)
- [ ] `PLATFORM_SERVICE_URL` — platform-service endpoint (port 4003)
- [ ] `NEXT_PUBLIC_PLATFORM_URL` — client-side platform URL
+- [ ] `EXTRACTION_SERVICE_URL` = `https://api.bytelyst.com/extraction`
+- [ ] `PLATFORM_SERVICE_URL` = `https://api.bytelyst.com/platform`
+- [ ] `NEXT_PUBLIC_PLATFORM_URL` = `https://api.bytelyst.com/platform`

 ## Deployment Steps

--- a/docs/devops/vercel/ROADMAP_NOMGAP_WEB.md
+++ b/docs/devops/vercel/ROADMAP_NOMGAP_WEB.md
@ -46,6 +46,17 @@
 - [ ] Update `next.config.ts` — conditional output mode
 - [ ] Verify Docker build still works (`output: standalone` still active without `VERCEL`)

+### Gap 3: Registry Access (~5 min)
+
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.
+
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
+- [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable
+
 ## Deployment Steps

 ### Step 1: Fix `file:` ref (~5 min)
@ -62,8 +73,9 @@

 ### Step 5: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — NomGap backend endpoint (port 4013)
+- [ ] `NEXT_PUBLIC_PLATFORM_URL` = `https://api.bytelyst.com/platform`
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/nomgap`
+- [ ] `GITEA_NPM_TOKEN` — Gitea npm token

 ### Step 6: Verify (~10 min)

@ -73,8 +85,6 @@

 ### Step 7: Domain (~5 min)

-4
-
 - [ ] Add custom domain (e.g., `app.nomgap.app`)

-## Estimated Total Effort: ~50 minutes
+## Estimated Total Effort: ~40 minutes
--- a/docs/devops/vercel/ROADMAP_NOTELETT_WEB.md
+++ b/docs/devops/vercel/ROADMAP_NOTELETT_WEB.md
@ -48,9 +48,13 @@

 ### Gap 3: Registry Access (~5 min)

-Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.
+Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ## Deployment Steps
@ -69,8 +73,8 @@ Once Gitea is deployed to the Azure VM with a public HTTPS URL, update `.npmrc`.

 ### Step 5: Environment Variables (~5 min)

- [ ] `NEXT_PUBLIC_PLATFORM_URL` — platform-service endpoint
- [ ] `NEXT_PUBLIC_BACKEND_URL` — NoteLett backend endpoint (port 4016)
+- [ ] `NEXT_PUBLIC_PLATFORM_URL` = `https://api.bytelyst.com/platform`
+- [ ] `NEXT_PUBLIC_BACKEND_URL` = `https://api.bytelyst.com/notelett`

 ### Step 6: Verify (~10 min)

--- a/docs/devops/vercel/ROADMAP_TRACKER_WEB.md
+++ b/docs/devops/vercel/ROADMAP_TRACKER_WEB.md
@ -27,7 +27,7 @@

 - [ ] `JWT_SECRET` — JWT signing secret
 - [ ] `AZURE_KEYVAULT_URL` — Azure Key Vault URL (optional)
- [ ] `PLATFORM_SERVICE_URL` — URL of platform-service API
+- [ ] `PLATFORM_SERVICE_URL` = `https://api.bytelyst.com/platform`
 - [ ] `NODE_ENV` = `production`

 ### Step 3: Verify Build (~5 min)
--- a/docs/devops/vercel/ROADMAP_USER_DASHBOARD.md
+++ b/docs/devops/vercel/ROADMAP_USER_DASHBOARD.md
@ -19,9 +19,13 @@

 ### Gap 1: Gitea Registry Access on Vercel (~5 min)

-The `.npmrc` currently points to local Gitea (`http://localhost:3300`). Once Gitea is deployed to the Azure VM with a public HTTPS URL, this is a simple `.npmrc` update.
+The `.npmrc` currently points to local Gitea (`http://localhost:3300`). Once Caddy is configured on the Azure VM (see [SECURE_API_EXPOSURE.md](../single_azure_vm/docker/SECURE_API_EXPOSURE.md)), Gitea will be accessible at `https://gitea.bytelyst.com`.

- [ ] Update `.npmrc` to use Azure VM Gitea URL (e.g., `@bytelyst:registry=https://gitea.bytelyst.com/api/packages/YOUR_ORG/npm/`)
+- [ ] Update `.npmrc`:
+  ```
+  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
+  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
+  ```
 - [ ] Set `GITEA_NPM_TOKEN` as a Vercel environment variable

 ### Gap 2: Environment Variables (~10 min)
@ -32,15 +36,15 @@ The `.npmrc` currently points to local Gitea (`http://localhost:3300`). Once Git
 - [ ] `STRIPE_SECRET_KEY` — Stripe server-side key
 - [ ] `STRIPE_PUBLISHABLE_KEY` — Stripe public key
 - [ ] `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — Client-side Stripe key
- [ ] `PLATFORM_SERVICE_URL` — platform-service endpoint
- [ ] `ACTIONTRAIL_SERVICE_URL` — ActionTrail backend
+- [ ] `PLATFORM_SERVICE_URL` = `https://api.bytelyst.com/platform`
+- [ ] `ACTIONTRAIL_SERVICE_URL` = `https://api.bytelyst.com/actiontrail`
 - [ ] `AZURE_KEYVAULT_URL` — AKV (optional)

 ## Deployment Steps

 ### Step 1: Fix Registry Access (~5 min)

- [ ] Update `.npmrc` to Azure VM Gitea URL
+- [ ] Update `.npmrc` to `gitea.bytelyst.com` registry
 - [ ] Set `GITEA_NPM_TOKEN` on Vercel

 ### Step 2: Create Vercel Project (~5 min)
@ -69,6 +73,6 @@ The `.npmrc` currently points to local Gitea (`http://localhost:3300`). Once Git

 - **Cosmos latency:** Same region concern as admin-web.
 - **Stripe webhooks:** Stripe webhook URL must be updated to Vercel domain.
- **Platform-service connectivity:** PLATFORM_SERVICE_URL must point to a publicly accessible endpoint (not localhost).
+- **Platform-service connectivity:** `PLATFORM_SERVICE_URL` → `https://api.bytelyst.com/platform` (requires Caddy gateway on Azure VM).

 ## Estimated Total Effort: ~35 minutes