From 020306c94f488fca8c73bfd0b716dc1be876630f Mon Sep 17 00:00:00 2001 From: Duncan Tourolle Date: Thu, 30 Jul 2026 18:35:10 +0200 Subject: [PATCH] docs: builder images and per-backend release binaries (DP-008) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the build/deploy story that was missing: containerised builder images for cpu / cuda / rocm, and release jobs producing prebuilt binaries so a first install need not compile. States explicitly that this does not reverse DP-005. That requirement rejects Docker as a *runtime* — GPU passthrough is fragile and exists only because of the container. Using it as a *build* environment is the opposite case, and lets one machine produce binaries for backends it cannot itself run. Build in a container, run natively. Two things deliberately cannot ship, and the installer must not imply otherwise: TensorRT engines are GPU-architecture and TRT-version specific, so build_trt_engines.sh still runs on the target; and models are ~725 MB in LFS, orthogonal to the binary. The base image is chosen by the OLDEST glibc to be supported, not by convenience — a binary built in a container runs against the host's glibc, and getting this wrong fails at load with GLIBC_2.xx not found. Accelerator runtimes have the same shape of problem, so each image documents its compatible CUDA/ROCm range and the installer checks it rather than discovering a mismatch at first inference. Co-Authored-By: Claude Opus 5 TRACES: DP-005, DP-007, DP-008 | PR-004 --- docs/SPEC.md | 76 ++++++++++++++++++++++++++++++++++++++++++-- docs/requirements.md | 2 ++ 2 files changed, 75 insertions(+), 3 deletions(-) diff --git a/docs/SPEC.md b/docs/SPEC.md index b54b5d0..49fbaa0 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -777,9 +777,16 @@ prerequisite. ## DP-005 — Installation and provisioning -- Native install, **no Docker** — GPU passthrough is the most fragile part of a - containerised setup and exists only because of the container. Natively the GPU - works with the host drivers and media paths need no re-mounting. +- Native install, **no Docker at runtime** — GPU passthrough is the most fragile + part of a containerised setup and exists only because of the container. + Natively the GPU works with the host drivers and media paths need no + re-mounting. This constrains how the software *runs*, not how it is *built*: + DP-008 uses containers as build environments precisely because that side has + none of these problems. +- The installer may **fetch a prebuilt binary** (DP-008) instead of compiling. + Compiling stays supported, but should not be the only path — it is the slowest + and most fragile step of a first install. TRT engines are still built locally + either way (DP-008). - An installer (`scripts/build_install.py`) consuming one `install.yaml`: platform (nvidia/amd/cpu), embedder model, gallery scan cadence, install prefix; runtime secrets written to a `.env`, editable without recompiling. @@ -838,6 +845,69 @@ and resample to 11025 Hz. It must be added alongside the audio-signature work. **Gap:** entire requirement. The image does not exist, and no CI config is present in this repo. +## DP-008 — Builder images and release binaries + +Produce prebuilt binaries per backend so deployment does not require every user +to compile the project. + +**This does not contradict DP-005.** That requirement rejects Docker as a +*runtime* — GPU passthrough is the most fragile part of a containerised setup and +exists only because of the container. Using Docker as a *build* environment is +the opposite case: hermetic, reproducible, and it lets one machine produce +binaries for backends it cannot itself run. Build in a container; run natively. + +### Image matrix + +The build has two independent axes (`CMakeLists.txt:48-49`), so the useful +combinations are: + +| Image | `SAE_INFERENCE_BACKEND` | `SAE_GEMM_BACKEND` | Target | +|---|---|---|---| +| `sae-builder-cpu` | ORT | CPU | CI (DP-007), and the smoke-test fallback | +| `sae-builder-cuda` | TRT | CUDA | NVIDIA | +| `sae-builder-rocm` | ORT | ROCM | AMD | + +All three carry the DP-007 dependency set (OpenCV 5, HDF5, FFmpeg incl. +swresample, vendored Catch2/nlohmann) and differ only in the accelerator stack. +The CPU image is the CI image — one artifact, two uses. + +Published to the Gitea container registry, pinned by tag, rebuilt when the +dependency set changes rather than per run. + +### What ships, and what cannot + +**Ships:** the `scene_analyze` binary and its companions, per backend. + +**Cannot ship: TensorRT engines.** `.engine` files are specific to the GPU +architecture and TRT version they were built on — `scripts/build_trt_engines.sh` +must still run on the target machine. A prebuilt binary shortens the install; it +does not remove the local engine-build step, and the installer must not imply +otherwise. + +**Cannot ship: models.** ~725 MB in LFS, and orthogonal to the binary. + +### The constraint that decides the base image + +**A binary built in a container runs against the host's glibc.** Build on a +newer base than the oldest supported host and it fails at load with +`GLIBC_2.xx not found` — the classic and entirely avoidable trap when shipping +binaries out of containers. + +So the base is chosen for the *oldest* glibc to be supported, not for +convenience or recency. Accelerator libraries have the same shape of problem: +the binary links against a driver-provided runtime, so each image must document +the CUDA/ROCm version range its output is compatible with, and the installer +must check it rather than discovering a mismatch at first inference. + +### Jobs + +A release job per backend, producing a tagged artifact in the registry. These are +**not** the CI gate — the gate runs the CPU image on every push (DP-007); +release builds run on tag. Their outputs are what DP-005's installer fetches +when the user does not want to compile. + +**Gap:** entire requirement. No images, no release jobs. + ## DP-006 — Gallery maintenance as a background concern - Incremental gallery refresh runs on a timer (`gallery_scan_interval`, default diff --git a/docs/requirements.md b/docs/requirements.md index 98c562d..089f8a7 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -66,6 +66,8 @@ Status: `Done` · `In Progress` · `Planned` · `TBD` · `Withdrawn` | DP-004 | Opportunistic/idle mode: external trigger, hard stop, implicit re-queue | PR-004 | Medium | Planned | | DP-005 | Native installer, no Docker; Fedora + Arch | PR-004 | Medium | Planned | | DP-006 | Background incremental gallery refresh on a timer | PR-003 | Medium | Planned | +| DP-007 | CI builder image, CPU-only, pinned by tag in the Gitea container registry | PR-004 | High | Planned | +| DP-008 | Builder images + release jobs per backend (cpu / cuda / rocm); ship binaries, not engines | PR-004 | Medium | Planned | ## Integration (IR)