docs(corp-network): document shell no_proxy overriding .env (the #1 trap)#543
Conversation
…rap)
A real corp-firewall install lost hours to this: the operator correctly added
the Compose service names to no_proxy in .env, but Docker Compose resolves
`${no_proxy:-}` from the SHELL environment first and only falls back to .env
when the shell doesn't define it. Corporate machines export no_proxy globally
(~/.zshrc, /etc/profile, MDM), so that value wins and the .env edit is silently
ignored — engines read as unreachable, worker stays unhealthy, seed skips every
scenario, all despite a correct .env.
- corporate-network-install.md: new §7 (symptom/cause/fix/verify), decision-tree
entry, and callouts from §3 (where we tell people to set no_proxy in .env) and
§4. Authoritative check is `docker compose exec api env | grep no_proxy`, not
the .env file.
- .env.example: ⚠️ note in the proxy section that the shell overrides this file.
- seed_meaningful_demos.py: the corp-proxy hint now adds a 'if you already added
these to .env, a shell-exported no_proxy is overriding it' note with the
`export no_proxy=...` recipe and §7 reference — it fires precisely when the
operator has likely already edited .env.
- Test asserts the hint calls out the shell-override trap + §7.
Verified the precedence empirically (docker compose config: shell no_proxy wins
over .env). Docs-only + hint text; mypy clean, full seed suite green.
Signed-off-by: Claude <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation, warning messages, and test coverage addressing a common issue where host shell environment variables (specifically no_proxy) override settings defined in the .env file, causing Docker Compose to silently ignore them. The feedback suggests correcting a technical inaccuracy regarding uppercase NO_PROXY resolution in the runbook, and wrapping an export command in backticks within the python script's console hint for better formatting and consistency.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
…e export hint Adopt two Gemini review findings on PR #543: - Runbook §7: docker-compose.yml interpolates ${no_proxy} (lowercase) for both no_proxy/NO_PROXY container vars, and .env defines lowercase no_proxy — so only a non-empty LOWERCASE no_proxy in the shell triggers the override; an uppercase-only NO_PROXY still lets .env win. Corrected the 'if either is non-empty' overstatement and annotated the echo checks accordingly. - Seed hint: wrap the `export no_proxy=...` command in backticks (matching the other commands) and drop the trailing em-dash to avoid copy-paste errors. Signed-off-by: Claude <noreply@anthropic.com>
Pre-merge review adjudicationCI: green on Cross-model review: Opus self-review (GPT-5.5 unreachable in the remote sandbox). Gemini Code Assist reviewed; both findings adjudicated below, both threads resolved.
Merging via squash once the coverage gate finishes. Generated by Claude Code |
2 participants
Why
A real corp-firewall install (Fidelity) lost hours to a subtle trap: the operator correctly added the Compose service names to
no_proxyin.env, recreated the containers — and the engines were still unreachable (seed skipped every scenario,docker compose exec api env | grep no_proxyshowed the corporate value without the service names).Root cause: Docker Compose resolves
${no_proxy:-}from the shell environment first, and only falls back to.envwhen the shell doesn't define it. Corporate-managed machines exportno_proxy/http_proxyglobally (~/.zshrc,/etc/profile, MDM), so the shell value wins and the.envedit is silently ignored. Verified empirically (docker compose config: shellno_proxyoverrides.env).This is the #1 "I set it but it didn't take" cause for corp installs, and nothing documented it.
Changes
corporate-network-install.md(the symptom-first FAQ):no_proxyoverrides.env(symptom / cause / fix / verify), establishingdocker compose exec api env | grep no_proxyas the authoritative check (not the.envfile).no_proxyin.env) and §4 (worker-unhealthy fix)..env.example:no_proxyoverrides the file, with the verify command + §7 pointer.scripts/seed_meaningful_demos.py: the corp-proxy hint (from feat(seed): point engine-unreachable at no_proxy fix behind a corp proxy #542) now adds an "if you already added these to.env, a shell-exportedno_proxyis overriding it" note with theexport no_proxy=…recipe and §7 reference — it fires precisely when the operator has likely already edited.env.Verification
mypy
--strictclean (622 files); full seed unit suite green (288 passed);ruffclean. The runbook is not a generated-guide artifact, so no freshness gate applies.🤖 Generated with Claude Code
https://claude.ai/code/session_01MtJPQEjFqk3eipSiq8R6iS
Generated by Claude Code