85d8cef110
- 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
164 lines
6.8 KiB
Markdown
164 lines
6.8 KiB
Markdown
# Dual-Network Development Setup
|
|
|
|
**Description**: Seamlessly switch between corporate (SSL-intercepting proxy) and home (direct internet) networks using a single environment variable.
|
|
|
|
## How It Works
|
|
|
|
One env var — `NETWORK` — controls all proxy/registry config for npm, pnpm, pip, curl, and Node.js:
|
|
|
|
| `NETWORK` | Effect |
|
|
| ----------------- | ---------------------------------------- |
|
|
| `corp` | Proxy + JFrog npm registry + relaxed SSL |
|
|
| `home` (or unset) | Direct internet, default registries |
|
|
|
|
**Script**: `scripts/switch-network.sh` — sourced from `~/.zshrc`, runs on every new shell.
|
|
|
|
## Setup (one-time)
|
|
|
|
### 1. Add to `~/.zshrc`
|
|
|
|
```bash
|
|
# Dual-network: set to "corp" at work, "home" at home
|
|
export NETWORK=corp
|
|
source "$HOME/code/mygh/learning_ai_common_plat/scripts/switch-network.sh"
|
|
```
|
|
|
|
### 2. Remove old `~/.npmrc`
|
|
|
|
```bash
|
|
rm ~/.npmrc
|
|
```
|
|
|
|
The env vars (`NPM_CONFIG_REGISTRY`, `NPM_CONFIG_PROXY`, etc.) override `.npmrc` — no config file needed.
|
|
|
|
### 3. Open a new terminal
|
|
|
|
You'll see either:
|
|
|
|
- `🏢 NETWORK=corp — proxy active`
|
|
- `🏠 NETWORK=home — direct internet`
|
|
|
|
## Switching Networks
|
|
|
|
Just edit `~/.zshrc` and change the value:
|
|
|
|
```bash
|
|
export NETWORK=home # at home
|
|
export NETWORK=corp # at work
|
|
```
|
|
|
|
Then open a new terminal (or `source ~/.zshrc`).
|
|
|
|
## What Gets Configured
|
|
|
|
### `NETWORK=corp`
|
|
|
|
| Variable | Value |
|
|
| ------------------------------ | --------------------------------- |
|
|
| `http_proxy` / `https_proxy` | Corporate proxy URL |
|
|
| `NPM_CONFIG_REGISTRY` | JFrog Artifactory npm proxy |
|
|
| `NPM_CONFIG_PROXY` | Corporate proxy URL |
|
|
| `NPM_CONFIG_STRICT_SSL` | `false` |
|
|
| `PIP_TRUSTED_HOST` | `pypi.org files.pythonhosted.org` |
|
|
| `NODE_TLS_REJECT_UNAUTHORIZED` | `0` |
|
|
|
|
### `NETWORK=home`
|
|
|
|
All proxy vars are **unset**. npm/pnpm use `registry.npmjs.org`, pip uses `pypi.org` — standard defaults.
|
|
|
|
## Lock File Cleanup (one-time, from home)
|
|
|
|
After switching to home for the first time, regenerate lock files to remove corporate proxy URLs:
|
|
|
|
```bash
|
|
# Common platform (pnpm)
|
|
cd $HOME/code/mygh/learning_ai_common_plat
|
|
rm pnpm-lock.yaml && pnpm install
|
|
|
|
# Dashboards (npm)
|
|
cd $HOME/code/mygh/learning_voice_ai_agent/admin-dashboard-web
|
|
rm package-lock.json && npm install
|
|
cd ../user-dashboard-web && rm package-lock.json && npm install
|
|
cd ../tracker-dashboard-web && rm package-lock.json && npm install
|
|
|
|
# MindLyst
|
|
cd $HOME/code/mygh/learning_multimodal_memory_agents
|
|
rm package-lock.json && npm install
|
|
cd mindlyst-native/web && rm package-lock.json && npm install
|
|
```
|
|
|
|
Commit and push the clean lock files. They'll work on both networks going forward.
|
|
|
|
## Affected Tools
|
|
|
|
| Tool | How proxy is picked up |
|
|
| ------------------------- | ----------------------------------------------------------------------------- |
|
|
| **npm** | `NPM_CONFIG_REGISTRY`, `NPM_CONFIG_PROXY` env vars |
|
|
| **pnpm** | Same `NPM_CONFIG_*` env vars |
|
|
| **pip** | `http_proxy`, `https_proxy`, `PIP_TRUSTED_HOST` |
|
|
| **curl** | `http_proxy`, `https_proxy` |
|
|
| **git** (HTTPS) | `http_proxy`, `https_proxy` |
|
|
| **Node.js** (fetch/axios) | `NODE_TLS_REJECT_UNAUTHORIZED` for SSL |
|
|
| **Docker** | Not affected — Docker Desktop has its own proxy settings |
|
|
| **az CLI** | Reads `http_proxy`/`https_proxy` but may need `REQUESTS_CA_BUNDLE` separately |
|
|
|
|
## Troubleshooting
|
|
|
|
### `npm install` hangs or times out
|
|
|
|
- Verify `NETWORK` is set correctly: `echo $NETWORK`
|
|
- Check proxy is reachable: `curl -I $http_proxy`
|
|
|
|
### SSL errors from pip
|
|
|
|
- Ensure `PIP_TRUSTED_HOST` is set: `echo $PIP_TRUSTED_HOST`
|
|
- Or pass explicitly: `pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org <package>`
|
|
|
|
### Lock file has wrong registry URLs after install
|
|
|
|
- You installed on the wrong network. Switch, delete lock file, reinstall.
|
|
|
|
### Docker builds fail behind proxy
|
|
|
|
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
|
|
|
|
- [Local Development Setup](./local-development.md) — Starting all services
|
|
- [Docker Compose](./docker-compose.md) — Container-based development (home network only)
|
|
- [Production Readiness](./production-readiness.md) — Pre-release validation
|