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
- Create a directory with a
Dockerfile and a version.sh:
mkdir my-app
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"
- 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
License
MIT
