Dockerfile & Images

Alpine uses musl libc instead of glibc, so precompiled binaries and Python manylinux wheels built for glibc do not apply. Package managers fall back to compiling from source, which is slow and needs toolchains, and mismatched native libraries fail to load. Unless you have verified the native dependency chain, prefer a glibc -slim base.

The docker-container buildx driver runs BuildKit outside the engine's image store and exports nothing by default, so the result stays in the builder. Add --load to import it into the local engine, or --push to publish it.

Use docker buildx build --platform linux/amd64,linux/arm64 --push, which produces one manifest list (image index) referencing a per-architecture image. The foreign architecture can run under QEMU emulation (simple but slow), on native builder nodes (fast, needs machines of both architectures), or via cross-compilation using BUILDPLATFORM and TARGETARCH (fastest, needs a cross-compiling toolchain).

Set ENTRYPOINT to a small script and CMD to the real command. The script does start-up work — render config, fix permissions, first-run initialisation — then runs exec "$@", replacing itself with the CMD so the real process becomes PID 1 and receives signals.

That pause is the build context being walked and transferred. Measure it with --progress=plain, find the bulk with du, and exclude version-control, dependency and build-output directories via .dockerignore at the context root — which also stops unrelated files from invalidating the COPY layer's cache.

The kernel could not execute the binary because it was compiled for another architecture and no emulation handler is registered. Check the image's recorded architecture, rebuild the image for the host's platform, or run it with docker run --platform and accept the emulation cost.

Stages form a dependency graph, not a list. Independent stages build concurrently, unreferenced stages are skipped, and a cache miss invalidates only the rest of that stage's chain — not sibling stages. Inside each stage, put rarely-changing steps first.

STOPSIGNAL sets which signal the runtime sends to the container's main process on a stop request; the default is SIGTERM, and SIGKILL follows after the grace period. Change it when the application's graceful shutdown uses a different signal, as nginx does with SIGQUIT.

Decide by where the result must land and how insulated the build must be from the host: the built-in docker driver for laptop iteration, and a docker-container or remote builder in CI with push as the default exporter.

It is a BuildKit parser directive naming the frontend image that parses the Dockerfile. BuildKit pulls docker/dockerfile:1 and uses it instead of its built-in parser, so newer Dockerfile syntax works without upgrading the Docker Engine.

Declare ARG above the first FROM and use it in the FROM line, for example ARG BASE=debian:bookworm-slim then FROM ${BASE}. Such an ARG lives in a global scope usable only by FROM lines; to use its value inside a build stage you must re-declare a bare ARG with the same name after that stage's FROM.

--chown sets ownership as the files are written, avoiding a second full-size layer that a later RUN chown would create. --link writes the copied content as a self-contained layer that does not depend on earlier layers, so it stays cached and reusable when the base changes.

Export the build cache to somewhere shared. BuildKit supports --cache-to/--cache-from with an inline cache (embedded in the pushed image, final stage only), a registry cache (separate tag, mode=max keeps intermediate stages), or a local or cloud backend. Weigh cache hit rate against push/pull cost and storage, and scope caches per branch and per platform.

Mandate exec-form instructions, decide one convention for whether ENTRYPOINT is the app or a thin wrapper, guarantee the real process ends up as PID 1 with a SIGTERM handler, standardise grace periods against measured drain time, and enforce it with lint plus an automated termination test.

Pick one of three shapes: per-service contexts (fast, but shared code must be published), one root context with per-Dockerfile ignore files (simple, pays the walk), or a small context plus BuildKit named contexts for shared libraries. Optimise for cache hit rate and transfer cost, and enforce the ignore files automatically.

Decide per image from where it actually runs, not by default: dual-architecture for shared base images and anything developers run locally, single-architecture where a workload is pinned to one host pool. Then test each architecture on native hardware, because build success is not behavioural parity.

Self-contained multi-stage Dockerfiles maximise reproducibility and local parity but rebuild toolchains everywhere. A shared prebuilt builder image centralises the toolchain and speeds cold builds at the cost of a versioned dependency. Copying in an externally built artifact is fastest but loses hermeticity.