Docker Multi-Stage Builds

A Docker multi-stage build uses multiple FROM instructions in a single Dockerfile to build artifacts in one stage and copy only the needed result into a smaller final image.

They reduce image size, improve security, and keep build tooling out of the final runtime image.

A Dockerfile is a text file that defines how an image is built.

A build stage is a section of the Dockerfile starting with a FROM instruction.

The final stage is the last stage in the Dockerfile and is the image that gets produced as the final artifact.

A build stage can compile code, install dependencies, or generate artifacts.

A runtime image is the final image used to run the application in production or development.

They allow builders and compilers to remain in earlier stages while the final image stays lean.

It copies files from one stage into another stage in a multi-stage Dockerfile.

Image layering is how Docker composes read-only filesystem layers to build an image.

Because only necessary files are copied from the build stage into the final image.

A build dependency is a tool or package required only while compiling or packaging the application.

A runtime dependency is a library or package needed when the application actually runs.

A compiled artifact is the output of the build step, such as a binary, JAR, WAR, or static files.

They are usually the only things needed in the final runtime image.

A builder image contains the toolchain required to compile the project.

A distroless image contains only the runtime dependencies and not a package manager or shell.

They reduce attack surface and image size.

A base image is the starting point for a Docker image build.

It is the image produced by the last stage and served to runtime workloads.

To reduce attack surface and avoid unnecessary package installation.

Build in one stage, then copy results into a smaller runtime stage.

Using a build image with the full toolchain to compile for a target environment and then shipping a minimal runtime image.

A Docker stage can be assigned a name using AS stage_name to make copying easier.

AS assigns a name to a stage so it can be referenced later with COPY --from=stage_name.

A stage dependency is when one stage depends on artifacts produced by another stage.

A dependency required for compilation but not needed at runtime.

A package manager such as apt, apk, yum, npm, or Maven is often used during compilation.

Sometimes runtime stage is minimal and may not include package managers at all.

Because they increase image size and can expose vulnerabilities.

A minimal runtime image includes only what the app needs to run.

It often uses a JDK builder stage and a slim JRE final stage.

It often compiles Go code in a Go builder stage and ships a minimal final binary image.

It often compiles or installs dependencies in a node builder stage and ships a minimal runtime image.

It often uses a Node or Nginx builder stage to generate static assets and then copies them into a smaller runtime image.

An artifact path is the directory inside the build stage where compiled or packaged outputs are stored.

The build context is the filesystem sent to the Docker daemon to build the image.

COPY moves files between the build context and stages and between stages themselves.

A final stage often uses a slim OS like alpine, debian-slim, or distroless.

It reduces attack surface by removing shells, package managers, and unnecessary libraries from the final image.

A shell-less image contains no shell binary, making debugging harder but reducing attack surface.

The shell is not needed in many production images and can be exploited if present.

The build stage creates output, while the runtime stage executes and serves the application.

Examples include Maven, Gradle, npm, gcc, make, and other compilers.

A final binary image contains only the compiled binary and minimal runtime dependencies.

An entrypoint defines the command executed when the container starts.

CMD defines default arguments to the entrypoint or the main command when the container starts.

Because the final image might need a runtime command that uses the copied artifact.

A Go final stage may use a scratch image or a tiny alpine image with the compiled binary.

scratch is an empty base image, often producing the smallest possible final image.

It lacks common system libraries and tools, so the binary must be statically linked or contain everything it needs.

Because you may need glibc or other libraries at runtime.

A statically compiled binary contains all required libraries at compile time.

A dynamically linked binary expects shared libraries at runtime.

The runtime image must include necessary shared libraries, increasing image size and compatibility issues.

A compiler toolchain includes compilers, linkers, standard libraries, and build utilities.

A packaging step creates an artifact like a tarball, JAR, or executable from the build.

It installs runtime or build dependencies needed during the build.

Artifact copying moves the built output from build stage to runtime stage.

Docker reuses layers when unchanged, making multi-stage builds faster and more efficient.

A cache layer is a Docker image layer reused when the same steps are repeated without changes.

Each stage can be cached independently, and the final image may re-use earlier build steps.

