container-workflows

Build minimal, rootless, reproducible container images and ship them safely to registries.

Principles

• Smallest attack surface — fewest packages = fewest CVEs
• Rootless builds — no Docker daemon required (buildah)
• Separate build and runtime stages — compilers never reach production
• Images are immutable — never exec into a running container; rebuild and redeploy

Dockerfile Standards

| Rule | Detail | |---|---| | Multi-stage | Always — builder compiles, runtime stage runs | | Runtime base | FROM scratch / cgr.dev/chainguard/static for static binaries; *-slim for interpreted | | Pin digests | FROM python:3.13-slim@sha256:... — never float on mutable tags | | Non-root USER | USER nobody or dedicated UID — never root | | COPY specific files | Never COPY . .; .dockerignore is a safety net only | | HEALTHCHECK | Always define one for orchestrator integration | | OCI labels | org.opencontainers.image.source, .version, .revision, .created | | Syntax directive | # syntax=docker/dockerfile:1 at top |

Secrets: Never in ENV/ARG/COPY (visible in docker history). Use RUN --mount=type=secret,id=token.

Packages: Always apt-get install --no-install-recommends. Combine update+install+clean in one RUN. Use --mount=type=cache for package manager caches.

Build-to-Push Workflow

# Build (rootless)
buildah build -t myapp:$(git rev-parse --short HEAD) .

# Scan — always before push
trivy image myapp:$(git rev-parse --short HEAD)

# Tag: semver + SHA (never only latest)
buildah tag myapp:$(git rev-parse --short HEAD) myapp:1.4.0

# Push
skopeo copy containers-storage:localhost/myapp:1.4.0 docker://registry.example.com/myapp:1.4.0
skopeo copy containers-storage:localhost/myapp:$(git rev-parse --short HEAD) docker://registry.example.com/myapp:$(git rev-parse --short HEAD)

Tag strategy: 1.4.0 (release, immutable), a3f9b2c (SHA, immutable), latest (convenience only, never used in prod).

Patterns We Use

| Choice | Why | |---|---| | buildah + skopeo | Rootless, daemonless, OCI-native | | Harbor | Private registry with vulnerability scanning and RBAC | | FROM scratch for Rust | Statically linked musl — ~5 MB, zero runtime deps | | Chainguard/distroless | CA certs + tzdata + non-root user out of the box | | python:3.x-slim + uv | Fast installs, small image | | just commands | just build, just scan, just push wrap the cycle |

Anti-Patterns

A successful build does not mean a secure image. Always run trivy image <name> before pushing.

| Don't | Do instead | |---|---| | Run as root | USER nobody or dedicated UID | | Compilers in runtime image | Multi-stage builds | | :latest in production | Pin semver + digest | | Secrets via ENV/ARG | RUN --mount=type=secret or runtime injection | | Docker-in-Docker in CI | Use buildah — rootless, no privileged containers |