Multi-stage Docker builds in Spring Boot - Deep Dive

Overview - Multi-stage Docker builds

What is it?

Multi-stage Docker builds let you create smaller, cleaner Docker images by using multiple steps in one build process. Each step can use a different base image and only the final step's output is kept. This helps separate building your app from running it, making the final image lighter and faster. It's especially useful for complex apps like Spring Boot services.

Why it matters

Without multi-stage builds, Docker images often include unnecessary files and tools used only during building, making them large and slow to deploy. This wastes bandwidth, storage, and slows down startup times. Multi-stage builds solve this by keeping only what is needed to run the app, improving efficiency and security. This means faster updates and better resource use in real projects.

Where it fits

Before learning multi-stage builds, you should understand basic Docker concepts like images, containers, and Dockerfiles. After mastering multi-stage builds, you can explore advanced Docker optimizations, container orchestration with Kubernetes, and CI/CD pipelines that build and deploy containers automatically.

Mental Model

Core Idea

Multi-stage Docker builds use separate steps to build and package your app, keeping only the final necessary files to create a small, efficient image.

Think of it like...

It's like cooking a meal in stages: you prepare ingredients in one kitchen, then only bring the finished dish to the dining table, leaving the messy prep behind.

┌───────────────┐     ┌───────────────┐
│ Build Stage   │     │ Final Stage   │
│ (compile app) │────▶│ (copy output) │
│ Full tools    │     │ Minimal image │
└───────────────┘     └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Docker Images and Layers

Concept: Learn what Docker images are and how they are built in layers.

Docker images are like snapshots of your app and its environment. Each command in a Dockerfile creates a new layer. Layers stack to form the final image. Understanding this helps you see why image size matters and how builds work.

Result

You know that each Dockerfile command adds a layer and that images can get large if layers include unnecessary files.

Understanding layers is key to optimizing Docker images and sets the stage for why multi-stage builds are useful.

2

Foundation

Basic Dockerfile for Spring Boot App

Concept: Create a simple Dockerfile that builds and runs a Spring Boot app in one stage.

A typical Dockerfile might start from a Java base image, copy your app code, build it inside the image, and then run it. This means build tools stay in the final image, making it large.

Result

You get a working Docker image but it is bigger than necessary because it includes build tools and source code.

Seeing the size and contents of a single-stage image shows why separating build and runtime is beneficial.

3

Intermediate

Introducing Multi-stage Build Syntax

🤔Before reading on: do you think multi-stage builds require separate Dockerfiles or just one? Commit to your answer.

Concept: Multi-stage builds use one Dockerfile with multiple FROM statements to define stages.

You can write a Dockerfile with multiple FROM lines. Each FROM starts a new stage with its own base image. You can name stages and copy files from one stage to another using special syntax.

Result

You can build your app in one stage and copy only the final artifact to a smaller runtime image in the next stage.

Knowing that multi-stage builds happen in one Dockerfile simplifies management and improves build efficiency.

4

Intermediate

Building Spring Boot with Multi-stage Dockerfile

🤔Before reading on: do you think the final image will include the entire JDK or just the JRE? Commit to your answer.

Concept: Use a full JDK image to build the app, then copy the built jar to a lightweight JRE image for running.

First stage: use a JDK image, copy source, run ./mvnw package to build jar. Second stage: use a JRE image, copy jar from first stage, run java -jar. This keeps the final image small and secure.

Result

Final image contains only the jar and runtime environment, reducing size significantly.

Separating build and runtime environments reduces image size and attack surface.

5

Intermediate

Optimizing Cache with Multi-stage Builds

🤔Before reading on: do you think changing source code affects all build stages or only some? Commit to your answer.

Concept: Order Dockerfile commands to maximize cache reuse, speeding up builds.

Copy only dependency files first and run dependency download commands before copying full source. This way, if source changes but dependencies don't, Docker reuses cached layers for dependencies.

Result

Build times improve because unchanged layers are reused.

Understanding Docker cache behavior helps write efficient multi-stage Dockerfiles.

6

Advanced

