Docker Containers

Production-ready Docker images with zero-touch upstream monitoring — when a new version drops, builds happen automatically.

What's in the box

Container	What it does	Variants
postgres	PostgreSQL with extension ecosystem	base, vector, analytics, timeseries, spatial, distributed, full
terraform	Terraform CLI, cloud-provider scoped	base, aws, azure, gcp, full
opentofu	OpenTofu CLI, cloud-provider scoped	base, aws, azure, gcp, full
github-runner	Self-hosted GitHub Actions runner	ubuntu-2404, debian-trixie, windows-ltsc2022 × base/dev
web-shell	Browser-accessible shell over HTTPS	debian (default), alpine, ubuntu, rocky
wordpress	WordPress with PHP optimizations	—
openresty	Nginx + Lua web platform	—
php	PHP-FPM runtime	—
ansible	Automation platform	—
vector	Datadog Vector log/metrics shipper	—
debian	Minimal base image	—
jekyll	Static site generator	—
openvpn	VPN server	—
sslh	SSL/SSH port multiplexer	—
tor	Tor SOCKS proxy — relay, exit, bridge, hidden-service	default, monitoring

All images are published to GHCR and Docker Hub.

How it works

Upstream releases new version
        │
        ▼
  upstream-monitor.yaml     ← daily at 06:00 UTC
  detects version change
        │
        ▼
  Creates PR + triggers
  auto-build.yaml
        │
        ▼
  Build digest label          ← source-cache provenance
  recorded on matrix and direct `./make push` builds
        │
        ▼
  Multi-arch build           ← linux/amd64 + linux/arm64
  (native runners, no QEMU)
        │
        ▼
  Push to GHCR + Docker Hub
  Emit build lineage JSON
        │
        ▼
  Auto-merge PR

Key differentiators:

• Build digest labels — matrix builds and direct ./make push builds carry the descriptive source-cache label; Bake records its OCI containerimage.digest (sha256:) as lineage build_digest (ADR-002)
• Declarative variants — one Dockerfile, N flavors via variants.yaml (ADR-003)
• Build lineage tracking — full provenance chain from source to published image (ADR-004)
• Native multi-arch & multi-OS — parallel linux/amd64 + linux/arm64 builds on dedicated runners with no emulation, plus windows-ltsc2022 for the github-runner image (ADR-001)
• Multi-distro from one source — github-runner and web-shell expand a single template into per-distro Dockerfiles at build time (ADR-006)
• Supply-chain transparency — every published image carries a Sigstore-attested SBOM, a Trivy CRITICAL scan history, and a multi-arch manifest reference. The dashboard surfaces these as click-through trust badges; the /verify-images/ page documents how to reproduce each check locally.

Quick start

# List containers
./make list

# Build a container (auto-discovers latest upstream version)
./make build postgres

# Build with specific version
./make build postgres 17

# Push to registries
./make push postgres

# Check what's upstream
./make version postgres

# Check all containers for updates
./make check-updates

# Show build lineage
./make lineage postgres

# Show image sizes
./make sizes

Adding a container

1. Create a directory with a Dockerfile and a version.sh:

mkdir my-app

2. version.sh discovers the latest upstream version:

#!/bin/bash
source "$(dirname "$0")/../helpers/docker-registry"

get_latest_upstream() {
    latest-docker-tag library/nginx "^[0-9]+\.[0-9]+\.[0-9]+$"
}

handle_version_request "$1" "oorabona/my-app" "^[0-9]+\.[0-9]+\.[0-9]+$" "get_latest_upstream"

3. Build and test:

./make build my-app
./make run my-app

That's it. The CI picks it up automatically on next push.

Requirements

• Docker Engine 20.10+ (or Podman)
• Supported Bash baseline: 4.4+ — mapfile -d is used on the documented extension build path.
• Mike Farah's yq
• jq (for extension builds)
• sha256sum (for extension-build resolver cache identities). GNU coreutils provides it; on macOS, brew install coreutils and put its libexec/gnubin on PATH.
• A timeout accepting -k, for the e2e suite and registry helpers — it keeps container cleanup and registry operations from waiting forever on a child that ignores SIGTERM. GNU coreutils provides it and most Linux distributions ship it; on macOS, brew install coreutils and put its libexec/gnubin on PATH. Both consumers probe at startup for a timeout that accepts -k, so one that does not fails immediately rather than during cleanup or a registry operation. That probe reads the interface, not the behaviour: an implementation that took the flag and ignored it would still get through.

Documentation

• Development Guide — internals, variants, build system
• CI/CD Workflows — GitHub Actions reference
• Architecture — pipeline design
• Local Development — dev setup
• Testing Guide — running tests locally
• Container Dashboard — live build status with trust badges
• Verify Images — reproduce SBOM / Trivy / multi-arch checks locally

License

MIT