How docker-library/official-images works
Project type and purpose
• This is a monorepo for the “Docker Official Images” project: a tooling and metadata repository that drives the creation, testing, and publication of Docker images to Docker Hub.
• It houses library‐definition files (under library/), per‐image Dockerfiles and contexts, a large functional test suite (test/), build orchestration scripts (.bin/, top‐level shell scripts), and CI configurations (.github/workflows/).
Main components
a. Source repository (GitHub)
• Directory tree:
– library/: image definition files (metadata for tags, architectures, build contexts)
– <name>/... under library/: per‐image Dockerfiles & support files
– test/: test harness, per‐image functional tests, helper scripts
– .bin/ & top‐level scripts: helpers for build context generation, buildx setup, SBOM indexing
– .external-pins/: pinned-from upstream binary sources
– CI config: .github/workflows/
– Root-level Dockerfile, scripts for local experimentation
b. Developer workstation
• Local clone → run test/run.sh, bashbrew, docker buildx locally
c. CI/CD system (GitHub Actions)
• Triggers on PRs and merges
• Steps: lint definitions, generate build contexts, run tests, build multi‐arch images, push to Docker Hub
d. Build tools & orchestration
• bashbrew: CLI to read library definitions and drive builds
• Docker BuildKit & Buildx: multi‐arch builds, image manifest lists
e. External services
• Docker Hub (image registry)
• Upstream package sources (via HTTPS, GPG verification, pinned in .external-pins/)
• PGP keyservers for signature verification
Relationships and data flows
1. Developer edits library/ files or Dockerfiles → commits & pushes to GitHub
2. GitHub Actions workflow kicks off:
• Step – Validate & lint library definitions and Dockerfiles
• Step – Run functional tests (test/run.sh against Docker-in-Docker or BuildKit)
• Step – Invoke bashbrew to generate per-image build contexts (.buildkit-build-contexts.sh)
• Step – Use Docker Buildx to build multi‐arch images
• Step – Publish images & manifest lists to Docker Hub
3. Upstream binary downloads (e.g. Python, Node, etc.) are fetched over HTTPS, verified via GPG or checksums (as per .external-pins/) during image builds
Architectural patterns and design principles
• Monorepo pattern: all images share common tooling, tests, and CI definitions
• Infrastructure as code: build and test pipelines defined entirely in shell scripts and GitHub Actions YAML
• Declarative image definitions: library/<image> files follow RFC-2822‐style manifest format, driving automated tooling
• Single responsibility per container: images are designed for one main process, minimal init (Tini)
• Multi‐arch support using Buildx manifest lists and conditional build logic