Targeting specific stages in Docker - Commands & Configuration

Introduction

When building Docker images, you can create multiple steps called stages. Targeting specific stages lets you build only part of the image, saving time and space.

When you want to build only the final app without the build tools to keep the image small

When you want to test or debug an intermediate stage separately

When you want to reuse a build stage for different final images

When you want to speed up builds by skipping unnecessary stages

When you want to create multiple images from one Dockerfile with different contents

Config File - Dockerfile

Dockerfile

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

FROM nginx:1.23 AS production
COPY --from=builder /app/build /usr/share/nginx/html

FROM node:18 AS test
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install
COPY . .
CMD ["npm", "test"]

This Dockerfile has three stages:

• builder: installs dependencies and builds the app
• production: copies built files from builder to nginx image
• test: installs dependencies and runs tests

You can choose which stage to build or run.

Commands

Builds only the 'builder' stage to get the build environment and compiled app without creating the final image.

Terminal

docker build --target builder -t my-app-builder .

Expected Output

Sending build context to Docker daemon  12.34MB

Step 1/7 : FROM node:18 AS builder

 ---> 123abc456def

Step 2/7 : WORKDIR /app

 ---> Using cache

 ---> 789def012abc

Step 3/7 : COPY package.json package-lock.json ./

 ---> Using cache

 ---> 345abc678def

Step 4/7 : RUN npm install

 ---> Running in 456def789abc

added 100 packages in 5s

Removing intermediate container 456def789abc

 ---> 901abc234def

Step 5/7 : COPY . .

 ---> Using cache

 ---> 567def890abc

Step 6/7 : RUN npm run build

 ---> Running in 678abc901def

Build completed successfully

Removing intermediate container 678abc901def

 ---> 234def567abc

Successfully built 234def567abc

Successfully tagged my-app-builder:latest

→

--target - Specifies which build stage to build

→

-t - Tags the image with a name

Builds the final production image by copying built files from the builder stage into the nginx base image.

Terminal

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

Expected Output

Sending build context to Docker daemon  12.34MB

Step 1/9 : FROM node:18 AS builder

 ---> 123abc456def

Step 2/9 : WORKDIR /app

 ---> Using cache

 ---> 789def012abc

Step 3/9 : COPY package.json package-lock.json ./

 ---> Using cache

 ---> 345abc678def

Step 4/9 : RUN npm install

 ---> Using cache

 ---> 901abc234def

Step 5/9 : COPY . .

 ---> Using cache

 ---> 567def890abc

Step 6/9 : RUN npm run build

 ---> Using cache

 ---> 234def567abc

Step 7/9 : FROM nginx:1.23 AS production

 ---> 456abc789def

Step 8/9 : COPY --from=builder /app/build /usr/share/nginx/html

 ---> Using cache

 ---> 678def901abc

Step 9/9 : 

 ---> Using cache

Successfully built 678def901abc

Successfully tagged my-app-prod:latest

→

--target - Builds the specified stage

→

-t - Tags the image

Runs the production image to serve the built app using nginx.

Terminal

docker run --rm my-app-prod

Expected Output

No output (command runs silently)

→

--rm - Removes the container after it stops

Builds the test stage to run tests inside the container.

Terminal

docker build --target test -t my-app-test .

Expected Output

Sending build context to Docker daemon  12.34MB

Step 1/7 : FROM node:18 AS test

 ---> 123abc456def

Step 2/7 : WORKDIR /app

 ---> Using cache

 ---> 789def012abc

Step 3/7 : COPY package.json package-lock.json ./

 ---> Using cache

 ---> 345abc678def

Step 4/7 : RUN npm install

 ---> Running in 456def789abc

added 100 packages in 5s

Removing intermediate container 456def789abc

 ---> 901abc234def

Step 5/7 : COPY . .

 ---> Using cache

 ---> 567def890abc

Step 6/7 : CMD ["npm", "test"]

 ---> Using cache

Successfully built 567def890abc

Successfully tagged my-app-test:latest

→

--target - Builds only the test stage

→

-t - Tags the image

Runs the test stage container to execute tests defined in the app.

Terminal

docker run --rm my-app-test

Expected Output

> my-app@1.0.0 test

> jest



 PASS  src/app.test.js

  ✓ renders without crashing (5 ms)



Test Suites: 1 passed, 1 total

Tests:       1 passed, 1 total

Snapshots:   0 total

Time:        2.345 s

→

--rm - Removes container after test run

Key Concept

If you remember nothing else from this pattern, remember: the --target flag lets you build or run only the stage you want from a multi-stage Dockerfile.

Common Mistakes

Not specifying --target when building multi-stage Dockerfiles

Docker builds the last stage by default, which may be larger or not what you want

Use --target with the exact stage name to build only that stage

Using stage names that are not defined in the Dockerfile

Docker will fail with an error saying the target stage does not exist

