Named build stages in Docker - Commands & Configuration

Introduction

When building Docker images, you often need to run multiple steps like compiling code and then packaging it. Named build stages let you split these steps clearly and reuse parts, making builds faster and images smaller.

When you want to compile your application in one step and copy only the final files to the image.

When you need to keep your final image small by excluding build tools.

When you want to organize complex Dockerfiles into clear sections.

When you want to speed up builds by caching intermediate steps.

When you want to share files between different build steps safely.

Config File - Dockerfile

Dockerfile

FROM golang:1.20 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

FROM alpine:3.18
WORKDIR /app
COPY --from=builder /app/myapp .
CMD ["./myapp"]

This Dockerfile has two named stages:

• builder: Uses the Go language image to compile the app.
• The final stage: Uses a small Alpine Linux image and copies only the compiled app from the builder stage.

This keeps the final image small and clean.

Commands

Builds the Docker image using the Dockerfile in the current folder. It runs all stages and creates the final image tagged 'my-go-app'.

Terminal

docker build -t my-go-app .

Expected Output

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

 => [builder 1/4] FROM golang:1.20 AS builder  0.0s

 => CACHED [builder 2/4] WORKDIR /app  0.0s

 => CACHED [builder 3/4] COPY . .  0.0s

 => [builder 4/4] RUN go build -o myapp  10.0s

 => [final 1/3] FROM alpine:3.18  0.0s

 => CACHED [final 2/3] WORKDIR /app  0.0s

 => [final 3/3] COPY --from=builder /app/myapp .  0.1s

 => exporting to image  2.0s

 => => exporting layers  1.9s

 => => writing image sha256:abcdef1234567890  0.0s

Successfully built sha256:abcdef1234567890

Successfully tagged my-go-app:latest

Shows the list of images with the name 'my-go-app' to verify the image was created.

Terminal

docker images my-go-app

Expected Output

REPOSITORY   TAG       IMAGE ID       CREATED          SIZE

my-go-app    latest    abcdef123456   10 seconds ago   15MB

Runs the built image to check if the application starts correctly. The --rm flag removes the container after it stops.

Terminal

docker run --rm my-go-app

Expected Output

Hello from my Go app!

→

--rm - Automatically remove the container after it exits

Key Concept

If you remember nothing else from this pattern, remember: named build stages let you separate build steps and copy only what you need to the final image, making it smaller and cleaner.

Common Mistakes

Not naming the build stage and trying to copy from an unnamed stage.

Docker cannot copy files from a stage without a name, so the build fails.

Always add 'AS stage-name' after the FROM line to name your build stage.

Copying files that do not exist in the named stage.

The build fails because the source path is wrong or the file was not created.

Make sure the file or folder exists in the named stage before copying it.

Using a large base image in the final stage instead of a minimal one.

This makes the final image unnecessarily large and slow to deploy.

Use a small base image like Alpine for the final stage to keep the image size small.

Summary

Use named build stages to split your Dockerfile into clear steps.

Build your app in one stage and copy only the needed files to the final stage.

This approach keeps your final image small and your build organized.

Practice

1. What is the main purpose of using named build stages in a Dockerfile?

easy

A. To automatically update Docker images

B. To split the build process into parts and reuse files between them

C. To create multiple Dockerfiles in one file

D. To run multiple containers at the same time

Solution

1. Step 1: Understand what named build stages do

   Named build stages let you divide your Docker build into parts with names, making it easier to manage.

2. Step 2: Recognize the benefit of reusing files

   You can copy files from one named stage to another, which helps keep images smaller and cleaner.

3. Final Answer:

   To split the build process into parts and reuse files between them -> Option B

4. Quick Check:

   Named build stages = split and reuse [OK]

Hint: Named stages let you copy files between build steps [OK]

Common Mistakes:

• Confusing named stages with running multiple containers
• Thinking named stages create multiple Dockerfiles
• Believing named stages update images automatically

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

easy