Docker executes instructions in order, building cacheable layers sequentially.

Because changing an early instruction invalidates later cached layers, which affects build performance.

Install dependencies in a build stage, compile assets if needed, then copy produced files to a runtime stage.

Use a JDK image to compile and package, then copy the JAR to a JRE-based final image.

Use a Go builder image, copy the source code, build the binary, copy the binary into a minimal final image.

Install dependencies in a build stage, maybe compile a wheel, then copy the installed app into a slim Python runtime.

Example: FROM maven:3.9-eclipse-temurin-17 AS build

Example: FROM eclipse-temurin:17-jre-jammy

Example: COPY --from=build /workspace/app.jar /app/app.jar

It affects what files are available to the build and what gets sent to the daemon.

.dockerignore excludes files from the build context, reducing build time and accidentally including secrets.

Because it reduces data sent to Docker and can prevent sensitive files, build artifacts, or caches from being copied.

Example: /workspace/target/app.jar

Use multiple COPY --from=... lines or copy a directory containing multiple outputs.

Named stages improve readability and make stage references explicit.

A dependency required only for the compilation step.

A dependency required only when the app executes.

Image optimization includes reducing layer count, removing unnecessary files, and minimizing runtime dependencies.

Combine related commands into fewer Dockerfile instructions to reduce layer count.

It removes package manager caches to reduce final image size.

It removes temporary package download caches after installation.

It reduces image size and leaves less noise in the final image.

It removes downloaded package metadata to shrink the image.

A library required by the final app at execution time but not during compilation.

The set of tools needed only to compile or package an app.

A clean build stage is a stage that does not carry package manager caches or previous build artifacts.

The final image should have correct file permissions for the runtime user.

A non-root runtime user improves the security posture of the container.

It includes creating a runtime user and setting ownership of application files.

It reduces the impact of attacker code execution within the container.

Some base images run as root by default; better practice is to create a dedicated user for the app.

Because they remove build dependencies and tools from the final image, which reduces the attack surface.

A production image is the final runtime image used in deployment.

A development image may include more tools and debug utilities than a production image.

Development images may need compilers, editors, and debugging tools while production images should be minimal.

Compile site assets in one stage, then serve those static files from a minimal Nginx or static web server image.

Compile the Java app in a JDK stage, then run the JAR in a JRE-based image.

Restore and build in a .NET SDK image, then copy the compiled app into an ASP.NET or runtime image.

mvn dependency:go-offline and compile in the builder stage, then copy the packaged JAR to the runtime stage.

Use a Gradle builder stage to build the application, then copy the JAR or WAR to the final stage.

Use a Node builder stage to install dependencies and build the frontend, then copy built static assets to a smaller runtime image.

Use a Python builder stage for pip install and compile assets, then copy the app into a runtime image.

Because it contains only what is needed to run, but may still require OS binaries and libraries.

It is reuse of previous build instruction outputs to avoid redoing expensive work.

Because it allows dependencies to be cached separately from source changes.

A lockfile pins dependency versions and improves reproducibility during builds.

It speeds up builds and reduces time spent reinstalling dependencies.

They separate dependency installation and compile steps from the final runtime shipping image.

They may need multiple build steps or copying from subdirectories into the runtime stage.

To avoid pulling too much of the source tree into the final image.

A build stage can be named and referred to later, like a namespace.

It allows building a specific stage in a multi-stage Dockerfile instead of the final stage.

It enables building intermediate stages for testing or specialized outputs.

You may build a debug stage with compilers and shells, even if final image is minimal.

A test stage may install test tools and run tests before copying artifacts to the final image.

It validates the app before shipping the production image.

A scanning stage may run SAST or dependency scanning tools before final shipping.

A packaging stage may compress or produce release artifacts for distribution.

A minimal runtime base may be distroless or a tiny alpine image depending on the application requirements.

Image squashing reduces image layers and compresses filesystem content, but it is often not used in normal Docker builds.

BuildKit is the modern Docker builder backend with better caching, concurrent builds, and advanced features.

It improves build efficiency and supports advanced caching semantics.

A build cache mount allows persistent caching of dependency directories across builds.

It enables persistent caching for build dependencies like npm or Maven caches.

