How rtvkiz/minimal works
Purpose and entry points
This repository defines and publishes 96 small, hardened OCI container images for linux/amd64 and linux/arm64. Primary developer entry points are root Make targets (Makefile), per-image build recipes, and GitHub Actions. Published artifacts are consumed from GHCR; the public catalog is built as a static site.
Paths: Makefile, README.md, .github/workflows/build.yml
Image recipe model
Each image is an isolated top-level component directory. Production and development image definitions use apko YAML; source-built applications add a melange package recipe. This separates package construction from final image assembly, while allowing apko-only images where no custom package build is required.
Paths: caddy/melange.yaml, caddy/apko/caddy.yaml, caddy/apko/caddy-dev.yaml
Catalog as the registry boundary
catalog.json is the canonical declared image inventory and is validated against CI’s build matrix. It is also an input to the catalog site, providing a boundary between image metadata/build definitions and user-facing discovery. The site’s data-generation script produces image data consumed by Astro pages.
Paths: catalog.json, site/scripts/build-data.mjs, site/src/data/images.json
Build, publish, and attest pipeline
The central CI workflow builds the catalog on a six-hour cadence and publishes production images. The project’s artifact contract includes keyless Cosign signatures, SPDX SBOM attestations, and SLSA provenance. GHCR is the image distribution service; GitHub Actions OIDC underpins the documented keyless verification model.
Paths: .github/workflows/build.yml, cosign/apko/cosign.yaml, .github/SECURITY.md
Security scanning and vulnerability assertions
Grype findings are informational for publication but feed the catalog and GitHub Security reporting. Per-image OpenVEX documents express vulnerability status; repository tooling reconciles them against fresh scans so suppressions remain current. This makes scan output and VEX status distinct security data streams.
Paths: vex/python.openvex.json, tools/vex/reconcile.sh, grype/apko/grype.yaml
Update automation and dependency maintenance
Independent automation loops update application versions, rebuild against current Wolfi packages, and patch vulnerable transitive dependencies. Version policy and coverage are represented centrally, while scripts create and manage update PRs. These flows modify image recipes rather than directly changing published artifacts.
Paths: .github/versions.yaml, .github/scripts/check-upstream.sh, .github/workflows/patch-deps.yml
Static documentation and catalog delivery
The site/ subproject is an Astro/TypeScript static site presenting image pages and operational documentation. It consumes generated image data and is deployed independently from the image build workflow, via a dedicated GitHub Actions workflow, to minimalcontainers.com.
Paths: site/package.json, site/src/pages/images/[name].astro, .github/workflows/deploy-site.yml
Main entry points: build.yml Build and publish CI · caddy.yaml Production image recipe · Makefile Make targets · catalog.json Image inventory
Components 22
Image recipes
Per-image package and image definitions.
- Caddy package recipe · Builds source-based application packages.
caddy/melange.yaml - Production image recipe
caddy/apko/caddy.yaml - Development image recipe
caddy/apko/caddy-dev.yaml - Cosign image recipe
cosign/apko/cosign.yaml - Grype image recipe
grype/apko/grype.yaml
Catalog and site
Inventory-driven public discovery.
- Image inventory · Declared inventory validated against the CI matrix.
catalog.json - Catalog data generator · Generates image data for the static site.
site/scripts/build-data.mjs - Generated image data
site/src/data/images.json - Image catalog pages
site/src/pages/images/[name].astro - Static catalog site
site/package.json - Site deploy workflow · Deploys the catalog independently to minimalcontainers.com.
.github/workflows/deploy-site.yml
CI and maintenance
Build, security, publication, and update automation.
- Build and publish CI · Builds on a six-hour cadence and publishes production images.
.github/workflows/build.yml - GHCR · Distribution endpoint for published images.
- GitHub Actions OIDC · Supports keyless artifact verification.
- Verification guidance
.github/SECURITY.md - OpenVEX assertions · Per-image vulnerability status declarations.
vex/python.openvex.json - VEX reconciliation · Reconciles VEX assertions with fresh scans.
tools/vex/reconcile.sh - Version policy
.github/versions.yaml - Upstream update checks · Creates and manages application-version update PRs.
.github/scripts/check-upstream.sh - Dependency patch workflow · Patches vulnerable transitive dependencies through recipe changes.
.github/workflows/patch-deps.yml
Other components
- Make targets
Makefile - Project guide
README.md
Connections 22
- Project guide → Make targets: documents
- Make targets → Caddy package recipe: builds packages
- Make targets → Production image recipe: assembles images
- Caddy package recipe → Production image recipe: package input
- Production image recipe → Development image recipe: parallel variant
- Image inventory → Build and publish CI: defines build matrix
- Build and publish CI → Production image recipe: builds
- Build and publish CI → GHCR: publishes images
- GitHub Actions OIDC → Build and publish CI: keyless identity
- Cosign image recipe → Build and publish CI: signs and attests
- Verification guidance → GitHub Actions OIDC: documents verification
- Grype image recipe → VEX reconciliation: scan findings
- OpenVEX assertions → VEX reconciliation: reconciles assertions
- Build and publish CI → Grype image recipe: security scanning
- Version policy → Upstream update checks: governs coverage
- Upstream update checks → Production image recipe: updates recipes
- Dependency patch workflow → Production image recipe: patches recipes
- Image inventory → Catalog data generator: catalog input
- Catalog data generator → Generated image data: generates
- Generated image data → Image catalog pages: supplies image data
- Static catalog site → Image catalog pages: contains
- Site deploy workflow → Static catalog site: deploys