Multi-Stage Builds

Last updated: Jun 12, 2026

Author: ManaCoding Team

← Docker Health Checks Image Optimization →

∙ Docker

Multi-Stage Builds covers multiple Dockerfile stages that separate build tools from the final runtime filesystem.

📝Syntax

FROM IMAGE AS build, followed by a minimal runtime stage

multi-stage-builds.sh

📝 Example Command

# Topic: Multi-Stage Builds
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

👁 Output

💡 Copy the example, run it against disposable Docker resources, and compare the resulting state with the lesson.

👀Output

The final image contains the built frontend without Node.js build dependencies

🔍Line-by-Line Explanation

Line	Meaning
`FROM node:20-alpine AS build`	Selects the base image for the new build stage.
`WORKDIR /app`	Sets the working directory used by following instructions.
`COPY package*.json ./`	Copies selected build-context files into the image.
`RUN npm ci`	Executes a build-time command and creates a filesystem layer.
`COPY . .`	Copies selected build-context files into the image.
`RUN npm run build`	Executes a build-time command and creates a filesystem layer.
`FROM nginx:alpine`	Selects the base image for the new build stage.
`COPY --from=build /app/dist /usr/share/nginx/html`	Copies selected build-context files into the image.

🌐Real-World Uses

1Packaging applications for repeatable delivery.
2Improving build cache efficiency.
3Creating smaller production runtime images.

⚠Common Mistakes

1Copying the full builder filesystem defeats size and security benefits.
2Sending unnecessary files in the build context.
3Embedding credentials in image layers.
4Installing build tools in the runtime image.

✓Best Practices

1Copy only required runtime artifacts into a small final stage.
2Keep the build context small with .dockerignore.
3Order stable dependency steps before frequently changed source files.
4Use multi-stage builds where compilation is required.

💡How it works

1Primary Docker responsibility: image build contract.
2Operation performed: create small, reproducible, cache-efficient images.
3The active Docker daemon applies the request to the relevant resource.
4The resulting object state determines whether the operation succeeded.

💡Practical workflow

1Prepare the build context.
2Build with a versioned tag.
3Inspect layers, size, user, and command.
4Run a smoke test from the built image.

💡Verification

1Compare single-stage and multi-stage image size, packages, and runtime behavior.
2Compare the observed state with the expected output shown in this lesson.
3Repeat the check from a clean or disposable Docker environment.
4Confirm the final evidence is a smaller runtime image with the same application behavior.

💡Limits and boundaries

1This topic owns image build contract; related concerns still need their own configuration.
2Docker does not automatically provide secure permissions, durable data, useful monitoring, or recovery.
3Host operating system, architecture, daemon mode, and runtime environment can change the available behavior.
4Add further tooling only when the application requirement cannot be met by this focused Docker feature.

✅Summary

Identify the Docker resource before changing it.
Run the example with disposable test resources.
Inspect the result instead of trusting command success alone.
Keep configuration reproducible across environments.
Finish with an intentional cleanup or retention decision.

🧑‍💻Interview Questions

Q1. Which Docker resource does Multi-Stage Builds affect?

Answer: It primarily concerns image build contract.

Q2. What result should Multi-Stage Builds produce?

Answer: It should produce a reproducible image digest and verified runtime.

Q3. What should be inspected after the operation?

Answer: Inspect the relevant status, metadata, output, dependencies, and cleanup state.

Q4. What production concern matters most?

Answer: Reproducibility and explicit lifecycle ownership are the main production concerns.

Q5. How can the behavior be demonstrated?

Answer: Use the smallest disposable example, observe the state change, and remove the test resources safely.

🎯Quick Quiz

Which approach is best when implementing Multi-Stage Builds?

○Use explicit inputs, inspect the resulting Docker state, and document cleanup. ○Use mutable defaults and skip recording the Docker configuration. ○Keep important data only in the disposable container writable layer. ○Treat the first successful command as proof that production behavior is correct.