chore(docker): wire http_proxy / https_proxy / no_proxy ARGs through builds

[SoundMindsAI]

Summary

This PR bundles two related Dockerfile-flexibility changes:

1. Wire http_proxy / https_proxy / no_proxy ARGs through builds (commit 03cb1e3c)

• Add three new build args to both Dockerfile and ui/Dockerfile so corp installs behind an HTTP proxy can route apt / PyPI / npm fetches at build time and outbound HTTP (OpenAI, GitHub, registered ES/OpenSearch/Solr) at runtime through that proxy.
• Both case variants (http_proxy + HTTP_PROXY, etc.) are ENV'd in every stage because Linux tooling is split: apt + curl prefer lowercase; uv + pip + requests accept either; npm + pnpm prefer uppercase.
• Compose forwards all three through every service's build.args block (migrate / api / worker / ui).
• Defaults stay empty — unchanged behavior when the vars are unset.

The no_proxy gotcha — Compose service names

Without postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate in no_proxy, the worker's HTTP call to http://elasticsearch:9200 (and similar in-network calls) gets routed through the corporate proxy, which has no path to those Compose-internal hostnames. The recommended .env.example default bakes them in alongside:

• 169.254.169.254 — EC2 / cloud metadata service
• 10.0.0.0/8 — internal VPC traffic
• localhost, 127.0.0.1 — local

2. Rename UV_REGISTRY → GHCR_REGISTRY (commit 9a9f1a0c)

