Dockerfile & Images

FROM sets the filesystem your image starts from. Full distro images have every tool but are large; -slim strips docs and extras; Alpine is tiny but uses musl libc; distroless ships only the runtime with no shell or package manager; scratch is empty and only fits static binaries. Pick the smallest image that still runs and that you can still debug.

The classic builder ran instructions strictly top to bottom, one container per step. BuildKit builds a dependency graph, so independent stages run in parallel, unused stages are skipped, and only the build-context files actually needed are transferred. It also adds features the old builder lacks: secret, cache and ssh mounts, and multi-platform builds.

ENTRYPOINT is the executable that always runs; CMD gives default arguments, or the whole command when there is no ENTRYPOINT. Arguments after the image name in docker run replace CMD but are appended to ENTRYPOINT.

The . is the build context: the directory tree the CLI packages up and hands to the builder before building. Only files inside it can be used by COPY, and everything not excluded by .dockerignore is transferred.

Each FROM starts a new build stage with its own fresh filesystem. Compile in a toolchain stage, then start a slim runtime stage and pull across only the built artifact with COPY --from. Only the last stage's layers ship.

COPY just copies files from the build context into the image. ADD does that plus two magic behaviours: it auto-extracts local tar archives and can fetch remote URLs. Default to COPY because its behaviour is predictable; use ADD only when you want extraction.

USER sets the UID/GID that later build steps and the container's main process run as. Without it everything runs as root (UID 0). Recipe: create a user, chown the app files to it, then USER before CMD.

WORKDIR sets the working directory for every following instruction and for the container's main process, and creates it if missing. Each RUN runs in its own shell, so a cd inside one RUN is forgotten when that step ends.

The container sees debug: docker run -e overrides the image's ENV default. During the build, an ENV always beats a same-named ARG, so --build-arg LOG_LEVEL=trace is ignored for later build steps unless the ENV is written as ENV LOG_LEVEL=${LOG_LEVEL}.

A tag is a mutable pointer: the same tag can resolve to different image content over time. A digest is the sha256 hash of the image manifest, so it is immutable and content-addressed. Tags give you automatic patch updates; digests give you reproducible, verifiable builds. Pin digests for release builds and update them with automation.

BuildKit converts the Dockerfile into a dependency graph and solves only the steps the requested output actually needs, so a stage nothing copies from is pruned. The legacy builder walked the file top to bottom, so every stage ran.

Use BuildKit mounts. RUN --mount=type=secret,id=tok exposes the value as a file under /run/secrets for that one instruction only, and it is never written to a layer or to image history. For private Git over SSH use --mount=type=ssh to forward the agent. Never pass credentials via ARG, ENV or COPY.

Shell form runs the command via /bin/sh -c, so the shell is PID 1 and usually does not forward the SIGTERM that docker stop sends — the container is SIGKILLed after the timeout. Exec (JSON) form runs the process directly as PID 1, so it receives the signal.

It sits at the build-context root and lists patterns excluded before the context is sent. Patterns are path-matched with *, ? and **, ! re-includes, and the last matching line wins. Unlike .gitignore, a bare name like node_modules matches only at the top level — use **/node_modules.

The --load flag copies the build result into the local Docker image store, which holds one architecture per tag, so a two-platform result has nowhere to go. Push it to a registry with --push instead, or load one platform at a time.

Every RUN, COPY and ADD commits a new immutable layer. Files created in one layer and deleted in a later one still ship — deletion only writes a whiteout marker. Chaining with && lets the cleanup happen inside the same layer, so the bytes never exist in the image.

EXPOSE only records metadata: which ports the image intends to listen on. It publishes nothing. To reach a port from the host you must publish it at run time with -p host:container, or -P to map every EXPOSEd port to a random host port.

HEALTHCHECK CMD runs a command inside the container on a schedule: exit 0 means healthy, 1 means unhealthy. --interval is the gap between checks, --timeout kills a hung check, --retries is how many consecutive failures flip the status, --start-period is a startup grace window where failures do not count.

Yes, it is recoverable. docker history --no-trunc shows the build instructions with the substituted value, and anything the token was written into (an .npmrc, a cached file) stays in that layer. Use a BuildKit secret mount instead, and rotate the token.

An ARG declared before the first FROM lives in a global scope usable only by FROM lines. Build stages do not inherit it. Re-declare ARG APP_VERSION (no value needed) inside the stage; the value passed or defaulted globally is then applied.

A cache mount gives a RUN instruction a persistent directory that lives on the builder across builds and is not part of any layer. Layer caching reuses whole instruction results and is invalidated by any input change; a cache mount still helps after invalidation, because the package manager's downloads or compiler outputs survive. Use it for dependency and compiler caches.

Run docker run --rm -it --entrypoint sh myimage. The flag replaces the image's ENTRYPOINT for that container only; anything you type after the image name still becomes the arguments, replacing CMD.

Run docker build -f docker/api.Dockerfile -t api . from the repository root: -f locates the Dockerfile, the positional argument sets the context. Besides a local directory, the context can be a Git repository URL, a tarball URL, or a tar/Dockerfile piped on stdin with -.

BUILDPLATFORM describes the machine running the build; TARGETARCH describes the architecture currently being produced. Pinning a stage with FROM --platform=$BUILDPLATFORM keeps that stage on the builder's own architecture so its toolchain runs natively and cross-produces output for TARGETARCH.

COPY --from accepts a stage name declared with FROM ... AS name, a stage index (--from=0), or any external image reference such as --from=nginx:1.27. Source paths are resolved inside that stage or image, not in the build context.

Layer the stages: a shared base, a deps stage, a dev/test stage with tooling, and a lean final stage. Build a specific one with docker build --target dev. Without --target the last stage in the file is built, so keep production last.

The string form is shell form: Docker runs it via /bin/sh -c, so variables, globs, pipes and && work. The JSON-array form is exec form: the binary is executed directly with no shell, so shell syntax is literal and the image needs no shell.

Use LABEL key=value in the Dockerfile; values land in the image config and are readable with docker inspect. Use the standard OCI keys org.opencontainers.image.* (source, revision, version, created, title, licenses) so tooling and registries recognize them. MAINTAINER is obsolete.

ENV persists into the image, so every container and every downstream image inherits DEBIAN_FRONTEND=noninteractive and any interactive apt or dpkg run later misbehaves. Set it per instruction (RUN DEBIAN_FRONTEND=noninteractive apt-get ...) or as an ARG, which does not persist.