Docker Image Management

[bradjin8]

Title

Issue 4: Docker Image Management – Load, Create, Save, and Cleanup

Summary

Implement the Docker Image Management layer for the local CI system: load pre-built images from .tar files, create new images when the registry has no matching image, save newly built images for reuse, enforce the image naming convention, and manage disk space by cleaning up old/unused images. This is the integration point between the Image Registry (Issue 3) and the Job Executor (Issue 5).

Goal

• Load images from .tar files so jobs can run without pulling from a remote registry.
• Create new images on-demand when no image matches (using base image from registry + build steps).
• Save newly created images as .tar and register them for future runs.
• Enforce a consistent naming convention and storage layout.
• Manage disk by removing old or rarely used images within configurable limits.

Context

• Depends on: Issue 3 (Image Registry and Matching Algorithm) — we get best_image_path or best_base_image_path and needs_build from the execution plan.
• Feeds into: Issue 5 (Job Executor with act) — job execution calls this layer to prepare the image (load or build), then runs act with the prepared image.
• Design reference: docs/Design Guide.md — Image Management System, Image Storage, Appendix E (New Image Creation Process), E.4 (Image Naming Convention).

Deliverables

• Load images from .tar

  • Given a path from the registry (e.g. images/<project>/<name>.tar), run docker load -i <path>.
  • Verify image is present (e.g. docker images) and return the image reference (name:tag) for act (-P <runner>=<image>).
  • Handle missing file / corrupt archive with a clear error (no silent fallback to pull).

• Create new images when no match found

  • When execution plan says needs_build = true with best_base_image_path:
    • Load the base image from its .tar.
    • Build new image (Dockerfile or equivalent) to satisfy missing essentials (e.g. compiler) and required packages.
    • Tag according to naming convention; save to .tar; update registry (or call registry API from Issue 3).
  • Image creation is synchronous — the job waits until the image is ready; we never skip a job due to “image not found”.

• Save newly built images for reuse

  • After creating an image: docker save -o <path> <image>:<tag>.
  • Use the standard path layout: images/<project>/<name>.tar (see Design Guide).
  • Persist metadata (e.g. add entry to image-registry.yml or equivalent) so the matching algorithm can select this image on future runs.

• Image naming convention enforcement

  • Naming pattern: <project>-<os>-<variant>.tar (e.g. capy-ubuntu-25.04-gcc15.tar, capy-ubuntu-25.04-clang20-asan.tar).
  • Reject or normalize names that don’t follow the convention when saving/registering.
  • Document the pattern in this repo (e.g. in Design Guide or a dedicated doc).

• Disk space management (cleanup old images)

  • Policy: e.g. max total size, max age, or “keep last N” per project/pattern.
  • Implement cleanup (remove .tar files and optionally docker rmi for loaded copies) and optionally a localci images prune (or similar) command.
  • Respect disk_min_free_gb-style limits from config if present (see Design Guide).

Acceptance Criteria

• Load: Any registered .tar path can be loaded and used for a job; errors for missing/corrupt files are explicit.
• Create: When registry returns “needs_build” with a base image, a new image is built, saved, and registered.
• Save: New images are written to images/<project>/<name>.tar and appear in the registry.
• Naming: Only compliant names are accepted when saving/registering; examples are documented.
• Cleanup: Configurable cleanup keeps disk under the chosen limit and does not delete images that are still in use (e.g. referenced by current run).

References

• Design Guide: docs/Design Guide.md — Image Management System (Architecture), Image Storage & Image Registry Format (C), New Image Creation Process (E), Image Naming Convention (E.4), docker load/docker save examples.
• Parent epic: Local CI System for Capy.
• Related: Issue 3 (Image Registry & Matching), Issue 5 (Job Executor with act).

---

Branch: feature/docker-image-management