Multi-Stage Builds Optimization in Java: Complete Guide

Table of Contents

Introduction

Multi-stage Docker builds are a powerful technique for creating optimized, secure, and efficient Java application containers. By separating build dependencies from runtime environment, you can significantly reduce image size, improve security, and speed up deployment.

Architecture Overview

[Stage 1: Builder] → [Stage 2: Dependency Cache] → [Stage 3: Runtime] → [Final Image]
↓                    ↓                       ↓              ↓
JDK + Maven        Dependency Layers      JRE Only        Minimal Image
Source Code        Compiled Classes      Application     Security Hardened
Compilation        Test Execution        Optimized JVM   Production Ready

Step 1: Basic Multi-Stage Build

Standard Multi-Stage Dockerfile

Dockerfile

# Stage 1: Build stage
FROM eclipse-temurin:17-jdk-jammy as builder
WORKDIR /app
# Copy Maven wrapper and pom.xml
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Download dependencies (cached unless pom.xml changes)
RUN ./mvnw dependency:go-offline -B
# Copy source code
COPY src src
# Build the application (including tests)
RUN ./mvnw clean package -DskipTests
# Stage 2: Runtime stage
FROM eclipse-temurin:17-jre-jammy as runtime
WORKDIR /app
# Create non-root user for security
RUN groupadd -r appuser && useradd -r -g appuser appuser
# Copy JAR from builder stage
COPY --from=builder /app/target/*.jar app.jar
# Create necessary directories and set permissions
RUN mkdir -p /app/logs && chown -R appuser:appuser /app
# Switch to non-root user
USER appuser
# Expose port
EXPOSE 8080
# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8080/actuator/health || exit 1
# Run the application
ENTRYPOINT ["java", "-jar", "app.jar"]

Step 2: Advanced Multi-Stage Optimization

Optimized Multi-Stage with Layer Caching

Dockerfile.optimized

# Stage 1: Base build image with common dependencies
FROM eclipse-temurin:17-jdk-jammy as base
# Install necessary build tools
RUN apt-get update && apt-get install -y \
curl \
git \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Copy Maven wrapper and pom.xml first (for better caching)
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Download dependencies in separate layer (cached unless pom.xml changes)
RUN ./mvnw dependency:go-offline -B
# Stage 2: Test stage (optional - for CI/CD)
FROM base as tester
# Copy source code for testing
COPY src src
# Run tests
RUN ./mvnw test
# Stage 3: Package stage
FROM base as packager
# Copy source code
COPY src src
# Build the application without running tests
RUN ./mvnw clean package -DskipTests
# Extract layers for better Docker layer caching
RUN java -Djarmode=layertools -jar target/*.jar extract --destination target/extracted
# Stage 4: Production runtime
FROM eclipse-temurin:17-jre-jammy as production
# Install security updates and minimal runtime dependencies
RUN apt-get update && apt-get install -y \
curl \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Create non-root user
RUN groupadd -r appuser && useradd --no-log-init -r -g appuser appuser
WORKDIR /app
# Copy extracted layers from packager stage
COPY --from=packager /app/target/extracted/dependencies/ ./
COPY --from=packager /app/target/extracted/spring-boot-loader/ ./
COPY --from=packager /app/target/extracted/snapshot-dependencies/ ./
COPY --from=packager /app/target/extracted/application/ ./
# Create necessary directories and set permissions
RUN mkdir -p /app/logs /app/tmp && \
chown -R appuser:appuser /app
# Switch to non-root user
USER appuser
# Expose port
EXPOSE 8080
# Configure JVM for containers
ENV JAVA_OPTS="-XX:+UseContainerSupport -XX:MaxRAMPercentage=75.0 -Djava.security.egd=file:/dev/./urandom"
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
CMD curl -f http://localhost:8080/actuator/health || exit 1
# Use Spring Boot layered JAR approach
ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]

Step 3: JVM Optimization for Containers

JVM-Optimized Multi-Stage Build

Dockerfile.jvm-optimized

# Stage 1: Build with performance optimizations
FROM eclipse-temurin:17-jdk-jammy as builder
WORKDIR /app
# Copy build files
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Download dependencies
RUN ./mvnw dependency:go-offline -B
# Copy source
COPY src src
# Build with optimizations
RUN ./mvnw clean package -DskipTests \
-Dmaven.compiler.source=17 \
-Dmaven.compiler.target=17 \
-Dmaven.compiler.release=17
# Stage 2: JLink custom runtime (minimal JRE)
FROM eclipse-temurin:17-jdk-jammy as jlink
WORKDIR /app
# Copy JAR from builder
COPY --from=builder /app/target/*.jar app.jar
# Create custom JRE with only required modules
RUN jdeps --ignore-missing-deps \
--multi-release 17 \
--print-module-deps \
--class-path 'app.jar' \
app.jar > jre-modules.txt
# Create minimal JRE
RUN jlink --verbose \
--add-modules $(cat jre-modules.txt),jdk.unsupported \
--strip-debug \
--no-man-pages \
--no-header-files \
--compress=2 \
--output /custom-jre
# Stage 3: Final production image
FROM debian:bookworm-slim
# Install minimal security updates
RUN apt-get update && \
apt-get upgrade -y && \
apt-get install -y --no-install-recommends \
ca-certificates \
curl \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Create app user
RUN groupadd -r appuser && useradd -r -g appuser appuser
WORKDIR /app
# Copy custom JRE from jlink stage
COPY --from=jlink /custom-jre /opt/java
# Copy application from builder stage
COPY --from=builder /app/target/*.jar app.jar
# Set Java home
ENV JAVA_HOME=/opt/java
ENV PATH="${JAVA_HOME}/bin:${PATH}"
# Create necessary directories
RUN mkdir -p /app/logs /app/tmp && \
chown -R appuser:appuser /app
USER appuser
EXPOSE 8080
# Optimized JVM options for containers
ENV JAVA_OPTS="-XX:+UseContainerSupport \
-XX:MaxRAMPercentage=75.0 \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:ParallelGCThreads=2 \
-XX:ConcGCThreads=2 \
-Djava.security.egd=file:/dev/./urandom \
-Dspring.jmx.enabled=false"
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

Step 4: Spring Boot Specific Optimizations

Spring Boot Layered JAR Optimization

Dockerfile.spring-layered

# Stage 1: Build with Spring Boot layers
FROM eclipse-temurin:17-jdk-jammy as builder
WORKDIR /app
# Copy build configuration
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Resolve dependencies
RUN ./mvnw dependency:go-offline -B
# Copy source code
COPY src src
# Build with layered JAR support
RUN ./mvnw clean package -DskipTests \
-Dspring-boot.repackage.layeredArtifact=true
# Extract layers for optimized Docker caching
RUN java -Djarmode=layertools -jar target/*.jar extract --destination target/extracted
# Stage 2: Production runtime
FROM eclipse-temurin:17-jre-jammy
# Install security updates
RUN apt-get update && \
apt-get upgrade -y && \
apt-get install -y --no-install-recommends \
curl \
&& apt-get clean \
&& rm -rf /var/lib/apt/lists/*
# Create app user
RUN groupadd -r appuser && useradd -r -g appuser appuser
WORKDIR /app
# Copy layers in optimized order (least changing first)
COPY --from=builder /app/target/extracted/dependencies/ ./
COPY --from=builder /app/target/extracted/spring-boot-loader/ ./
COPY --from=builder /app/target/extracted/snapshot-dependencies/ ./
COPY --from=builder /app/target/extracted/application/ ./
# Create directories and set permissions
RUN mkdir -p /app/logs /app/tmp && \
chown -R appuser:appuser /app
USER appuser
EXPOSE 8080
# Spring Boot specific optimizations
ENV SPRING_OUTPUT_ANSI_ENABLED=NEVER
ENV JAVA_OPTS="-XX:+UseContainerSupport \
-XX:MaxRAMPercentage=75.0 \
-Xss256k \
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-Djava.awt.headless=true \
-Djava.security.egd=file:/dev/./urandom \
-Dspring.backgroundpreinitializer.ignore=true"
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
CMD curl -f http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]

Maven Configuration for Layered JARs

pom.xml with Spring Boot Maven Plugin

<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<layers>
<enabled>true</enabled>
</layers>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
<!-- Maven Compiler Plugin -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<release>17</release>
<parameters>true</parameters>
<optimize>true</optimize>
</configuration>
</plugin>
<!-- Maven Resources Plugin with filtering -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>3.3.1</version>
<configuration>
<delimiters>
<delimiter>@</delimiter>
</delimiters>
<useDefaultDelimiters>false</useDefaultDelimiters>
</configuration>
</plugin>
</plugins>
</build>

Step 5: GraalVM Native Image Build

Native Image Multi-Stage Build

Dockerfile.native

# Stage 1: Build native image
FROM ghcr.io/graalvm/native-image:17-ol9 as native-builder
WORKDIR /app
# Install build dependencies
RUN microdnf update -y && \
microdnf install -y \
maven \
git \
&& microdnf clean all
# Copy source code
COPY . .
# Build native image
RUN mvn clean package -DskipTests -Pnative
# Stage 2: Minimal runtime for native executable
FROM redhat/ubi9-micro
# Install CA certificates and basic security
RUN microdnf update -y && \
microdnf install -y \
ca-certificates \
curl \
&& microdnf clean all
# Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser
WORKDIR /app
# Copy native executable from builder
COPY --from=native-builder /app/target/*-runner /app/application
# Create necessary directories
RUN mkdir -p /app/logs /app/tmp && \
chown -R appuser:appuser /app
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
CMD curl -f http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["/app/application"]

Maven Profile for Native Image

pom.xml with Native Profile

<profiles>
<profile>
<id>native</id>
<properties>
<packaging>native</packaging>
</properties>
<dependencies>
<dependency>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>0.9.28</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.graalvm.buildtools</groupId>
<artifactId>native-maven-plugin</artifactId>
<version>0.9.28</version>
<executions>
<execution>
<id>build-native</id>
<goals>
<goal>compile-no-fork</goal>
</goals>
<phase>package</phase>
</execution>
</executions>
<configuration>
<imageName>${project.artifactId}</imageName>
<mainClass>${start-class}</mainClass>
<buildArgs>
<buildArg>--enable-url-protocols=http,https</buildArg>
<buildArg>--initialize-at-build-time=org.slf4j.MDC</buildArg>
<buildArg>-H:+ReportExceptionStackTraces</buildArg>
</buildArgs>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>

Step 6: Security-Hardened Multi-Stage Build

Security-Focused Multi-Stage Build

Dockerfile.secure

# Stage 1: Build with security scanning
FROM eclipse-temurin:17-jdk-jammy as builder
# Install security scanner
RUN apt-get update && apt-get install -y \
curl \
&& curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh -s -- -b /usr/local/bin
WORKDIR /app
# Copy build files
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Download dependencies and scan for vulnerabilities
RUN ./mvnw dependency:go-offline -B && \
trivy filesystem --exit-code 1 --severity HIGH,CRITICAL /root/.m2/repository
# Copy source code
COPY src src
# Build application
RUN ./mvnw clean package -DskipTests
# Stage 2: Security-hardened runtime
FROM gcr.io/distroless/java17:nonroot
WORKDIR /app
# Copy JAR from builder stage
COPY --from=builder /app/target/*.jar app.jar
# Use the nonroot user provided by distroless (uid: 65532)
USER nonroot
EXPOSE 8080
# Security-focused JVM options
ENV JAVA_OPTS="-XX:+UseContainerSupport \
-XX:MaxRAMPercentage=75.0 \
-Djava.security.egd=file:/dev/./urandom \
-Djava.awt.headless=true \
-Dfile.encoding=UTF-8"
ENTRYPOINT ["java", "-jar", "app.jar"]

Alternative: Alpine-based Secure Build

Dockerfile.alpine-secure

# Stage 1: Build stage
FROM eclipse-temurin:17-jdk-alpine as builder
WORKDIR /app
# Install necessary tools
RUN apk add --no-cache \
curl \
maven
# Copy build files
COPY pom.xml .
COPY mvnw .
COPY .mvn .mvn
# Download dependencies
RUN ./mvnw dependency:go-offline -B
# Copy source code
COPY src src
# Build application
RUN ./mvnw clean package -DskipTests
# Stage 2: Production stage with Alpine JRE
FROM eclipse-temurin:17-jre-alpine
# Security hardening
RUN apk add --no-cache \
curl \
&& addgroup -S appuser && adduser -S appuser -G appuser \
&& rm -rf /var/cache/apk/*
WORKDIR /app
# Copy JAR from builder
COPY --from=builder /app/target/*.jar app.jar
# Create necessary directories
RUN mkdir -p /app/logs /app/tmp && \
chown -R appuser:appuser /app
USER appuser
EXPOSE 8080
# Alpine-specific JVM optimizations
ENV JAVA_OPTS="-XX:+UseContainerSupport \
-XX:MaxRAMPercentage=75.0 \
-Xss256k \
-Djava.security.egd=file:/dev/./urandom"
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:8080/actuator/health || exit 1
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

Step 7: Development vs Production Builds

Development Multi-Stage Build

Dockerfile.dev

# Stage 1: Development build with hot reload
FROM eclipse-temurin:17-jdk-jammy as development
WORKDIR /app
# Install additional development tools
RUN apt-get update && apt-get install -y \
curl \
vim \
git \
&& rm -rf /var/lib/apt/lists/*
# Copy Maven wrapper and pom.xml
COPY mvnw .
COPY .mvn .mvn
COPY pom.xml .
# Download dependencies (cached layer)
RUN ./mvnw dependency:go-offline -B
# Copy source code
COPY src src
# Expose debug port
EXPOSE 8080 5005
# Development-specific JVM options
ENV JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"
# Run with hot reload for development
CMD ["./mvnw", "spring-boot:run", "-Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"]
# Stage 2: Production build from same source
FROM development as production-builder
# Build production JAR
RUN ./mvnw clean package -DskipTests
# Stage 3: Production runtime
FROM eclipse-temurin:17-jre-jammy as production
WORKDIR /app
# Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser
# Copy JAR from builder
COPY --from=production-builder /app/target/*.jar app.jar
# Set up directories and permissions
RUN mkdir -p /app/logs && chown -R appuser:appuser /app
USER appuser
EXPOSE 8080
# Production JVM options
ENV JAVA_OPTS="-XX:+UseContainerSupport -Djava.security.egd=file:/dev/./urandom"
ENTRYPOINT ["java", "-jar", "app.jar"]

Step 8: Build Arguments and Customization

Configurable Multi-Stage Build

Dockerfile.configurable

# Build arguments for customization
ARG JAVA_VERSION=17
ARG MAVEN_VERSION=3.9.5
ARG APP_PORT=8080
# Stage 1: Configurable builder
FROM eclipse-temurin:${JAVA_VERSION}-jdk-jammy as builder
ARG MAVEN_VERSION
ARG BUILD_NUMBER=1
# Install specific Maven version
RUN apt-get update && apt-get install -y \
curl \
&& curl -fsSL https://archive.apache.org/dist/maven/maven-3/${MAVEN_VERSION}/binaries/apache-maven-${MAVEN_VERSION}-bin.tar.gz \
| tar xzf - -C /opt \
&& ln -s /opt/apache-maven-${MAVEN_VERSION} /opt/maven
ENV PATH="/opt/maven/bin:${PATH}"
WORKDIR /app
# Copy build files
COPY pom.xml .
COPY mvnw .
COPY .mvn .mvn
# Download dependencies
RUN mvn dependency:go-offline -B
# Copy source code
COPY src src
# Build with build number
RUN mvn clean package -DskipTests -Dbuild.number=${BUILD_NUMBER}
# Stage 2: Configurable runtime
FROM eclipse-temurin:${JAVA_VERSION}-jre-jammy
ARG APP_PORT
ARG APP_USER=appuser
# Create user
RUN groupadd -r ${APP_USER} && useradd -r -g ${APP_USER} ${APP_USER}
WORKDIR /app
# Copy application
COPY --from=builder /app/target/*.jar app.jar
# Set up directories
RUN mkdir -p /app/logs && chown -R ${APP_USER}:${APP_USER} /app
USER ${APP_USER}
EXPOSE ${APP_PORT}
ENV JAVA_OPTS="-XX:+UseContainerSupport -Djava.security.egd=file:/dev/./urandom"
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
CMD curl -f http://localhost:${APP_PORT}/actuator/health || exit 1
ENTRYPOINT ["java", "-jar", "app.jar"]

Build Script with Arguments

build.sh

#!/bin/bash
# Build configuration
JAVA_VERSION=${1:-17}
MAVEN_VERSION=${2:-3.9.5}
APP_PORT=${3:-8080}
BUILD_NUMBER=${4:-$(date +%s)}
echo "Building with:"
echo "  Java: ${JAVA_VERSION}"
echo "  Maven: ${MAVEN_VERSION}"
echo "  Port: ${APP_PORT}"
echo "  Build: ${BUILD_NUMBER}"
docker build \
--build-arg JAVA_VERSION=${JAVA_VERSION} \
--build-arg MAVEN_VERSION=${MAVEN_VERSION} \
--build-arg APP_PORT=${APP_PORT} \
--build-arg BUILD_NUMBER=${BUILD_NUMBER} \
-t myapp:${BUILD_NUMBER} \
-f Dockerfile.configurable .
# Tag for different environments
docker tag myapp:${BUILD_NUMBER} myapp:latest
docker tag myapp:${BUILD_NUMBER} myapp:java${JAVA_VERSION}

Step 9: Docker Compose for Multi-Stage Testing

Development and Testing Setup

docker-compose.yml

version: '3.8'
services:
# Development build with hot reload
app-dev:
build:
context: .
dockerfile: Dockerfile.dev
target: development
ports:
- "8080:8080"
- "5005:5005"
volumes:
- .:/app
- maven-repo:/root/.m2
environment:
- SPRING_PROFILES_ACTIVE=dev
command: ["./mvnw", "spring-boot:run"]
# Production build test
app-prod:
build:
context: .
dockerfile: Dockerfile.optimized
target: production
ports:
- "8081:8080"
environment:
- SPRING_PROFILES_ACTIVE=prod
depends_on:
- postgres
# Database for testing
postgres:
image: postgres:15-alpine
environment:
POSTGRES_DB: myapp
POSTGRES_USER: appuser
POSTGRES_PASSWORD: secret
ports:
- "5432:5432"
volumes:
maven-repo:

Multi-Architecture Build Script

build-multi-arch.sh

#!/bin/bash
# Multi-architecture build script
VERSION=${1:-latest}
PLATFORMS="linux/amd64,linux/arm64"
echo "Building multi-architecture image for version: $VERSION"
# Create builder instance
docker buildx create --name multiarch-builder --use
# Build for multiple platforms
docker buildx build \
--platform ${PLATFORMS} \
-t mycompany/myapp:${VERSION} \
-t mycompany/myapp:latest \
--push \
.
# Inspect the built image
docker buildx imagetools inspect mycompany/myapp:${VERSION}

Performance Comparison

Build Size Comparison

Build Type	Image Size	Startup Time	Security	Use Case
Standard	~300MB	~3-5s	Medium	General purpose
Optimized	~150MB	~2-3s	High	Production
JLink Minimal	~80MB	~1-2s	High	Resource-constrained
Native Image	~50MB	~0.1s	High	Performance-critical
Distroless	~60MB	~2s	Very High	Security-focused

Build Time Optimization

# ❌ Bad - No layer caching
COPY . .
RUN mvn clean package
# ✅ Good - Optimal layer caching
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src src
RUN mvn clean package

Best Practices

1. Layer Caching Optimization

Copy pom.xml first for dependency caching
Separate dependency download from source compilation
Use .dockerignore to exclude unnecessary files

2. Security Hardening

Use minimal base images (distroless, Alpine)
Run as non-root user
Regular security updates
Vulnerability scanning in CI/CD

3. JVM Optimization

Use container-aware JVM options
Set appropriate memory limits
Choose optimal garbage collector
Enable container support

4. Build Performance

Use buildkit features
Parallelize independent operations
Cache dependencies appropriately
Use multi-stage builds effectively

5. Monitoring & Debugging

Include health checks
Proper logging configuration
JMX/actuator endpoints
Debug capabilities in development

Conclusion

Multi-stage Docker builds provide significant benefits for Java applications:

Reduced Image Size: From ~300MB to ~50MB with optimizations
Improved Security: Minimal attack surface with distroless images
Faster Deployment: Smaller images deploy quicker
Better Caching: Optimized layer caching for faster builds
Production Readiness: Security-hardened, optimized runtime

By implementing these multi-stage build strategies, you can create Java applications that are secure, efficient, and optimized for modern containerized environments.