probably-rendering-one-more-pixel-tonight/docs/wiki-image-retention.md

Wiki image retention on ces-control

Wiki CI builds one runtime image and one integration-test image per revision. Web and worker share the runtime image. Tags can share an image ID; displayed image sizes include shared layers and must not be added to estimate reclaimed space.

Policy

• Retain the current release and the two preceding distinct successful releases. scripts/deploy.sh records success in /opt/prompt/successful-releases only after all existing deployment checks pass. The ledger is replaced atomically.
• The first three successful deployments bootstrap this ledger. Until then, retain all runtime images, since old release directories alone do not prove successful deployment. No historical success is guessed from directory dates.
• Keep the test images corresponding to retained runtime releases: Studio verification and publishing scripts use them as operational tools. Remove other successful job test images unless a container still references them or their image ID has another protected tag.
• Retain other runtime/test/build images for at least 72 hours for debugging. Expired runtime images outside the three retained releases become eligible.
• Remove expired project/build-labelled exited containers only with no mounts. Remove expired project-labelled untagged image intermediates where Docker allows.
• Always preserve images referenced by any running, created or stopped container. This can deliberately keep more than three runtime versions.
• Preserve foreign tags/digests, unlabelled intermediates and legacy prompt:* images. Legacy images require a separate reviewed migration list.
• Never use global prune, force image/container removal, or volume deletion. Database, object storage, backups and release directories are outside this tool.

Preview and apply

Run from the reviewed checkout on the confirmed ces-control host:

sudo python3 scripts/wiki-image-lifecycle.py preview
sudo python3 scripts/wiki-image-lifecycle.py apply

The default command is preview. Both print keep/delete reasons, image IDs and tags. Preview reads Docker metadata and may create empty lock files, but never changes Docker state. Both commands refuse to proceed if the current release metadata or success ledger is invalid. They also refuse while another cooperating build or deployment holds the locks.

The workflow invokes ci --sha <full-sha> once on main. A single exclusive /opt/prompt/.image-lifecycle.lock spans builds, integration, deployment and cleanup. Cleanup also takes the existing .deploy.lock, protecting manual deploy.sh invocations. Use this CI entrypoint for manual builds too; raw Docker commands and old workflow revisions do not participate in this lock. Allow old wiki jobs to finish before first enabling apply. Other projects are out of scope.

Cleanup runs after both success and failure. Errors are reported without changing the original build/deployment status or rolling back healthy services. Referenced images and Docker refusal are reported and retained. Failed CI does not record a successful release and does not immediately remove that job's test image.

After the user merges to main, policy checks run Python tests and shell syntax checks on ces-control without building or touching Docker. The full application build/integration/deployment also runs only on main updates, subject to its path filters. PR events and manual dispatch do not trigger either workflow. No local builds are needed.