fix(docker): size the Next build worker pool for a 16 GB runner

[diegosouzapw]

Fixes the "Publish to Docker Hub" pipeline, red on 96 of the last 100 runs — every run since 2026-08-22 23:14 UTC. Example: run 32666809903, both linux/amd64 and linux/arm64.

Diagnosis

ERROR: failed to solve: ResourceExhausted: process "/bin/sh -c ... npm run build ..."
did not complete successfully: cannot allocate memory

That is the kernel, not a V8 heap OOM — and the log says exactly where:

#21 256.1 ✓ Compiled successfully in 4.2min
#21 256.1   Collecting page data using 7 workers ...
...
#21 ERROR: ... cannot allocate memory

The compile phase always finishes. The build dies in page-data collection.

Each page-data worker is its own process and inherits NODE_OPTIONS, so --max-old-space-size=6144 is a ceiling per process, not per build. CIRCLE_NODE_TOTAL=8 gives 7 workers, and 7 of them alongside the parent no longer fit the 16 GB / 4 vCPU GitHub-hosted runners (ubuntu-24.04, ubuntu-24.04-arm). It was intermittent before going 100% — success and failure alternated on 08-22 — which is what a threshold crossed by ordinary codebase growth looks like. 7 workers was also oversubscribing a 4 vCPU runner.

Fix

Lower the pool to 3 (2 workers) and make it a build arg, so a large builder can raise it back:

docker build --build-arg OMNIROUTE_BUILD_WORKERS=8 .

The existing #10060 comment already capped this at 8 for the same class of failure on 32-core builders; the value simply is not low enough for a 4 vCPU / 16 GB runner any more.

Validation

tests/unit/docker-build-memory-budget.test.ts — 3 tests, red on the base (3/3), green here (3/3). It reads the two ARG defaults straight out of the Dockerfile and fails if parent heap + workers × per-worker peak outgrows the runner, or if the pool oversubscribes its CPUs. So a future one-line bump to either knob has to re-do the arithmetic instead of silently reddening the publish pipeline again.

The per-worker peak the budget uses (2560 MB) is documented as an inference from this failure — 7 workers did not fit in 16 GB, which puts the peak north of ~1.8 GB — not as a measurement. That is called out in the test's comment.

Other checks:

• Dockerfile sibling tests (dockerfile-dashboard-embed-arg-10273, dockerfile-npm-bundled-cve-patch, dockerfile-better-sqlite3-node-gyp-6700, tls-client-node-docker-binary-7802, dockerfile-base-path-arg, docker-llmlingua-optionals-9166, assemble-standalone-onnxruntime-native-asset, docker-healthcheck-base-path) — 26/26
• check:docs-all (doc-links + fabricated-docs), check:tracked-artifacts — PASS
• prettier --check, eslint — clean

docs/guides/DOCKER_GUIDE.md's build-arg table was stale (still listing the pre-#10060 4096 default); updated, plus the new knob and the symptom to recognize — a build that dies after ✓ Compiled successfully.

CIRCLE_NODE_TOTAL and OMNIROUTE_BUILD_WORKERS are added to the fabricated-docs env allowlist with the reason inline: neither is read via process.env in this repo — one is a Dockerfile ARG, the other is read by Next itself.

⚠️ What this PR cannot prove

The failure only reproduces on a memory-constrained host, so no unit test can reproduce the OOM — the test guards the arithmetic, not the outcome. The real validation is the next publish run after merge. If it still OOMs, the knob to turn is WORKER_PEAK_MB in the test plus a lower OMNIROUTE_BUILD_WORKERS; the diagnosis (page-data workers, not the compile pass) holds either way.

⚠️ base-red inherited: #9985