A. STAGE node:18 builder

B. BUILD node:18 AS builder

C. FROM node:18 AS builder

D. FROM node:18 WITH builder

Solution

1. Step 1: Recall Dockerfile syntax for naming stages

   The correct syntax uses the FROM instruction followed by the image and AS plus the stage name.

2. Step 2: Check each option

   Only FROM node:18 AS builder uses FROM node:18 AS builder, which is correct syntax.

3. Final Answer:

   FROM node:18 AS builder -> Option C

4. Quick Check:

   Named stage syntax = FROM ... AS ... [OK]

Hint: Use FROM image AS name to name stages [OK]

Common Mistakes:

• Using BUILD or STAGE instead of FROM
• Omitting the AS keyword
• Using WITH instead of AS

3. Given this Dockerfile snippet, what will be the final image size compared to a single-stage build?

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

medium

A. Smaller, because only needed files are copied from builder

B. Larger, because it includes both stages fully

C. Same size, because both stages use the same base image

D. Build will fail due to syntax error

Solution

1. Step 1: Understand multi-stage build effect on image size

   Multi-stage builds copy only required files from earlier stages, reducing final image size.

2. Step 2: Analyze the COPY --from usage

   The final stage copies only /app/node_modules from the builder, not the whole builder image.

3. Final Answer:

   Smaller, because only needed files are copied from builder -> Option A

4. Quick Check:

   Multi-stage copy reduces image size [OK]

Hint: Copy only needed files from builder stage to reduce size [OK]

Common Mistakes:

• Assuming both stages are fully included in final image
• Thinking same base image means same size
• Confusing syntax causing build failure

4. Identify the error in this Dockerfile snippet using named build stages:

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

medium

A. The stage name 'build' is misspelled as 'builder' in COPY

B. Missing RUN command in second stage

C. Cannot use COPY between stages

D. FROM instruction must be last in Dockerfile

Solution

1. Step 1: Check stage names consistency

   The first stage is named build, but COPY uses --from=builder, which is incorrect.

2. Step 2: Understand COPY --from usage

   The --from must match the exact stage name to copy files correctly.

3. Final Answer:

   The stage name 'build' is misspelled as 'builder' in COPY -> Option A

4. Quick Check:

   Stage name mismatch causes COPY error [OK]

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

Common Mistakes:

• Assuming COPY can't copy between stages
• Ignoring stage name spelling
• Thinking RUN is required in second stage

5. You want to build a Docker image that compiles a Go app in one stage and produces a small final image with only the binary. Which Dockerfile snippet correctly uses named build stages to achieve this?

hard

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

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

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

D. FROM golang:1.20 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp
FROM alpine:latest
COPY --from=builder /app/myapp /usr/local/bin/myapp
CMD ["myapp"]

Solution

1. Step 1: Identify multi-stage build for compiling and final image

   FROM golang:1.20 AS builder
   WORKDIR /app
   COPY . .
   RUN go build -o myapp
   FROM alpine:latest
   COPY --from=builder /app/myapp /usr/local/bin/myapp
   CMD ["myapp"]

   uses a builder stage with golang image to compile, then copies only the binary to a small alpine image.

2. Step 2: Check other options for correctness

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

   installs Go in alpine, which is less efficient. Single-stage builds do not use multi-stage builds, so final image is large.

3. Final Answer:

   Uses golang:1.20 AS builder to compile and alpine:latest for the final binary-only image -> Option D

4. Quick Check:

   Multi-stage build with builder and final stage =

   FROM golang:1.20 AS builder
   WORKDIR /app
   COPY . .
   RUN go build -o myapp
   FROM alpine:latest
   COPY --from=builder /app/myapp /usr/local/bin/myapp
   CMD ["myapp"]

   [OK]

Hint: Use builder stage to compile, final stage to copy binary only [OK]

Common Mistakes:

• Installing build tools in final image
• Not using multi-stage build
• Copying entire source instead of just binary