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.