From 5ba9518722d62324f6579d844cf2e102ee461832 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Tue, 24 Mar 2026 15:57:20 -0700 Subject: [PATCH] docs: update Gitea registry docs for NETWORK-aware GITEA_NPM_HOST - GITEA_NPM_REGISTRY_MIGRATION.md: update .npmrc examples, add home row to network topology table, note switch-network.sh sets the host - SINGLE_VM_DEPLOYMENT.md: consolidate .npmrc example to show unified ${GITEA_NPM_HOST}:3300 pattern (host-side + Docker-side) - GITEA_LOCAL_CI.md: add NPM registry host note to Key Settings --- docs/devops/GITEA_LOCAL_CI.md | 1 + docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md | 11 +++++++---- docs/devops/SINGLE_VM_DEPLOYMENT.md | 11 ++++------- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/devops/GITEA_LOCAL_CI.md b/docs/devops/GITEA_LOCAL_CI.md index e68c56f7..47181d9e 100644 --- a/docs/devops/GITEA_LOCAL_CI.md +++ b/docs/devops/GITEA_LOCAL_CI.md @@ -57,6 +57,7 @@ git push gitea main - **Gitea port:** 3300 (avoids conflict with Next.js dev servers on 3000) - **Actions URL:** `github` (Gitea resolves action references via GitHub mirror) - **Git credential helper:** Configured globally for `localhost:3300` to auto-authenticate +- **NPM registry host:** `GITEA_NPM_HOST` set by `switch-network.sh` — `localhost` on corp, Azure VM host on home (from `~/.gitea_vm_host`). All repo `.npmrc` files use `${GITEA_NPM_HOST}:3300`. ## How It Works diff --git a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md index 35e0148f..b73b5370 100644 --- a/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md +++ b/docs/devops/GITEA_NPM_REGISTRY_MIGRATION.md @@ -67,7 +67,7 @@ Flow: learning_ai_common_plat/packages/* ↓ build locally ↓ publish to local Gitea npm registry -local Gitea npm registry (localhost:3300) +local Gitea npm registry (${GITEA_NPM_HOST}:3300) ↓ install via semver refs product repos / Docker builds / local Gitea CI ``` @@ -170,8 +170,9 @@ Host-side installs, Docker builds, and local CI are all validated. | 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 | +| **Local dev (Mac)** | `corp` | `localhost:3300` (GITEA_NPM_HOST=localhost) | `host.docker.internal` + `--add-host localhost:host-gateway` | **Yes** — expected | +| **Local dev (Mac)** | `home` | `:3300` (from `~/.gitea_vm_host`) | Direct internet (no proxy) | **No** — direct connection | +| **VM deployment** | N/A | `localhost: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. @@ -323,7 +324,9 @@ Do not use Azure or external registry credentials here. In this phase, all `npm publish` activity must point only to: -`http://localhost:3300/api/packages/bytelyst/npm/` +`http://${GITEA_NPM_HOST}:3300/api/packages/bytelyst/npm/` + +(`GITEA_NPM_HOST` is set by `switch-network.sh` — `localhost` on corp, Azure VM host on home.) No Azure Artifacts. No npmjs.org. diff --git a/docs/devops/SINGLE_VM_DEPLOYMENT.md b/docs/devops/SINGLE_VM_DEPLOYMENT.md index e66be73b..9d7d977b 100644 --- a/docs/devops/SINGLE_VM_DEPLOYMENT.md +++ b/docs/devops/SINGLE_VM_DEPLOYMENT.md @@ -986,13 +986,10 @@ Gitea is a lightweight, self-hosted Git forge (~150 MB RAM) that provides three ### Registry configuration ```bash -# .npmrc (host-side) — points @bytelyst scope to Gitea registry -@bytelyst:registry=http://localhost:3300/api/packages/bytelyst/npm/ -//localhost:3300/api/packages/bytelyst/npm/:_authToken=${GITEA_NPM_TOKEN} - -# .npmrc.docker (Docker-side) — uses compose service name or build arg -@bytelyst:registry=http://${GITEA_NPM_HOST:-localhost}:3300/api/packages/bytelyst/npm/ -//localhost:3300/api/packages/bytelyst/npm/:_authToken=${GITEA_NPM_TOKEN} +# .npmrc (host-side + Docker-side) — GITEA_NPM_HOST set by switch-network.sh +# NETWORK=corp → localhost, NETWORK=home → Azure VM (from ~/.gitea_vm_host) +@bytelyst:registry=http://${GITEA_NPM_HOST}:3300/api/packages/bytelyst/npm/ +//${GITEA_NPM_HOST}:3300/api/packages/bytelyst/npm/:_authToken=${GITEA_NPM_TOKEN} ``` ### Publish workflow