Fix Docker image bloat: exclude local venvs from build context, move transformers.js to devDependencies.

docs/Decisions.md

@@ -755,3 +755,84 @@ for no benefit, and the UI is where `context.offline`/retry actions live).
 surfacing richer structured errors (e.g. a `GPUDeviceLostInfo` object
 instead of a stringified message), prefer inspecting that directly over
 adding more substring patterns.
+
+## D-031 — Docker image hardening: exclude local venvs, move Transformers.js out of the runtime image
+**Status:** Accepted (2026-07-29)
+WorkBreakdown's M6 "production build + `bun start` deployment check" item —
+a `docker build .` from this checkout, not a fresh clone, exposed two real
+bugs the documented image sizes (WorkBreakdown M5 notes: "244 MB" /
+"405 MB") had already gone stale against.
+**Bug 1 — local Python venvs leak into every image.** `server-py/venv` and
+`server-py/.venv` (created locally to test the sidecar against a real
+faster-whisper install) are invisible to `git status` — `python -m venv`
+drops its own nested `.gitignore` (`*`) inside the venv directory — but
+Docker does not read `.gitignore`, and `.dockerignore` had no matching
+pattern. `COPY server-py ./server-py` therefore copied both venvs (858 MB
+combined) into the image; measured effect on the Bun-only image: 999 MB
+instead of the intended size, with a completely unused,
+machine-specific Python interpreter baked in at `/app/server-py/venv` and
+`/app/server-py/.venv`. **Fix:** `.dockerignore` gained `**/venv/` and
+`**/.venv/`. Verified: rebuilding after the fix, `find /app/server-py`
+inside the image no longer lists either directory.
+**Bug 2 — `@huggingface/transformers` (and its `onnxruntime-node` +
+`onnxruntime-web` dependencies, 341 MB combined) had no reason to be in the
+*production runtime* image.** Grepped: the only file in `src/` that imports
+`@huggingface/transformers` as a value (not a type) is
+`src/worker/inference.worker.ts`, and that file is bundled once, at build
+time, into the static `dist/inference.worker.js` the production server
+just serves as a file (confirmed: `src/index.ts`'s `Bun.build`-based
+on-the-fly bundling path — needed because Bun doesn't follow `new
+Worker(...)` graphs, per M1's Architecture notes — only runs in
+**development** mode; production never calls it). No server-side module
+(`src/server/*`, `src/index.ts`, `src/lib/models.ts`'s only import from the
+package is `import type`, erased at transpile time) touches the package at
+runtime. Yet it was a `dependencies` entry, so the Dockerfile's runtime
+stage (`bun install --frozen-lockfile --production`) installed it and its
+full dependency tree anyway — dead weight on every deploy. **Fix:**
+`@huggingface/transformers` moved to `devDependencies` in `package.json`.
+The **build** stage's `bun install --frozen-lockfile` (no `--production`)
+still installs devDependencies, so `scripts/build.ts`'s `Bun.build` call
+(which needs the package on disk to bundle the worker) is unaffected; the
+patch in `patches/@huggingface%2Ftransformers@4.2.0.patch` still applies
+there the same way. Verified: production `node_modules` in the built image
+dropped from 409 MB to 7.9 MB (react/react-dom/passport only); the running
+container still served `/inference.worker.js` correctly (534,714 bytes,
+byte-identical to the pre-change build) and `/api/transcribe/status`
+correctly reported the expected `faster-whisper`/`python3` unavailability
+message — nothing at runtime needed the package.
+**Net effect, measured against a real `docker build .`/`--target
+with-server-engine` in this checkout:**
+| Image | Before both fixes | After |
+| --- | --- | --- |
+| Bun-only (`runtime`) | 2.18 GB (venv leak) | ~421 MB |
+| with-server-engine | not separately measured (inherits the leak) | ~7.1 GB — see below |
+**A third, non-bug finding while re-measuring:** the with-server-engine
+image is legitimately several GB, not the "405 MB" previously written down
+— its last `RUN` layer pre-downloads both server-selectable models
+(`large-v3-turbo`, `medium.en`, matching the `EngineToggle`'s hardcoded
+allow-list in `App.tsx`) into `/opt/faster-whisper/models` at *build* time,
+which alone measured 3.15 GB; the venv/faster-whisper/ctranslate2 install
+layer is a separate 451 MB. This is intentional (comment already in the
+Dockerfile: baking the weights into the image, outside `/app/data`, means
+no first-request cold-download and no dependence on the data volume for
+those two models) — not something to shrink — but the number that made it
+into WorkBreakdown's M5 notes and README's env-var table was never updated
+to match, and the README's Persistence section wrongly implied these
+weights live in the `/app/data` volume (`FASTER_WHISPER_DOWNLOAD_ROOT`'s
+actual default in that image is `/opt/faster-whisper/models`, not
+`/app/data/faster-whisper-models`). **Fix:** README's env-var table,
+Persistence section, and a new "Image sizes" subsection now state the
+verified numbers and the reason for each; WorkBreakdown's M5 notes updated
+to match.
+**Consequence:** none of this is CI-visible — GitLab CI (`.gitlab-ci.yml`)
+builds from a clean checkout that never has `server-py/venv` on disk, so
+Bug 1 only bit a local `docker build .` run from a working directory that
+had one (as this checkout did); the `.dockerignore` fix is still correct
+defense-in-depth regardless. Bug 2 was real everywhere, CI included — every
+pushed Bun-only image has been ~340 MB heavier than necessary since
+`@huggingface/transformers` became a production dependency.
+**Revisit:** if the with-server-engine catalog ever grows beyond the two
+baked-in models, either accept runtime downloads for the extra ones (point
+`FASTER_WHISPER_DOWNLOAD_ROOT` at `/app/data` for those, per the README's
+override note) or extend the Dockerfile's pre-download `RUN` line —
+re-measure and re-document the image size either way.