Multi-stage for different environments in Docker - Commands & Configuration

Introduction

Building Docker images for different environments like development and production can be slow and create large files. Multi-stage builds let you create smaller, faster images by separating steps for each environment in one file.

When you want a fast image for development with debugging tools included.

When you need a small, secure image for production without extra files.

When you want to avoid repeating similar build steps for different environments.

When you want to keep your Dockerfile clean and easy to maintain.

When you want to reduce the size of your final Docker image to save space.

Config File - Dockerfile

Dockerfile

FROM node:18 AS base
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .

FROM base AS development
ENV NODE_ENV=development
CMD ["npm", "run", "dev"]

FROM base AS production
ENV NODE_ENV=production
RUN npm run build
CMD ["npm", "start"]

This Dockerfile has three stages:

• base: installs dependencies and copies source code, shared by both environments.
• development: uses base, sets environment to development, and runs the app with live reload.
• production: uses base, sets environment to production, builds the app, and runs the optimized version.

This keeps images small and environment-specific.

Commands

Builds the Docker image using the development stage for a fast, debug-friendly environment.

Terminal

docker build --target development -t my-app-dev .

Expected Output

[+] Building 12.3s (10/10) FINISHED

 => [base 1/6] FROM docker.io/library/node:18@sha256:... 

 => CACHED [base 2/6] WORKDIR /app

 => CACHED [base 3/6] COPY package.json package-lock.json ./

 => CACHED [base 4/6] RUN npm install

 => CACHED [base 5/6] COPY . .

 => [development 6/6] ENV NODE_ENV=development

 => exporting to image

 => => exporting layers

 => => writing image sha256:...

Successfully built sha256:...

Successfully tagged my-app-dev:latest

→

--target - Specifies which build stage to use

→

-t - Names the image

Runs the development image, exposing port 3000 to access the app in the browser.

Terminal

docker run --rm -p 3000:3000 my-app-dev

Expected Output

 > my-app@dev

 > next dev



ready - started server on http://localhost:3000

→

--rm - Removes container after it stops

→

-p - Maps container port to host port

Builds the Docker image using the production stage for a small, optimized environment.

Terminal

docker build --target production -t my-app-prod .

Expected Output

[+] Building 15.7s (11/11) FINISHED

 => [base 1/6] FROM docker.io/library/node:18@sha256:... 

 => CACHED [base 2/6] WORKDIR /app

 => CACHED [base 3/6] COPY package.json package-lock.json ./

 => CACHED [base 4/6] RUN npm install

 => CACHED [base 5/6] COPY . .

 => [production 6/7] ENV NODE_ENV=production

 => [production 7/7] RUN npm run build

 > my-app@build

 > next build



 > exporting to image

 > => exporting layers

 > => writing image sha256:...

Successfully built sha256:...

Successfully tagged my-app-prod:latest

→

--target - Specifies which build stage to use

→

-t - Names the image

Runs the production image, exposing port 8080 to access the optimized app.

Terminal

docker run --rm -p 8080:3000 my-app-prod

Expected Output

 > my-app@start

 > next start



ready - started server on http://localhost:3000

→

--rm - Removes container after it stops

→

-p - Maps container port to host port

Key Concept

If you remember nothing else from this pattern, remember: multi-stage builds let you create different environment images efficiently in one Dockerfile.

Common Mistakes

Not using the --target flag when building, so Docker builds all stages instead of just one.

This makes the build slower and the image larger than needed for the environment.

Always use --target with the stage name to build only the needed environment.

Copying unnecessary files in all stages, including development tools in production.

This increases the image size and can expose sensitive files in production.

Use multi-stage builds to copy only what each environment needs.

Running the wrong image tag for the environment, like running the production image during development.

You lose debugging features and live reload, slowing development.

Tag images clearly and run the correct one for each environment.

Summary

Use multi-stage Dockerfiles to separate build steps for development and production.

Build images with the --target flag to choose the environment stage.

Run the correct image tag to get the right environment behavior and size.

Practice

1. What is the main purpose of using multi-stage builds in Docker for different environments?

easy

A. To automatically update Docker images from the internet

B. To run multiple containers simultaneously

C. To create smaller and cleaner Docker images by separating build and runtime stages

D. To increase the size of the Docker image for better performance

Solution

1. Step 1: Understand multi-stage build concept

   Multi-stage builds separate the build environment from the runtime environment to avoid including unnecessary build tools in the final image.

2. Step 2: Identify the benefit for different environments

   This separation results in smaller, cleaner images optimized for the target environment, such as production.

3. Final Answer:

   To create smaller and cleaner Docker images by separating build and runtime stages -> Option C

4. Quick Check:

   Multi-stage builds = smaller images [OK]

Hint: Remember: multi-stage means build then runtime separate [OK]

Common Mistakes:

• Thinking multi-stage runs multiple containers
• Believing it automatically updates images
• Assuming it increases image size

