From 85d8cef1107df6235ffae7a6ccf324c354ef94aa Mon Sep 17 00:00:00 2001
From: saravanakumardb1 <saravanakumardb1@users.noreply.github.com>
Date: Fri, 10 Apr 2026 16:00:12 -0700
Subject: [PATCH] docs: expand Docker build corporate proxy workarounds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AGENTS.md § 9: add 'Docker builds behind corporate proxy' subsection
  with Alpine/corepack/strict-ssl/NODE_TLS rules
- dual-network-setup.md: replace one-liner Docker section with full
  workaround table, recommended Dockerfile pattern, and key rules
---
 AGENTS.md                           | 11 +++++++++
 AI.dev/SKILLS/dual-network-setup.md | 36 ++++++++++++++++++++++++++++-
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 7efb34c2..2891cbcf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -486,6 +486,16 @@ keytool -importcert -noprompt -trustcacerts -alias att-cso-proxy \
   -keystore ~/.gradle/ssl/gradle-cacerts.jks -storepass changeit
 ```
 
+### Docker builds behind corporate proxy
+
+The TLS-intercepting proxy causes failures inside Docker containers even when Docker Desktop proxy is configured. See `AI.dev/SKILLS/dual-network-setup.md` § Docker Builds for the full reference. Summary:
+
+- **Never use Alpine** — `apk` cannot bypass TLS interception; use `node:22-slim` (Debian)
+- **Never use `corepack`** in Dockerfiles — use `npm install -g pnpm@10` or plain `npm`
+- **Always add** `npm config set strict-ssl false` before any `npm install`
+- **Always add** `ENV NODE_TLS_REJECT_UNAUTHORIZED=0` in build stages with native modules (e.g. `better-sqlite3`)
+- Build-stage only — production images don't need these workarounds
+
 ### MUST follow (network-related)
 
 - Always use `NETWORK` env var — never hardcode proxy URLs in app code
@@ -493,6 +503,7 @@ keytool -importcert -noprompt -trustcacerts -alias att-cso-proxy \
 - If a Gradle build fails with SSL errors, verify `echo $GRADLE_OPTS` shows the truststore path
 - If adding a new tool that fetches from the internet, add its proxy config to `switch-network.sh`
 - `~/.gradle/gradle.properties` is a local-only file — never commit it to any repo
+- Docker builds: follow the `node:22-slim` + `strict-ssl false` + `NODE_TLS_REJECT_UNAUTHORIZED=0` pattern (see above)
 
 ### Kotlin Platform SDK (`packages/kotlin-platform-sdk/`)
 
diff --git a/AI.dev/SKILLS/dual-network-setup.md b/AI.dev/SKILLS/dual-network-setup.md
index 3ad4b8c4..26fc1451 100644
--- a/AI.dev/SKILLS/dual-network-setup.md
+++ b/AI.dev/SKILLS/dual-network-setup.md
@@ -120,7 +120,41 @@ Commit and push the clean lock files. They'll work on both networks going forwar
 
 ### Docker builds fail behind proxy
 
-- Docker doesn't use shell env vars. Configure proxy in Docker Desktop → Settings → Resources → Proxies.
+Docker doesn't inherit shell proxy env vars. Even with Docker Desktop proxy settings configured, the corporate TLS-intercepting proxy causes additional failures inside containers:
+
+| Problem                                                                    | Workaround                                                              |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `npm install` fails with cert errors                                       | `RUN npm config set strict-ssl false` early in Dockerfile               |
+| `node-gyp` can't fetch Node headers (native modules like `better-sqlite3`) | `ENV NODE_TLS_REJECT_UNAUTHORIZED=0` in build stage                     |
+| Alpine `apk add` can't verify repo certs                                   | Use `node:22-slim` (Debian) instead of `node:22-alpine`                 |
+| `corepack prepare pnpm` fails fetching registry                            | Use `npm install -g pnpm@10` instead of corepack, or use `npm` directly |
+
+**Recommended Dockerfile pattern (corporate network):**
+
+```dockerfile
+FROM node:22-slim AS builder
+ENV NODE_TLS_REJECT_UNAUTHORIZED=0
+RUN npm config set strict-ssl false && \
+    apt-get update && apt-get install -y --no-install-recommends python3 make g++ && \
+    rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+# ... npm install + build ...
+
+FROM node:22-slim
+WORKDIR /app
+COPY --from=builder /app/node_modules/ node_modules/
+# ... copy dist, no build tools in prod image ...
+```
+
+**Key rules:**
+
+- **Never use Alpine** — `apk` cannot bypass TLS interception
+- **Never use `corepack`** — it fetches from registry.npmjs.org without respecting `strict-ssl`
+- **Always set `NODE_TLS_REJECT_UNAUTHORIZED=0`** in build stages that compile native modules
+- **Always set `npm config set strict-ssl false`** before any `npm install`
+- These workarounds are **build-stage only** — production images don't need them
+
+**Repos already using this pattern:** `learning_ai_common_plat` (platform-service, extraction-service), `learning_ai_talk2obsidian`, `learning_ai_local_llms`.
 
 ## Related Skills