# docker-library/official-images architecture

> Architecture diagram of the GitHub repository docker-library/official-images, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/docker-library/official-images
- Repository: https://github.com/docker-library/official-images

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment"
        direction TB
        DevWS["Developer Workstation"]:::dev
        DevGit["git commit & push"]:::dev
        DevBashbrew["bashbrew (local)"]:::tool
        DevBuildx["docker buildx (local)"]:::tool
        DevTestScript["test/run.sh"]:::tool
    end

    %% GitHub Repository
    subgraph "GitHub Repository"
        direction TB
        Library["Library Definition Files"]:::code
        click Library "https://github.com/docker-library/official-images/tree/master/library/"
        PerImage["Per-Image Dockerfiles & Contexts"]:::code
        click PerImage "https://github.com/docker-library/official-images/tree/master/library/<image_name>/"
        TestHarness["Test Harness & Functional Tests"]:::code
        click TestHarness "https://github.com/docker-library/official-images/tree/master/test/"
        TestCases["Individual Test Cases"]:::code
        click TestCases "https://github.com/docker-library/official-images/tree/master/test/tests/"
        BuildContextScript["Build Context Generation Script"]:::code
        click BuildContextScript "https://github.com/docker-library/official-images/blob/master/.buildkit-build-contexts.sh"
        BashbrewEnvScript["Bashbrew BuildKit Env Setup"]:::code
        click BashbrewEnvScript "https://github.com/docker-library/official-images/blob/master/.bin/bashbrew-buildkit-env-setup.sh"
        BuildxEnsureScript["Docker Buildx Ensurance Script"]:::code
        click BuildxEnsureScript "https://github.com/docker-library/official-images/blob/master/.bin/docker-buildx-ensure.sh"
        ExternalPins["External-Pins for Upstream Binaries & GPG Verification"]:::code
        click ExternalPins "https://github.com/docker-library/official-images/tree/master/.external-pins/"
        CIConfig["CI/CD Configuration (GitHub Actions Workflows)"]:::code
        click CIConfig "https://github.com/docker-library/official-images/tree/master/.github/workflows/"
        BashbrewActionDef["Bashbrew GitHub Action Definition"]:::code
        click BashbrewActionDef "https://github.com/docker-library/official-images/blob/master/.github/workflows/.bashbrew/action.yml"
        RootDockerfile["Root-Level Dockerfile for Local Experimentation"]:::code
        click RootDockerfile "https://github.com/docker-library/official-images/tree/master/Dockerfile"
        HelperScripts["Top-Level Build/PR Helper Scripts"]:::code
        click HelperScripts "https://github.com/docker-library/official-images/blob/master/diff-pr.sh"
    end

    %% CI/CD System
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        GHActions["GitHub Actions"]:::ci
        Lint["Lint Definitions"]:::ci
        RunTests["Run Functional Tests"]:::ci
        GenContext["Generate Build Contexts"]:::ci
        BashbrewCI["bashbrew"]:::tool
        Buildx["BuildKit/Buildx"]:::tool
        BuildImages["Build Images"]:::ci
        PushImages["Push to Docker Hub"]:::ci
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DockerHub["Docker Hub (Registry)"]:::ext
        UpstreamBin["Upstream Binaries"]:::ext
        click UpstreamBin "https://github.com/docker-library/official-images/tree/master/.external-pins/"
        PGPServers["PGP Keyservers"]:::ext
    end

    %% Flows
    DevWS --> DevGit
    DevGit --> Library
    DevGit --> PerImage
    Library --> GHActions
    PerImage --> GHActions

    GHActions --> Lint
    Lint --> RunTests
    RunTests --> GenContext
    GenContext --> BashbrewCI
    BashbrewCI --> Buildx
    Buildx --> UpstreamBin
    Buildx --> BuildImages
    BuildImages --> PushImages
    PushImages --> DockerHub

    GHActions -->|"update status"| DevWS

    %% Verification arrow
    Buildx -->|"HTTPS download + GPG verify"| PGPServers

    %% Classes
    classDef code fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef tool fill:#d4edda,stroke:#28a745,color:#000;
    classDef ci fill:#fff3cd,stroke:#ffecb5,color:#000;
    classDef ext fill:#e2e3e5,stroke:#bcbebe,color:#000;
    classDef dev fill:#f0f0f0,stroke:#aaaaaa,color:#000;
```