UV_REGISTRY (added in PR #517) read like an ARG for uv-managed dependencies (PyPI mirror?) when it actually controls only the registry prefix for the ghcr.io/astral-sh/uv tooling image. Renamed to GHCR_REGISTRY — describes what upstream it overrides (the GHCR namespace), matches BASE_REGISTRY's naming style, and stays accurate if any future GHCR-hosted image is added.

The breaking-change surface is intentionally tiny: PR #517 merged hours ago and no operator has had time to bake UV_REGISTRY into their .env yet. The state.md entry for PR #517 intentionally retains the original UV_REGISTRY wording (accurate for what shipped at that merge); the upcoming state finalization will note the rename.

Three usage patterns

# Default — no proxy, no registry override, unchanged behavior
make up

# One-shot inline
BASE_REGISTRY=fcr.fmr.com/ \
GHCR_REGISTRY=fcr.fmr.com/ \
http_proxy=http://http.proxy.fmr.com:8000 \
https_proxy=http://http.proxy.fmr.com:8000 \
no_proxy=fmr.com,.fmrcloud.com,localhost,127.0.0.1,10.0.0.0/8,169.254.169.254,postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate \
make up

# Persistent — uncomment + edit the relevant blocks in .env, then `make up`

What's documented

• The existing ## Corporate registry proxy support § in docs/01_architecture/deployment.md gains a new ### Corporate HTTP proxy (apt / PyPI / npm + runtime egress) subsection covering the three env vars, the no_proxy Compose-service-names gotcha, and a pointer to the deeper Artifactory-mirror case (not currently supported by the Dockerfiles).
• deployment.md's GHCR_REGISTRY row description is generalized away from "the uv COPY-from stage" to "every GHCR-hosted image … currently used by the uv-source alias stage; any future GHCR image lands under the same prefix."
• .env.example documents all three proxy vars with a copy-pasteable default no_proxy.
• docs/03_runbooks/local-dev.md troubleshooting bullet updated to use the new GHCR_REGISTRY name.

Test plan

• docker buildx build --check -f Dockerfile . — clean.
• docker buildx build --check -f ui/Dockerfile ui — clean.
• docker compose config — default-empty case: all 12 proxy build-arg slots (4 services × 3 vars) resolve to ""; BASE_REGISTRY + GHCR_REGISTRY resolve to "" + ghcr.io/.
• docker compose --env-file <override> config — override case: all slots propagate the override value.
• pytest backend/tests/unit/test_dockerfile_runtime_stage.py — 3/3 pass.
• CI docker job — buildx of API image with default ARGs.
• CI docker-ui job — buildx of UI image with default ARGs.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces corporate HTTP proxy support for both build-time and runtime egress across the backend and frontend services, updating the Dockerfiles, Docker Compose configuration, and deployment documentation. The feedback highlights that baking proxy settings into the Docker images via ENV is an anti-pattern; instead, these should be dynamically passed at runtime via the environment section in docker-compose.yml. Additionally, it is recommended to include host.docker.internal in the default no_proxy lists to ensure local LLM development works seamlessly behind a proxy.

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.

[gemini-code-assist]

Baking build-time proxy configuration into the Docker image via ENV is a known anti-pattern. Docker automatically treats proxy variables (http_proxy, https_proxy, no_proxy, etc.) as special build-time arguments that are available during RUN instructions but are purposely not persisted in the final image to keep it environment-agnostic.

By explicitly defining ENV http_proxy=${http_proxy}, you are overriding this behavior and hardcoding the builder's proxy settings into the image. Furthermore, because these variables are not defined in the environment section of docker-compose.yml, any runtime container started from a pre-built image will not have these proxy settings at runtime.

Recommendation:

1. Remove the ENV block from the Dockerfile.
2. Pass these variables dynamically at runtime by adding them to the environment section of each service in docker-compose.yml:

    environment:
      - http_proxy
      - https_proxy
      - no_proxy
      - HTTP_PROXY
      - HTTPS_PROXY
      - NO_PROXY

[gemini-code-assist]

Baking build-time proxy configuration into the UI image via ENV is an anti-pattern. Please remove this ENV block and rely on runtime environment variables passed via docker-compose.yml instead.

[gemini-code-assist]

The runner stage does not run any build-time commands (like npm install or apt-get) that require a proxy. Declaring these ARGs and ENVs in the runner stage is purely for runtime proxying, which should be handled dynamically via docker-compose.yml's environment section rather than being baked into the image.

[gemini-code-assist]

Passing these as build.args is correct for build-time proxying (e.g., apt-get and uv sync). However, to support runtime proxying (especially when using pre-built images or when running without rebuilding), these variables must also be declared in the environment section of the services.

Add them to the environment section of migrate, api, worker, and ui services:

    environment:
      - http_proxy
      - https_proxy
      - no_proxy
      - HTTP_PROXY
      - HTTPS_PROXY
      - NO_PROXY

[gemini-code-assist]

When developers run local LLMs (such as Ollama, LM Studio, or vLLM) behind a corporate proxy, they configure OPENAI_BASE_URL to point to http://host.docker.internal. Without adding host.docker.internal to the no_proxy list, requests to the local LLM will be incorrectly routed to the corporate proxy and fail.

Include host.docker.internal in the default no_proxy list to ensure local LLM development works seamlessly out of the box.

# no_proxy=your-corp.com,.your-corp-cloud.com,localhost,127.0.0.1,10.0.0.0/8,169.254.169.254,host.docker.internal,postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate

[gemini-code-assist]

Add host.docker.internal to the documented no_proxy example in the Dockerfile comments to keep it in sync with .env.example and support local LLM development behind a proxy.

#   no_proxy=your-corp.com,.your-corp-cloud.com,localhost,127.0.0.1,
#            10.0.0.0/8,169.254.169.254,host.docker.internal,
#            postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate

[gemini-code-assist]

Update the documentation example to include host.docker.internal in the no_proxy list to ensure consistency with .env.example.

Suggested change

	no_proxy=your-corp.com,.your-corp-cloud.com,localhost,127.0.0.1,10.0.0.0/8,169.254.169.254,postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate
	no_proxy=your-corp.com,.your-corp-cloud.com,localhost,127.0.0.1,10.0.0.0/8,169.254.169.254,host.docker.internal,postgres,redis,elasticsearch,opensearch,solr,api,worker,migrate

[SoundMindsAI]

Adjudication of Gemini Code Assist review

Per CLAUDE.md ("Before considering a PR ready to merge"). 7 findings — all accepted, all addressed in 77f81542.

#	File:Line	Severity	Verdict	Resolution
1	Dockerfile:107	HIGH	Accept	Removed Dockerfile ARG + ENV blocks; rely on BuildKit predefined ARGs
2	ui/Dockerfile:67	HIGH	Accept	Same — removed deps-stage ARG + ENV
3	ui/Dockerfile:97	HIGH	Accept	Removed runner-stage ARG + ENV
4	docker-compose.yml:75	HIGH	Accept	Added environment: proxy block to all 4 services
5	.env.example:152	MED	Accept	Added host.docker.internal to default no_proxy
6	Dockerfile:55	MED	Accept	Added host.docker.internal to comment example
7	deployment.md:238	MED	Accept	Added host.docker.internal to docs example + gotcha paragraph

The crucial technical correction (Findings 1-4)

Docker treats http_proxy / https_proxy / no_proxy (+ uppercase + FTP/ALL variants) as predefined ARGs: BuildKit forwards them from --build-arg into every RUN step's environment automatically — no ARG declaration needed in the Dockerfile — and intentionally excludes them from docker history so the proxy URL never gets baked into the image.

My initial design used explicit ARG http_proxy= + ENV http_proxy=${http_proxy} blocks in both Dockerfiles, which were both redundant (BuildKit handles it without them) AND counterproductive (the ENV baked the URL into the runtime image, making it environment-coupled and persistent in docker inspect).

The corrected architecture:

• Build-time: Compose build.args: (already wired) → BuildKit predefined-ARG forwarding → RUN steps see the value. No ARG/ENV in Dockerfile.
• Runtime: Compose environment: block on each service → container env at startup. Image stays portable; runtime settings live in compose where they belong.

Both paths read the same ${http_proxy:-} from .env, so a single http_proxy=… line in .env covers both build-time and runtime.

Findings 5-7 — host.docker.internal

Sharp catch on local-LLM dev. An operator using Ollama / LM Studio / vLLM via OPENAI_BASE_URL=http://host.docker.internal:11434 behind a corp proxy would have their local-machine LLM calls intercepted by the proxy without this exemption. Added to:

• .env.example default no_proxy line + the gotcha block (with "Common gotchas" subsection listing cloud-metadata, VPC, and host.docker.internal cases)
• Dockerfile explanatory comment
• deployment.md override example + the gotcha paragraph
• Plus a new "Architecture: build-time vs runtime" paragraph in deployment.md linking to Docker's predefined-ARGs reference

Validated

• docker buildx build --check clean on both Dockerfiles
• docker compose config resolves proxy vars in all 4 services' build.args (build-time) AND environment: (runtime) — both default-empty and override paths
• backend/tests/unit/test_dockerfile_runtime_stage.py — 3/3 pass

PR is ready for merge once CI on 77f81542 goes green.

[SoundMindsAI]

Adjudication of 2 follow-up Gemini findings on 77f81542

Both pinned to 77f81542 — same SHA as branch HEAD — but pointing at fixes that are already present elsewhere in the same commit. Both rejected as stale (bot false positives).

#	File:Line	Severity	Verdict	Counter-evidence
A	docker-compose.yml:79 ("add environment: proxy block")	HIGH	Reject — stale	All 4 services already have http_proxy/https_proxy/no_proxy + uppercase in their environment: blocks. See docker-compose.yml:144-149 (api), :93-98 (migrate), :226-231 (worker), :271-276 (ui). grep -c "http_proxy: \${http_proxy:-}" docker-compose.yml = 8 (4 × build.args + 4 × environment), confirming both layers are wired.
B	Dockerfile:60 ("add host.docker.internal to comment")	MED	Reject — stale	host.docker.internal already present in the cited comment at Dockerfile:59 (in the no_proxy=… example), plus lines 64, 67, 68 as part of the gotcha explanation. grep -n "host.docker.internal" Dockerfile returns 4 matches.

Both look like the bot re-scanned the build.args block in isolation and flagged based on it alone, without cross-checking the environment: block 60 lines further down (Finding A) and without scanning the full no_proxy=… comment line (Finding B). Pattern matches the project's known "Gemini re-flags resolved findings on the new SHA" failure mode.

No file changes; merging.