Check the Dockerfile for exact stage names and use those with --target

Trying to run intermediate build stages without CMD or ENTRYPOINT

Containers will exit immediately because no command is specified

Add CMD or ENTRYPOINT in the stage if you want to run it as a container

Summary

Use multi-stage Dockerfiles to separate build, test, and production steps.

Use docker build --target stage_name to build only a specific stage.

Run images built from specific stages to test or deploy parts of your app.

Practice

1. What does the --target <stage-name> option do when building a Docker image?

easy

A. It deletes the specified stage from the Dockerfile.

B. It builds only the specified stage in a multi-stage Dockerfile.

C. It runs the container from the specified stage.

D. It tags the image with the stage name.

Solution

1. Step 1: Understand multi-stage Dockerfiles

   Multi-stage Dockerfiles have multiple build stages named with AS <stage-name>.

2. Step 2: Purpose of --target

   The --target <stage-name> option tells Docker to build only up to that named stage, skipping later stages.

3. Final Answer:

   It builds only the specified stage in a multi-stage Dockerfile. -> Option B

4. Quick Check:

   --target builds specific stage [OK]

Hint: Use --target to build just one stage fast [OK]

Common Mistakes:

• Thinking --target runs containers
• Confusing --target with image tagging
• Assuming --target deletes stages

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

easy

A. FROM ubuntu WITH builder

B. FROM ubuntu TO builder

C. FROM ubuntu STAGE builder

D. FROM ubuntu AS builder

Solution

1. Step 1: Identify stage naming syntax

   Dockerfile uses FROM <image> AS <stage-name> to name stages.

2. Step 2: Check options

   Only FROM ubuntu AS builder uses AS correctly to name the stage.

3. Final Answer:

   FROM ubuntu AS builder -> Option D

4. Quick Check:

   Stage naming uses AS keyword [OK]

Hint: Remember: FROM ... AS stageName [OK]

Common Mistakes:

• Using TO or WITH instead of AS
• Missing the AS keyword
• Confusing stage naming with container commands

3. Given this Dockerfile snippet:

FROM node:18 AS build
RUN npm install
FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html

What happens if you run docker build --target build .?

medium

A. Fails because --target cannot be used with COPY --from.

B. Builds both stages and creates a final image with nginx.

C. Builds only the node:18 stage and stops before nginx stage.

D. Builds only the nginx stage and ignores node:18 stage.

Solution

1. Step 1: Identify stages and target

   The Dockerfile has two stages: 'build' (node:18) and default (nginx:alpine). The command targets 'build'.

2. Step 2: Effect of --target build

   Using --target build builds only the first stage and stops before the second stage.

3. Final Answer:

   Builds only the node:18 stage and stops before nginx stage. -> Option C

4. Quick Check:

   --target stops build at named stage [OK]

Hint: Target stage builds only that stage, skips later ones [OK]

Common Mistakes:

• Assuming all stages build with --target
• Thinking COPY --from breaks build
• Confusing target stage with final image

4. You have this Dockerfile snippet:

FROM python:3.12 AS base
RUN pip install flask
FROM base
RUN pip install pytest

You run docker build --target test . but get an error: "unknown stage name test". What is the likely cause?

medium

A. The stage name 'test' is not defined correctly in the Dockerfile.

B. You must build the 'base' stage first before 'test'.

C. The Docker version does not support multi-stage builds.

D. The --target option cannot be used with Python images.

Solution

1. Step 1: Check stage naming

   The Dockerfile snippet defines 'base' with AS base correctly, but the second stage FROM base lacks AS test, so 'test' is not defined.

2. Step 2: Identify error cause

   The error "unknown stage name test" means Docker did not recognize 'test' stage due to improper definition.

3. Final Answer:

   The stage name 'test' is not defined correctly in the Dockerfile. -> Option A

4. Quick Check:

   Unknown stage means wrong or missing stage name [OK]

Hint: Check stage names exactly match in Dockerfile and command [OK]

Common Mistakes:

• Assuming stages build in order automatically
• Ignoring Docker version compatibility
• Thinking --target depends on image type

5. You want to build only the 'final' stage from this Dockerfile:

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

Which command correctly builds only the 'final' stage?

medium

A. docker build --target final .

B. docker build --target builder .

C. docker build --stage final .

D. docker build --name final .

Solution

1. Step 1: Identify the stage to build

   The Dockerfile has two stages: 'builder' and 'final'. We want to build 'final'.

2. Step 2: Use correct build command

   The correct syntax to build a specific stage is docker build --target <stage-name> .. So use --target final.

3. Final Answer:

   docker build --target final . -> Option A

4. Quick Check:

   --target final builds final stage [OK]

Hint: Use --target with exact stage name to build it [OK]

Common Mistakes:

• Using --stage or --name instead of --target
• Building wrong stage name
• Forgetting the dot (.) at the end