feat(containers): build, gate and publish GHCR images (ENG-RELEASE-CONTAINERS)

[localai-bot]

Implements ENG-RELEASE-CONTAINERS — spike spec plus W1-W5 and W7. Closes #170 (image lanes), closes #312 (the bug the gate found).

The cpu lane is built and gated end to end on a real image. Nothing is published: the GHCR package does not exist, and no lane has matching-hardware runtime evidence — that is W6 and it stays open.

What is here

One docker/Dockerfile, three lane targets. Every builder stage calls the same scripts/build-*-release.sh the release workflow calls, so the ten-SM gencode list, the CPU tier gates and the staged layout are written down exactly once. Those scripts already end in validate-release-archive.py, so an image build inherits the extracted-archive audit rather than reimplementing it.

Runtime is ubuntu:24.04 pinned by digest for every lane; the cuda lane copies only the CUDA runtime libraries it links, and the driver stays on the host. ffmpeg ships in all three lanes — a deliberate, argued divergence from the archive contract's no-vendor rule, because an archive is extracted onto a host with a PATH to inherit and a container has none.

Three new gates, each with a red-first mutation suite:

Gate	Enforces	Suite
check-container-matrix.py	matrix ↔ Dockerfile agree on lanes, tags, digest-pinned bases, driver boundary	31/31
check-container-workflow.py	no registry write in the PR-facing job, OIDC only in attest, publish tag-gated, validation before push	22/22
validate-container-image.py	config, layout, and — given a model — a real boot	run on a real image

Measured

x86_64, Docker 29.1.2, booted on opt-125m-bf16-st:

• 783 MB cpu image; config + layout + boot all green
• /health 200, /version 200, the image's own declared healthcheck passing inside the container, clean SIGTERM

The gate found a real bug on its first run (#312)

This is why the smoke boots the server instead of running --help.

vllm-server installed no SIGTERM handler. As container PID 1 the kernel does not apply default signal dispositions, so the signal was ignored outright: docker stop waited its full 30 s grace, then SIGKILL — exit 137. Every rolling update, compose down and systemd restart was hard-killing the server and dropping in-flight work. It was invisible outside a container because a non-PID-1 process dies on the default disposition anyway.

Fixed with a self-pipe handler routing SIGTERM/SIGINT into the same server.stop() the existing VT_BENCH_PROFILE_CONTROL FIFO shutdown already used, installed at all three listen() sites.

RED: exit 137 after 30 s → GREEN: exit 0 in 0.25 s.

Also fixed, and silent until now

.dockerignore's **/build*/ matched files as well as directories — Docker does not honour a trailing slash as directories-only the way .gitignore does — so scripts/build-*-release.sh were excluded from the build context and the image build failed with not found after appearing to copy the whole tree. The builders also needed file and binutils, without which the inherited archive validator failed after a full compile. -j 2 was hardcoded in both release scripts and is now a JOBS parameter.

Not established, and not claimed

• Nothing is pushed to GHCR; the package does not exist.
• cuda and vulkan are gated statically but have never been built here.
• Both arm64 legs are unbuilt, so SBSA-vs-Tegra (Thor sm_110, Orin sm_87) is untouched.
• Hosted CI has no model, so it runs config and layout only and reports the absence of runtime evidence rather than implying it.

Records

Row → ACTIVE with anchors and a claim. docs/STATUS.md lands 1 byte under its ratchet, which is lowered in this change with the reason attached. FEATURES gains container and graceful-shutdown rows; BENCHMARKS gains the image size and the shutdown number; USAGE documents pulling, running and validating an image.

scripts/agent-preflight.sh and scripts/agent-ready.py are green on the merged tree, and the image was rebuilt and re-gated after merging main, since main touched server_main.cpp.

🤖 Generated with Claude Code

[localai-bot]

The two red sanitizer lanes are pre-existing on main, not from this PR

Verified by isolation rather than assumed. Built and ran the failing test under TSan on pristine origin/main d06a3792, with none of this branch applied:

WARNING: ThreadSanitizer: data race
    #8 PromRegistry::SeriesFor(...)  src/vllm/v1/metrics/prometheus.cpp:134
    #9 PromRegistry::SetGauge(...)   src/vllm/v1/metrics/prometheus.cpp:165

It reproduces there. Filed as #330 with the root cause: SeriesFor returns a Series& into a std::vector<Series> and then push_backs into that same vector, so every previously returned reference dangles — and PromRegistry carries no mutex or atomic at all while /metrics is now served concurrently.

Supporting evidence that it is not this branch:

• This PR's spec-only commit c3db7804 — no C++ whatsoever — passed both sanitizer lanes. The failures appear only after catch-up merges that pulled in 9c55e3df (/metrics is dead on the production server: AsyncLLM never folds IterationStats into the logger #277).
• The entire C++ diff here is server_main.cpp (+86, the SIGTERM handler). The ASan lane fails six tests, three of them loaders (test_load_direct_upload, test_laguna_nvfp4_loader, test_llama_embedding_fold) that a signal handler cannot reach.

Per the protocol a bug found while doing something else gets its own issue rather than a silent fix, and the metrics row owns that code — so #330 is filed and not repaired here.

The container-specific checks are green

containers.yml ran end to end on this PR: plan ✅, verify (cpu, linux/amd64) ✅, verify (vulkan, linux/amd64) ✅ — the vulkan lane's first build anywhere — with publish/manifest/attest/promote correctly skipped on a non-tag.