2. Which of the following is the correct syntax to name a build stage in a Dockerfile?

easy

A. STAGE node:18 build

B. FROM node:18 AS build

C. BUILD node:18 AS build

D. FROM node:18 WITH build

Solution

1. Step 1: Recall Dockerfile stage naming syntax

   Docker uses the syntax 'FROM <image> AS ' to name a build stage.

2. Step 2: Check each option

   Only FROM node:18 AS build uses the correct 'FROM ... AS ...' syntax; others are invalid Dockerfile commands.

3. Final Answer:

   FROM node:18 AS build -> Option B

4. Quick Check:

   Stage naming = FROM ... AS ... [OK]

Hint: Look for 'FROM ... AS ...' to name stages [OK]

Common Mistakes:

• Using 'STAGE' or 'BUILD' keywords incorrectly
• Forgetting the AS keyword
• Using 'WITH' instead of AS

3. Given this Dockerfile snippet, what will be the size characteristic of the final image?

FROM node:18 AS build
RUN npm install
FROM node:18-slim
COPY --from=build /app/node_modules /app/node_modules

medium

A. The final image will be smaller because it only copies needed files from build stage

B. The final image will be the same size as the build stage

C. The final image will fail to build due to missing files

D. The final image will be large because it includes all build tools

Solution

1. Step 1: Analyze the multi-stage build steps

   The first stage installs dependencies with full Node image; the second stage uses a smaller Node image and copies only node_modules from the build stage.

2. Step 2: Understand image size impact

   Because only necessary files are copied, the final image is smaller than the full build environment image.

3. Final Answer:

   The final image will be smaller because it only copies needed files from build stage -> Option A

4. Quick Check:

   Copying from build stage reduces final image size [OK]

Hint: Copy only needed files from build stage to keep image small [OK]

Common Mistakes:

• Assuming all build tools are included in final image
• Thinking the build will fail due to missing files
• Believing final image equals build stage size

4. Identify the error in this Dockerfile snippet for multi-stage build:

FROM python:3.12 AS build
RUN pip install -r requirements.txt
FROM python:3.12-slim
COPY --from=builder /app /app

medium

A. The COPY command syntax is incorrect

B. The requirements.txt file is missing

C. The base images are incompatible

D. The stage name 'builder' does not match the first stage name

Solution

1. Step 1: Check stage names consistency

   The first stage is named 'build' but COPY uses '--from=builder', which does not exist.

2. Step 2: Verify COPY command correctness

   The COPY syntax is correct, but the source stage name is wrong, causing build failure.

3. Final Answer:

   The stage name 'builder' does not match the first stage name -> Option D

4. Quick Check:

   Stage names must match exactly in COPY --from= [OK]

Hint: Match stage names exactly in COPY --from= [OK]

Common Mistakes:

• Using wrong stage name in COPY
• Confusing syntax errors with naming errors
• Assuming base images cause this error

5. You want to build a Docker image that uses a heavy build environment only during build, but produces a minimal runtime image for production. Which multi-stage Dockerfile snippet correctly achieves this?

hard

A. FROM golang:1.20 AS build
WORKDIR /app
RUN go build -o app .
FROM alpine:latest
COPY --from=build /app/app /app/app
CMD ["/app/app"]

B. FROM alpine:latest AS build
RUN apk add go
WORKDIR /app
RUN go build -o app .
FROM golang:1.20
COPY --from=build /app/app /app/app
CMD ["/app/app"]

C. FROM golang:1.20
WORKDIR /app
RUN go build -o app .
CMD ["/app/app"]

D. FROM alpine:latest
RUN apk add go
WORKDIR /app
RUN go build -o app .
CMD ["/app/app"]

Solution

1. Step 1: Identify build and runtime separation

   FROM golang:1.20 AS build WORKDIR /app RUN go build -o app . FROM alpine:latest COPY --from=build /app/app /app/app CMD ["/app/app"] uses golang image for building, then copies only the built app to a minimal alpine image for runtime.

2. Step 2: Check other options for correctness

   FROM alpine:latest AS build RUN apk add go WORKDIR /app RUN go build -o app . FROM golang:1.20 COPY --from=build /app/app /app/app CMD ["/app/app"] builds in alpine but runs in golang image, which is opposite of desired minimal runtime. Options C and D do not separate build and runtime stages.

3. Final Answer:

   Option A correctly uses multi-stage build for minimal runtime image -> Option A

4. Quick Check:

   Build heavy, run minimal = FROM golang:1.20 AS build WORKDIR /app RUN go build -o app . FROM alpine:latest COPY --from=build /app/app /app/app CMD ["/app/app"] [OK]

Hint: Build in heavy image, copy to minimal runtime image [OK]

Common Mistakes:

• Building in minimal image causing slow builds
• Running heavy image in production
• Not separating build and runtime stages