Handling Secrets and Build Arguments Securely

🤔Before reading on: do you think build secrets remain in the final image by default? Commit to your answer.

Concept: Use build arguments and Docker secrets carefully to avoid leaking sensitive data into images.

Pass secrets as build arguments or use Docker BuildKit features to keep secrets out of final images. Avoid copying sensitive files into any stage that ends up in the final image.

Result

Your images do not expose secrets, improving security.

Knowing how to manage secrets prevents accidental leaks in production images.

7

Expert

Advanced Multi-stage Build Internals and Pitfalls

🤔Before reading on: do you think files copied between stages preserve permissions and metadata? Commit to your answer.

Concept: Understand how Docker copies files between stages and how this affects permissions, metadata, and build context size.

Docker copies files from one stage to another using the build context. Permissions may reset, and large contexts slow builds. Also, beware of copying unnecessary files that increase image size. Use .dockerignore to exclude files.

Result

You avoid subtle bugs related to file permissions and reduce build times.

Understanding internal file handling helps prevent hard-to-debug issues and keeps builds efficient.

Under the Hood

Docker builds images by executing each Dockerfile command in order, creating a new layer each time. Multi-stage builds run multiple FROM commands in one Dockerfile, each creating a separate build stage with its own filesystem. Files can be copied from one stage to another using special syntax, but only the final stage's filesystem becomes the final image. This means build tools and intermediate files from earlier stages do not appear in the final image, reducing size and attack surface.

Why designed this way?

Multi-stage builds were introduced to solve the problem of large, bloated images that include build dependencies and source code. Previously, developers had to use multiple Dockerfiles or manual cleanup steps. Combining multiple stages in one Dockerfile simplifies maintenance and automates cleanup. The design balances flexibility with simplicity, allowing complex build pipelines in a single file.

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ Stage 1: Build│     │ Stage 2: Test │     │ Stage 3: Final│
│ - JDK image   │     │ - Optional    │     │ - JRE image   │
│ - Compile app │────▶│ - Run tests   │────▶│ - Copy jar    │
│ - Produce jar │     │               │     │ - Minimal run │
└───────────────┘     └───────────────┘     └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does multi-stage build mean multiple Dockerfiles? Commit yes or no.

Common Belief: Multi-stage builds require separate Dockerfiles for each stage.

Reality: Multi-stage builds happen in a single Dockerfile with multiple FROM commands.

Why it matters: Using multiple Dockerfiles complicates build processes and loses the benefits of single-file management.

Quick: Does the final image include all files from all stages? Commit yes or no.

Common Belief: All files from every build stage end up in the final image.

Reality: Only files copied into the final stage are included; earlier stages are discarded.

Why it matters: Assuming all files remain leads to unnecessarily large images and security risks.

Quick: Are build secrets automatically removed from final images? Commit yes or no.

Common Belief: Secrets used during build are never included in the final image by default.

Reality: If not handled carefully, secrets can leak into image layers and be extracted later.

Why it matters: Leaking secrets can cause serious security breaches in production.

Quick: Does copying files between stages preserve file permissions exactly? Commit yes or no.

Common Belief: File permissions and metadata are always preserved when copying between stages.

Reality: Permissions may reset or change, causing runtime errors if not managed.

Why it matters: Incorrect permissions can cause app failures or security issues.

Expert Zone

1

Docker caches each stage separately, so changing early stages can invalidate cache for later stages unexpectedly.

2

Using lightweight base images like Alpine in the final stage reduces image size but may require extra libraries for your app.

3

Build context size affects build speed; excluding unnecessary files with .dockerignore is critical for efficient multi-stage builds.

When NOT to use

Multi-stage builds are less useful if your app requires dynamic runtime compilation or debugging tools inside the container. In such cases, consider development-specific images or volume mounts. Also, for very simple apps, single-stage builds may be simpler and sufficient.

Production Patterns

In production, multi-stage builds are used to separate build and runtime environments, often combined with CI/CD pipelines that build images automatically. Teams use named stages for clarity, cache dependencies separately, and integrate security scanning on final images to ensure minimal attack surface.

