From 0dd57b9d008d24eb7a05a01a84f82bbf9029672e Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Mon, 23 Mar 2026 19:48:55 -0700 Subject: [PATCH] fix(docs): distinguish NETWORK=corp local-dev topology from VM deployment --- docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md | 46 ++++++++++++--------- docs/devops/SINGLE_VM_DEPLOYMENT.md | 20 ++++++--- 2 files changed, 41 insertions(+), 25 deletions(-) diff --git a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md index b20a9ebe..6fb4778e 100644 --- a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md +++ b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md @@ -167,18 +167,23 @@ That script is currently the authoritative local rehearsal path for publishing ` The remaining blocker is not host-side package publishing or host-side package consumption. -The blocker is specifically: +### Network topology determines the Docker recipe -- Docker / BuildKit installs against the local Homebrew Gitea instance on this Mac -- the Docker-side auth path, where `host.docker.internal` reaches the registry but placeholder-token package fetches still fail with `401 Unauthorized` +| Topology | `NETWORK=` | Gitea host | Docker reaches Gitea via | `--add-host` needed? | +| ------------------- | ---------- | ------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------- | +| **Local dev (Mac)** | `corp` | `localhost:3300` | `host.docker.internal` + `--add-host localhost:host-gateway` | **Yes** — expected | +| **VM deployment** | (TBD) | `:3300` or compose service `gitea:3300` | Native Docker networking | **No** — `ROOT_URL` resolves natively | + +The `--add-host localhost:host-gateway` workaround is the **correct local-dev pattern** when `NETWORK=corp`, not a generic blocker. On a VM, Gitea's `ROOT_URL` will be set to the real hostname or compose service name, so tarball URLs resolve without any host-mapping workaround. At the time of writing: - host-side registry usage is validated - FlowMonk host-side pilot migration is validated -- FlowMonk backend/web Docker builds are validated locally with a real token plus `--add-host localhost:host-gateway`, but the default advertised tarball URL shape is still not clean enough to call this solved generically +- FlowMonk backend/web Docker builds are validated locally with the recipe below +- local Gitea CI is green for both FlowMonk and common-platform on current commits -Verified local FlowMonk Docker recipe on this Mac: +Verified local FlowMonk Docker recipe (`NETWORK=corp`): ```bash export TOKEN='' @@ -196,34 +201,37 @@ docker build \ -f web/Dockerfile /Users/sd9235/code/mygh/learning_ai_flowmonk ``` -That blocker must be resolved before we can claim full local E2E completion. +On the target VM, the recipe simplifies to just `--build-arg GITEA_NPM_HOST=` plus the BuildKit secret — no `--add-host` needed. --- ## 5.2 Remaining Gaps From Local Mac Validation -The local rehearsal on this Mac has proven enough to validate the **host-side** registry model, but it has **not** yet proven the full VM-ready or K8s-ready path. +The local rehearsal on this Mac has validated the **host-side** registry model, **Docker builds** (backend + web), and **local Gitea CI**. The `--add-host localhost:host-gateway` pattern is the correct local-dev recipe when `NETWORK=corp`; it is not needed on the target VM. -### Gaps still open on this Mac +### Validated ✅ -- Docker / BuildKit package installs from the local Homebrew Gitea instance are still not green -- the Homebrew Gitea `ROOT_URL` / package tarball URL behavior is still fragile across host and Docker boundaries -- Docker-side package installs currently need a real Gitea package token even though host-side installs only need non-empty `GITEA_NPM_TOKEN` env resolution for `.npmrc` -- FlowMonk backend/web Docker builds now work locally with `host.docker.internal` plus `--add-host localhost:host-gateway`, but that host-specific workaround should not yet be treated as the final VM-ready/default solution -- local Gitea Actions has not yet been validated end-to-end for the package build → publish → consumer flow -- the FlowMonk pilot is now validated for backend/web host-side consumption plus local Docker builds with the documented workaround; mobile remains outside the registry-backed pilot slice -- not all `@bytelyst/*` packages have been revalidated under the local Gitea registry with a fresh consumer install after the `pnpm pack` publish flow changes +- Host-side `pnpm install` against local Gitea registry +- FlowMonk backend/web Docker builds with BuildKit secret + `--add-host` (local-dev topology) +- Local Gitea CI green for FlowMonk and common-platform on current commits +- Runner re-registered against `127.0.0.1` (avoids IPv6 `[::1]` declaration failure) + +### Gaps still open + +- Docker-side package installs need a real Gitea package token (host-side only needs non-empty `GITEA_NPM_TOKEN` for `.npmrc` resolution) +- Local Gitea Actions has not yet been validated end-to-end for the package build → publish → consumer flow +- Mobile remains outside the registry-backed pilot slice +- Not all `@bytelyst/*` packages have been revalidated under the local Gitea registry with a fresh consumer install after the `pnpm pack` publish flow changes ### Why this matters for Azure Azure should be a replication step, not a redesign step. -That means the Azure VM rollout should wait until the remaining local gaps are cleared for: +On the VM, Gitea's `ROOT_URL` will point to the real hostname, so Docker containers will resolve tarball URLs natively — the `--add-host` workaround is local-dev only. The Azure VM rollout should wait until the remaining local gaps are cleared for: - package metadata correctness -- tarball URL correctness -- Docker consumer correctness -- local CI correctness +- Docker consumer correctness across all product repos (not just FlowMonk pilot) +- local CI correctness for the full build → publish → consume loop If we skip those validations locally, the first Azure VM trial becomes a debugging environment instead of a deployment environment. diff --git a/docs/devops/SINGLE_VM_DEPLOYMENT.md b/docs/devops/SINGLE_VM_DEPLOYMENT.md index ae7b53ca..8f99c928 100644 --- a/docs/devops/SINGLE_VM_DEPLOYMENT.md +++ b/docs/devops/SINGLE_VM_DEPLOYMENT.md @@ -714,12 +714,20 @@ The remaining work is concentrated more in the **build and package-distribution ## 5.2 Remaining Gaps Before Azure VM / K3s Rollout -### Local Mac rehearsal gaps still open +### Local Mac rehearsal — validated ✅ -- local Homebrew Gitea package metadata and tarball URLs are not yet reliable across both host installs and Docker builds -- FlowMonk backend/web Docker builds are now green locally only when using a real Gitea package token plus `--add-host localhost:host-gateway`; that workaround is not yet the final default/VM-ready shape -- local Gitea Actions has not yet been fully validated for the package publish + consumer install path -- the pilot registry migration is validated for FlowMonk backend/web host-side usage plus local Docker builds with the documented workaround, but not yet end-to-end across CI and all surfaces +- Host-side `pnpm install` against local Gitea registry +- FlowMonk backend/web Docker builds with BuildKit secret + `--add-host localhost:host-gateway` (`NETWORK=corp` local-dev topology) +- Local Gitea CI green for FlowMonk and common-platform on current commits +- Runner re-registered against `127.0.0.1` (avoids IPv6 `[::1]` declaration failure) + +The `--add-host localhost:host-gateway` pattern is the **correct local-dev recipe** when `NETWORK=corp`. On the target VM, Gitea's `ROOT_URL` will be the real hostname or compose service name, so tarball URLs resolve natively — no `--add-host` needed. + +### Local Mac rehearsal — gaps still open + +- Local Gitea Actions has not yet been fully validated for the package build → publish → consumer flow +- Not all `@bytelyst/*` packages have been revalidated under the local Gitea registry with a fresh consumer install +- Mobile remains outside the registry-backed pilot slice ### Azure VM readiness gaps @@ -1196,7 +1204,7 @@ This is fragile, slow, and must be repeated for every image rebuild. Gitea has a built-in npm registry at `http://gitea:3300/api/packages//npm/`. Publishing `@bytelyst/*` packages there means **all product repos install from the registry like any normal npm dependency** — no tarballs, no rewriting, no `docker-prep.sh`. -> **Current local rehearsal status on this Mac:** host-side package publishing and host-side consumer installs are validated. FlowMonk backend/web Docker builds are also locally green with the documented `host.docker.internal` + `--add-host localhost:host-gateway` workaround, but the Homebrew Gitea tarball URL shape is still not clean enough to treat that as the final VM-ready/default result. +> **Current local rehearsal status on this Mac:** host-side publishing, host-side consumer installs, and FlowMonk backend/web Docker builds are all validated. The `--add-host localhost:host-gateway` pattern is the correct local-dev recipe when `NETWORK=corp`. On the target VM, Gitea's `ROOT_URL` will be the real hostname or compose service name, so no `--add-host` workaround is needed. #### Setup (one-time)