A multi-arch build produces images for multiple CPU architectures, such as amd64 and arm64.

Because the builder stage can compile for one architecture and the final stage can package the output for the target arch.

Cross-compilation builds artifacts for a different architecture than the host machine.

It happens when the final image is built for the wrong architecture or the binary is incompatible with the runtime environment.

They can segregate the build environment from the final runtime image to keep the output specific and portable.

It reduces the need for runtime libraries and keeps the final image leaner.

glibc is the GNU C runtime library often needed by dynamically linked binaries.

Because it adds to the image size and complexity.

musl is a lightweight C library used in Alpine and some minimal runtime environments.

A binary compiled against glibc may not run in musl-based image or vice versa.

Binary compatibility means the generated artifact runs on the target environment without requiring different libraries or ABI changes.

It happens when the binary expects a library that is not present in the final image.

An entrypoint script can prepare runtime environment variables, checks, or symlinks before launching the app.

To handle environment initialization, migrations, or dynamic configuration.

It validates that the compiled output works or runs correctly before packaging.

Image signing ensures the image has not been tampered with between build and deployment.

The final image is the signed artifact; the build stage is not usually what is distributed.

Provenance tracks the source, build steps, and environment used to produce the final artifact.

It helps audit and trace how an image was built and what inputs were included.

A security scan checks the final image for known vulnerabilities in packages and libraries.

Because the final image has fewer dependencies and fewer vulnerabilities than the build image.

An SBOM (Software Bill of Materials) documents the components and dependencies in an image.

They improve security visibility and compliance tracking for released images.

A release stage packages and signs the final image for deployment to registries or production systems.

A debug stage includes shells, editors, and debugging tools for troubleshooting.

They increase size and attack surface and are not needed by the runtime app.

It selectively copies the final binary or package from the builder to the runtime stage.

It reduces the risk of including build scripts, source code, secrets, or transient files in the final image.

It may include source code, dependencies, build caches, and credentials, which is often undesirable.

A whitelist is a rule that copies only known required outputs into the final stage.

It minimizes image size and reduces the chance of leaking internal build data.

Maintaining clean layers and removing temporary artifacts is part of robust Docker image design.

Large contexts slow builds and may include unnecessary files.

It can exclude node_modules, build directories, local secrets, and large generated files.

Multiple services or modules may require separate builder stages or multiple output copies.

Because different components may require different build tools, artifact locations, or runtime packaging.

It builds and tests the app, scans the image, and pushes the final runtime image to a registry.

Because it aligns build-time dependencies with final runtime requirements and improves operational quality.

A rootless final image runs the app as a non-root user to reduce privilege risk.

A read-only root filesystem prevents writes to the image filesystem and can be combined with mounted volumes for state.

The image layer is immutable; volumes provide persistence for runtime state.

Because the final image is minimal and state belongs in managed volumes or external storage.

Ship only the artifact and runtime runtime dependencies, with no compilers or package managers.

Build in a rich environment, ship a small and secure environment. That is the heart of Docker multi-stage build design.

It reduces security exposure, deployment time, and operational complexity.

It may leak source code, build logic, and internal structure while increasing attack surface.

Copying the entire source tree or build directory instead of just the required artifact.

Leaving package managers or shell utilities in the final image.

Not optimizing dependency installation ordering and build cache usage.

Compiling against one system library and running against another in the final image.

Check the runtime base image, binary linkage, copied artifact paths, and runtime dependencies.

It makes the build pipeline smaller, faster, and more secure while producing deployable artifacts.

Artifact promotion moves a validated build artifact through the pipeline to higher environments.

It cleanly separates the build environment from the runtime environment, helping security, portability, and operational quality.

Runtime minimalism means the final image contains as little as possible while still running the app correctly.

Build-time richness means the builder stage contains the necessary toolchain and dependencies for compilation.

They reflect the same principle: build once, then ship a focused runtime artifact.

Build phase creates and assembles artifacts; runtime phase executes and serves them.

A good multi-stage Dockerfile is a sign of disciplined engineering: keep the build environment rich, keep the runtime image minimal, and keep the artifact boundaries explicit.