A production container rarely needs compilers, package managers, test fixtures and source-control tools at runtime. Docker multi-stage builds let you compile or assemble an application in one stage and copy only the required artifacts into a smaller final image.
Separate build and runtime responsibilities
Choose a builder image with the toolchain required by the project. Install dependencies using lockfiles, compile the application and run tests. In the final stage, use a minimal compatible runtime and copy the built artifact. This reduces image size and removes many tools an attacker could otherwise use after compromising the container.
Example pattern
FROM golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/service ./cmd/service
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/service /service
USER nonroot:nonroot
ENTRYPOINT ["/service"]
Check the current supported versions and compatibility of your chosen base image. Applications that require certificates, timezone data or shared libraries must include those runtime dependencies explicitly.
Improve cache efficiency
Copy dependency manifests before application source so dependency installation can be cached when only code changes. Use a restrictive .dockerignore to exclude local build output, secrets, Git history and test artifacts. BuildKit cache mounts can speed package downloads without copying the cache into the final image.
Keep secrets out of layers
Do not pass build credentials through ordinary build arguments or write them into image layers. Use BuildKit secret mounts for private package access. Ensure the build output itself does not embed credentials or private configuration.
Run with least privilege
Use a non-root runtime user, read-only filesystem where practical, dropped Linux capabilities and explicit CPU and memory limits. Pin image versions and scan the final artifact. A small image is not automatically secure; it still needs patching and provenance.
Verify the final image
- Inspect image size and included packages.
- Run the container as a non-root user.
- Test health checks and graceful shutdown.
- Scan for vulnerabilities and leaked secrets.
- Generate an SBOM and sign release artifacts.
Multi-stage builds make the boundary between build-time and runtime dependencies explicit. For adjacent topics, see container security controls and multi-platform Buildx builds.
Design and prerequisites
Keep the final image intentionally minimal, but do not remove runtime components the application actually needs. Some programs require CA certificates, timezone data, shared libraries, user records or writable temporary directories. Run the final image in an environment that resembles production and test startup, health checks, DNS, outbound TLS and graceful shutdown. A binary that compiles successfully in the builder can still fail at runtime if it expects a library or file that was never copied into the final stage.
Configuration strategy
Optimize layer caching by copying dependency manifests before application source. This allows package installation to be reused when only source files change. Use a restrictive .dockerignore to exclude local build output, secrets, editor files and Git history. BuildKit cache mounts can accelerate dependency downloads without adding caches to the runtime image. Do not optimize for the smallest possible image at the expense of reproducibility or security updates; the goal is a maintainable artifact with only necessary runtime dependencies.
Security and compatibility
Keep credentials out of image layers. Build arguments and environment variables can be recorded in image metadata or build history, so use BuildKit secret mounts for private package registries. Ensure the build output does not embed credentials or private configuration. Scan the source tree and final image for accidental secrets. If a credential has entered a layer, deleting it in a later layer does not remove it from the earlier image history; rotate it and rebuild from a clean context.
Testing and validation
Run the container with least privilege. Use a non-root UID, drop Linux capabilities, enable a read-only root filesystem where possible and mount only required writable paths. Set CPU and memory requests or limits in the orchestrator. Avoid privileged mode and host networking unless there is a documented requirement. A small image still needs runtime restrictions because vulnerabilities in the application or its dependencies can be exploited regardless of the base image size.
Monitoring and diagnosis
Pin base images by a controlled version or digest and define an update process. Rebuild regularly to pick up security patches, even when application source has not changed. Generate an SBOM, scan the final artifact and sign it as part of the release pipeline. Promote the same digest from staging to production rather than rebuilding at each environment. This creates a traceable chain between tested code and the container that is actually running.
Operations and maintenance
Test signal handling and process behavior. Use exec-form ENTRYPOINT and CMD so the application receives termination signals directly. Confirm that it stops accepting new requests, drains active work and exits within the container platform’s grace period. Check that logs go to stdout and stderr and that health checks reflect application readiness rather than merely the existence of a process. Document the expected UID, writable directories and required environment variables for operations teams.
Operational handover and review
Before handing this implementation to an operations team, document the configuration owner, supported versions, dependency map and escalation path. Include the commands or dashboard views needed to verify normal operation, along with expected values and known limitations. Store configuration in version control, review changes through the normal deployment process and keep a tested rollback procedure. Schedule periodic reviews because upstream components, security requirements and workload patterns change. A short runbook should explain how to identify a failed component, what evidence to collect, which actions are safe to retry and when to escalate. Test that runbook during a maintenance exercise rather than waiting for an outage. Finally, measure the result against a baseline: reliability improvements should be visible in error rates, latency, resource consumption, recovery time or reduced manual work. This makes the implementation maintainable after the original developer has moved to another project.
Change management and production verification
Create a controlled change record for every production adjustment. Record the current value, intended value, reason, approver and expected impact before changing the live configuration. Use a staging environment or a representative test fixture to verify behavior, and compare the result against a known baseline. Keep rollback instructions beside the change record, not in an engineer’s private notes. If the change affects a shared service, coordinate the maintenance window with its consumers and define how they will report regressions.
Service-level observability
Build operational dashboards around outcomes rather than configuration alone. Track the service-level indicators that show whether the system is working: request success, latency, queue delay, resource pressure, error counts and recovery time. Add component-specific metrics where they help explain a failure, but avoid collecting high-cardinality labels that make monitoring expensive or unstable. Define alert thresholds with an owner and a response action. An alert that has no documented next step will eventually be ignored.
Failure testing and recovery
Test failure modes before declaring the work complete. Simulate a dependency outage, an invalid input, a restart during active work and a resource limit being reached. Confirm that the system fails safely, preserves recoverable state and produces useful logs. Verify that retries are bounded and that repeating an operation does not create duplicate side effects. Capture the observed behavior in a runbook so the next operator can distinguish a transient issue from a configuration defect.
Ongoing review
Review the design after the first production cycle. Compare expected and actual resource use, support incidents, maintenance effort and user impact. Remove temporary exceptions that are no longer required, update version pins deliberately and check upstream release notes before upgrades. Re-run the original validation suite after a dependency or runtime change. A technical implementation should remain understandable to a new engineer, so document trade-offs, known limitations and the reasons behind non-obvious settings.
Apply this review specifically to Docker Multi-Stage Builds: Smaller Images and Safer Runtime Containers: confirm the supported runtime and component versions, validate the behavior with a representative workload, and retain evidence from the test. Do not treat a successful configuration reload as proof that the user-facing workflow is healthy. Verify the end-to-end result from the same network path and identity used by the production application.