Connections

Continuous Integration/Continuous Deployment (CI/CD)

Multi-stage builds integrate tightly with CI/CD pipelines to automate building and deploying optimized images.

Understanding multi-stage builds helps design faster, more reliable CI/CD workflows that produce smaller, secure images.

Software Build Pipelines

Multi-stage builds mirror traditional build pipelines by separating compile, test, and package steps inside one Dockerfile.

Seeing Docker builds as pipelines clarifies how to structure complex builds and reuse intermediate results.

Manufacturing Assembly Lines

Like assembly lines, multi-stage builds break down production into steps, each adding value and passing on only needed parts.

Recognizing this connection helps appreciate efficiency gains and quality control in software container builds.

Common Pitfalls

#1 Including build tools in the final image, making it unnecessarily large.

Wrong approach:

FROM openjdk:17
COPY . /app
RUN ./mvnw package
CMD ["java", "-jar", "target/app.jar"]

Correct approach:

FROM maven:3.8.6-openjdk-17 AS build
COPY . /app
WORKDIR /app
RUN ./mvnw package
FROM openjdk:17-jre-slim
COPY --from=build /app/target/app.jar /app.jar
CMD ["java", "-jar", "/app.jar"]

Root cause:

Not separating build and runtime stages causes build tools and source code to remain in the final image.

#2 Not using .dockerignore, causing large build context and slow builds.

Wrong approach:

COPY . /app

Correct approach:

Use a .dockerignore file to exclude target/, .git/, and other unnecessary files before COPY . /app

Root cause:

Copying entire project directory without exclusions slows build and increases image size.

#3 Passing secrets as plain build arguments that remain in image layers.

Wrong approach:

ARG SECRET_KEY
RUN echo $SECRET_KEY > secret.txt

Correct approach:

Use Docker BuildKit secrets feature or mount secrets at runtime instead of embedding in image.

Root cause:

Misunderstanding how build arguments persist in image layers leads to secret leaks.

Key Takeaways

Multi-stage Docker builds let you separate building and running your app in one Dockerfile, producing smaller, cleaner images.

Only the final stage's files are included in the image, so build tools and source code can be left behind.

Ordering Dockerfile commands and using .dockerignore improves build speed by maximizing cache reuse and minimizing context size.

Careful handling of secrets during build prevents accidental exposure in images.

Understanding internal file copying and permissions avoids subtle bugs and security issues in production containers.

Practice

1. What is the main benefit of using multi-stage Docker builds for a Spring Boot application?

easy

A. It creates smaller and cleaner Docker images by separating build and runtime stages.

B. It allows running multiple containers from the same image simultaneously.

C. It automatically updates the Spring Boot version inside the container.

D. It enables running the application without a Dockerfile.

Solution

1. Step 1: Understand multi-stage build purpose

   Multi-stage builds separate the build environment from the runtime environment to reduce image size.

2. Step 2: Identify benefit for Spring Boot apps

   By copying only the needed files from build to runtime stage, the final image is smaller and cleaner.

3. Final Answer:

   It creates smaller and cleaner Docker images by separating build and runtime stages. -> Option A

4. Quick Check:

   Multi-stage builds = smaller images [OK]

Hint: Multi-stage builds reduce image size by splitting build and run [OK]

Common Mistakes:

• Confusing multi-stage builds with running multiple containers
• Thinking it updates Spring Boot version automatically
• Believing Dockerfile is not needed

2. Which of the following is the correct syntax to start a new build stage named 'builder' in a Dockerfile?

easy

A. NEW STAGE builder FROM openjdk:17

B. FROM openjdk:17 AS builder

C. BUILD openjdk:17 AS builder

D. STAGE builder FROM openjdk:17

Solution

1. Step 1: Recall Dockerfile multi-stage syntax

   The correct syntax to start a build stage is 'FROM <image> AS <name>'.

2. Step 2: Match syntax to options

   Only FROM openjdk:17 AS builder uses 'FROM openjdk:17 AS builder' which is valid.

