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.