From 93decd29a2ca1bb67cf71b2e2192abe115782eb6 Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Wed, 4 Nov 2026 22:04:22 -0600 Subject: [PATCH] docs: require a published digest for the current admission verifier --- docs/deploying.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/deploying.md b/docs/deploying.md index d41c422..1d403d4 100644 --- a/docs/deploying.md +++ b/docs/deploying.md @@ -37,7 +37,7 @@ private HeavyPad Tailscale endpoint. |---|---|---| | 1. land the change | commit + push to main | `ci.yml` runs fmt + debug/releasesafe tests; admission below is the deploy gate | | 2. admission | push triggers the `stream-admission` deployment, or trigger it by hand with `sha` + `build_image=true` | bare metal on heavypad; serialised by concurrency_limit=1 | -| 3. publish (optional) | `./scripts/admit publish [sha]` | pins the registry digest into the receipt. Skippable: the registry has been over quota, and deployment verifies by image id instead | +| 3. publish | `./scripts/admit publish [sha]` | pins the registry digest into the receipt; the current verifier rejects unpublished receipts | | 4. cut over | flip `STREAM_IMAGE` in `/opt/stream-experiment/.env`, `docker compose up -d stream` | seconds to swap | | 5. restart recovery | (automatic) | ~4–5 min to serving + dialing upstream; see below | @@ -47,10 +47,11 @@ Notes on the stages: one full-suite run to one image digest; `scripts/admit verify ` refuses anything without a fully-passing receipt. Never point `.env` at an image that `admit verify` rejects. -- **The registry is not on the critical path.** `22bf62c` shipped while atcr - was over quota by verifying the receipt's recorded `local_id` against the - image id on the box. `docker save | docker load` preserves image ids, so a - gate that built on heavypad can still be deployed by transferring it. +- **Publication is required by the current verifier.** `admit verify` checks + `registry_digest`, not `local_id`; an unpublished receipt is rejected. If + HeavyPad lacks registry credentials, transfer a checksummed image archive to + an authenticated workstation, verify its image ID against the receipt, and + run `admit publish` there. A tar transfer alone does not admit an artifact. - **Uncommitted trees are refused** (`require_clean_tree`) — the image tag is the commit, by construction. - **Partial runs cannot deploy.** `only`/`skip` record every unrun suite as @@ -131,11 +132,11 @@ For local iteration on oracle failures, `STREAM_UPSTREAM_REPO=~/github.com/bluesky-social/jetstream uv run python tests/differential_oracle.py` gives ~90s cycles against the gate's ~25min. -**Shipping the image.** Preferred: registry push (needs a live -`docker-credential-atcr login` session on the pushing machine). Fallback, -used whenever registry auth is stale — checksummed tar relay, never an -unverified pipe (a dropped `docker save` stream loads "successfully" with -missing layers via content-store dedupe): +**Shipping the image.** Publish through a client with a live +`docker-credential-atcr` session. A checksummed tar relay can move the image +to that client or to production, but does not replace publication and digest +verification. Never use an unverified pipe: a dropped `docker save` stream +can load "successfully" with missing layers via content-store dedupe: ssh stoat@heavypad '... docker save > image.tar && sha256sum image.tar' scp heavypad:image.tar . && verify sha && scp to box && verify sha && docker load -- knotmirror 0.0.1