3. Final Answer:

   FROM openjdk:17 AS builder -> Option B

4. Quick Check:

   Multi-stage start = FROM ... AS ... [OK]

Hint: Use 'FROM image AS name' to start a build stage [OK]

Common Mistakes:

• Using 'STAGE' or 'BUILD' keywords incorrectly
• Placing 'AS' after the stage name
• Writing 'NEW STAGE' which is invalid

3. Given this Dockerfile snippet for a Spring Boot app:

FROM maven:3.8.6-openjdk-17 AS builder
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests

FROM openjdk:17-jdk-slim
COPY --from=builder /app/target/myapp.jar /app/myapp.jar
ENTRYPOINT ["java", "-jar", "/app/myapp.jar"]

What will be the size impact of this multi-stage build compared to a single-stage build including Maven?

medium

A. The final image will be smaller because Maven and source files are excluded.

B. The final image will be larger because it contains both Maven and JDK.

C. The final image size is the same as a single-stage build.

D. The final image will fail to build due to missing source files.

Solution

1. Step 1: Analyze multi-stage build steps

   The first stage builds the app with Maven, the second stage copies only the jar file.

2. Step 2: Understand image size impact

   Since Maven and source code are not copied to the final image, it is smaller than a single-stage build including Maven.

3. Final Answer:

   The final image will be smaller because Maven and source files are excluded. -> Option A

4. Quick Check:

   Copy only jar = smaller image [OK]

Hint: Final image excludes build tools, so it's smaller [OK]

Common Mistakes:

• Assuming Maven stays in final image
• Thinking source files are copied to final image
• Believing multi-stage builds cause build failure here

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

FROM openjdk:17 AS builder
WORKDIR /app
COPY . .
RUN ./mvnw package

FROM openjdk:17-jdk-slim
COPY /app/target/app.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

medium

A. The first stage should use a Maven image, not openjdk.

B. The ENTRYPOINT syntax is incorrect and will cause a runtime error.

C. The WORKDIR command is missing in the second stage.

D. The COPY command in the second stage uses an absolute path instead of a relative path from the builder stage.

Solution

1. Step 1: Check COPY command in second stage

   The COPY command uses '/app/target/app.jar' which is an absolute path on the host, not from the builder stage.

2. Step 2: Correct COPY syntax for multi-stage

   It should be 'COPY --from=builder /app/target/app.jar /app/app.jar' to copy from the builder stage.

3. Final Answer:

   The COPY command in the second stage uses an absolute path instead of a relative path from the builder stage. -> Option D

4. Quick Check:

   Use COPY --from=builder for multi-stage files [OK]

Hint: Use COPY --from=stage to copy files between stages [OK]

Common Mistakes:

• Forgetting --from=builder in COPY
• Assuming ENTRYPOINT syntax is wrong
• Thinking WORKDIR is required in second stage

5. You want to optimize a Spring Boot Dockerfile using multi-stage builds. Which approach best reduces the final image size while ensuring the app runs correctly?

hard

A. Build the app and run it in the same stage using a full Maven and JDK image.

B. Copy the entire source code and Maven cache to the final image for faster startup.

C. Use a Maven build stage to compile, then copy only the fat jar to a minimal JRE base image in the final stage.

D. Use multiple runtime stages with different JDK versions to support various environments.

Solution

1. Step 1: Understand multi-stage build optimization

   Building with Maven in one stage and copying only the final jar to a minimal runtime image reduces size.

2. Step 2: Evaluate options for best practice

   Use a Maven build stage to compile, then copy only the fat jar to a minimal JRE base image in the final stage. uses a build stage with Maven and a minimal JRE image for runtime, which is optimal.

3. Final Answer:

   Use a Maven build stage to compile, then copy only the fat jar to a minimal JRE base image in the final stage. -> Option C

4. Quick Check:

   Build then minimal runtime = smallest image [OK]

Hint: Build with Maven, run with minimal JRE for smallest image [OK]

Common Mistakes:

• Running build and runtime in one large image
• Copying unnecessary source code to final image
• Using multiple runtime stages unnecessarily