Introduction

Every Spring Boot application ships as a self-contained executable JAR. Out of the box, that JAR bundles everything: your application classes, every dependency, and the Spring Boot loader. It works, but it creates a problem for containerized deployments. When you push a new version, Docker downloads the entire fat JAR on every code change unless you structure things differently. Layer caching breaks. CI pipelines slow down. Production deployments drag.

JAR optimization is about structuring your application archive so that Docker can reuse unchanged layers. The three mainstream approaches are layered JARs, Cloud Native Buildpacks, and thin JARs. Each has distinct mechanics and different trade-offs.

Layered JARs

How Standard JAR Structure Breaks Cache Efficiency

A typical Spring Boot executable JAR is a flat archive. The BOOT-INF/lib/ directory holds all dependencies, BOOT-INF/classes/ holds your code, and org/springframework/boot/loader/ holds the loader. When Docker layers this JAR, the entire file becomes one layer. A one-line change to a configuration class is enough to invalidate that entire layer on the next push.

Layered JARs solve this by decomposing the archive into discrete, ordered layers and embedding a layers.idx index file that maps JAR entries to layer names. Docker then handles each layer independently.

Default Layers

Spring Boot’s layered JAR format defines four layers by default:

Layer	Contents	Change Frequency
dependencies	Stable third-party JARs from BOOT-INF/lib/	Rare
spring-boot-loader	The JAR launcher classes (JarLauncher, etc.)	Almost never
snapshot-dependencies	JARs with -SNAPSHOT versions	Frequent
application	Your compiled classes, resources, and metadata	Every code push

The ordering matters. Docker applies layers from bottom to top. When a higher layer changes, Docker re-pulls only that layer. Everything below stays cached.

Enabling Layered JAR with Maven

The Spring Boot Maven plugin handles layered JAR creation. Add the layers configuration to your pom.xml:

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <layers>
                        <enabled>true</enabled>
                        <!-- Optional: point to a custom layers.xml -->
                        <!-- <configuration>${project.basedir}/src/layers.xml</configuration> -->
                    </layers>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

With this enabled, running mvn package produces a JAR that includes the layers.idx file. Verify it was created:

unzip -q target/*.jar -d /tmp/boot-jar
cat /tmp/boot-jar/org/springframework/boot/loader/data/layers.idx

Defining Custom Layers

You can define a custom layers.xml file when you need finer control, such as separating internal module dependencies from external ones or handling libraries with specific runtime requirements.

<layers xmlns="http://www.springframework.org/schema/boot/layers"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/boot/layers
                            https://www.springframework.org/schema/boot/layers/layers-3.5.xsd">
    <application>
        <into layer="spring-boot-loader">
            <include>org/springframework/boot/loader/**</include>
        </into>
        <into layer="application" />
    </application>
    <dependencies>
        <into layer="application">
            <includeModuleDependencies />
        </into>
        <into layer="snapshot-dependencies">
            <include>*:*:*SNAPSHOT</include>
        </into>
        <into layer="dependencies" />
    </dependencies>
    <layerOrder>
        <layer>dependencies</layer>
        <layer>spring-boot-loader</layer>
        <layer>snapshot-dependencies</layer>
        <layer>application</layer>
    </layerOrder>
</layers>

Extracting and Rebuilding Layers in Docker

The recommended Docker pattern uses the Spring Boot jarmode tool to extract layers into separate build stages:

# Stage 1: Extract layers
FROM bellsoft/liberica-openjre-debian:24-cds AS builder
WORKDIR /builder
ARG JAR_FILE=target/*.jar
COPY ${JAR_FILE} application.jar
RUN java -Djarmode=tools -jar application.jar extract --layers --destination extracted

# Stage 2: Runtime image
FROM bellsoft/liberica-openjre-debian:24-cds
WORKDIR /application

# Each COPY creates its own Docker layer
COPY --from=builder /builder/extracted/dependencies/         ./
COPY --from=builder /builder/extracted/spring-boot-loader/   ./
COPY --from=builder /builder/extracted/snapshot-dependencies/ ./
COPY --from=builder /builder/extracted/application/           ./

ENTRYPOINT ["java", "-jar", "application.jar"]

Docker evaluates each COPY –from statement independently. If only your application layer changed, Docker re-pulls only that layer and reuses everything else. In large microservices portfolios, this can cut image push and pull times significantly.

Enabling Layered JAR with Gradle

Gradle users configure layered JARs through the bootJar task:

tasks.named("bootJar") {
    layered {
        application {
            intoLayer("spring-boot-loader") {
                include "org/springframework/boot/loader/**"
            }
            intoLayer("application")
        }
        dependencies {
            intoLayer("application") {
                includeProjectDependencies()
            }
            intoLayer("snapshot-dependencies") {
                include "*:*:*SNAPSHOT"
            }
            intoLayer("dependencies")
        }
        layerOrder = [
            "dependencies",
            "spring-boot-loader",
            "snapshot-dependencies",
            "application"
        ]
    }
}

Cloud Native Buildpacks

What Buildpacks Bring

Cloud Native Buildpacks take a different approach. Instead of manually authoring a Dockerfile and managing layer extraction yourself, a buildpack analyzes your application, produces optimal build artifacts, and constructs a container image following OCI standards. The result is an image that follows best practices without you having to become a Docker expert.

Spring Boot supports two buildpack ecosystems: the Paketo Java buildpacks and the Spring Boot Cloud Native Buildpacks. Paketo is the default for most use cases and produces images well-suited for Kubernetes environments.

Builder Layers

A buildpack builder image is composed of stacked buildpack layers and base images. The Paketo Java builder includes:

• Base OS layer: A minimal operating system (Debian or UBI)
• JVM layer: The Java runtime, automatically selected based on your application
• Buildpack layers: Individual buildpacks for tasks like dependency caching, classpath assembly, and application staging

When you run mvn spring-boot:build-image (or gradle bootBuildImage), the buildpack downloads dependencies, compiles your code if needed, and assembles the final image. The buildpack respects the layers.idx file, so any custom layer configurations you have are honored.

Configuration Options

Pass environment variables to the Paketo builder through the Maven plugin:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <image>
            <env>
                <!-- Set specific JVM version -->
                <BP_JVM_VERSION>17</BP_JVM_VERSION>
                <!-- Pass custom environment variables -->
                <SPRING_PROFILES_ACTIVE>prod</SPRING_PROFILES_ACTIVE>
            </env>
        </image>
    </configuration>
</plugin>

For network environments behind a proxy:

<configuration>
    <image>
        <env>
            <HTTP_PROXY>http://proxy.example.com:8080</HTTP_PROXY>
            <HTTPS_PROXY>https://proxy.example.com:8443</HTTPS_PROXY>
        </env>
    </configuration>
</configuration>

Rebasing

Buildpacks support rebasing. When the base image OS layer receives a security patch, you do not need to rebuild your application. The buildpack can swap only the OS layer, leaving your application layers untouched.

# After base image security update
mvn spring-boot:build-image -Pnative

The -Pnative profile triggers GraalVM native image compilation when configured, which is a separate optimization path entirely.

Paketo vs Spring Boot Buildpacks

Aspect	Paketo	Spring Boot Buildpack
Maintainer	VMware/Broadcom community	Spring Boot team
Customization	Extensive via environment variables	Opinionated, minimal config
Layer awareness	Respects layers.idx	Respects layers.idx
JVM auto-detection	Yes	Yes
Native image support	Via BP_NATIVE_IMAGE BUILD_PACKAGES	Via native profile

For most teams, Paketo is the sensible choice. Pick the Spring Boot buildpack when you want stricter opinionation and a smaller configuration surface.

Thin JARs

The Thin JAR Philosophy

Thin JARs go the opposite direction from layered JARs. Instead of embedding dependencies inside the JAR, a thin JAR contains only your application code and a reference to a dependencies directory or Maven repository. Dependencies are resolved and cached separately.

This makes the thin JAR small, often under 100 KB, which means fast uploads and minimal layer churn. The trade-off is that runtime dependency resolution becomes your problem to manage.

Maven Thin JAR Plugin

The spring-boot-thin-maven-plugin is the standard way to build thin JARs with Maven:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-thin-maven-plugin</artifactId>
    <configuration>
        <!-- Directory where dependencies are cached -->
        <outputDirectory>${project.build.directory}/thin-dependencies</outputDirectory>
        <properties>
            <!-- Resolve dependencies at build time -->
            <spring.boot.thin.cache.resolve>true</spring.boot.thin.cache.resolve>
        </properties>
    </configuration>
</plugin>

Run mvn package spring-boot-thin:resolve to create the thin JAR and download its dependencies:

mvn clean package spring-boot-thin:resolve
ls -lh target/*.jar target/thin-dependencies/

The thin JAR appears in target/ alongside a thin-dependencies/ directory containing all resolved JARs.

Gradle Thin JAR with Shadow Plugin

Gradle users typically combine the Shadow plugin with a custom task to get thin JAR behavior:

plugins {
    id 'com.github.johnrengelman.shadow' version '8.1.1'
    id 'org.springframework.boot' version '3.5.3'
}

tasks.named('bootJar') {
    archiveClassifier.set('thin')
    archiveFile.set(file("${buildDir}/libs/${baseName}-${version}-thin.jar"))
}

tasks.register('resolveDependencies') {
    doLast {
        // Download dependencies to local cache
        configurations.runtimeClasspath.resolvedConfiguration
            .resolvedArtifacts
            .each { artifact ->
                copy {
                    from artifact.file
                    into "${buildDir}/thin-dependencies"
                }
            }
    }
}

bootJar.dependsOn resolveDependencies

Runtime Dependency Resolution

When running a thin JAR, the thin launcher resolves dependencies from the configured location:

java -jar target/myapp-1.0.0-thin.jar \
    --spring.thin.properties.path=file:target/thin-dependencies/

For Docker deployments, copy both the thin JAR and the dependencies directory:

FROM eclipse-temurin:17-jre
WORKDIR /app
COPY target/myapp-1.0.0-thin.jar         /app/app.jar
COPY target/thin-dependencies/            /app/thin-dependencies/
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Storing Dependencies in a Maven Repository

For production environments, push dependencies to a Maven repository (Nexus, Artifactory, or even a folder served over HTTP) and configure the thin launcher to resolve from there:

java -Dthin.repo=https://nexus.example.com/repository/maven-releases \
     -jar myapp-1.0.0-thin.jar

This works well in Kubernetes deployments where a shared volume or init container pre-populates the dependency cache across pods.

When to Use / When NOT to Use

Decision Criteria

Use layered JARs when you have an existing Dockerfile and want incremental Docker layer caching without changing your current build process.

Use Cloud Native Buildpacks when you want a hands-off container image build, are deploying to Kubernetes or Cloud Foundry, and want rebasing for security patches without rebuilds.

Use thin JARs when you have a dependency management infrastructure already in place (Nexus, Artifactory) and want minimal JAR sizes for rapid artifact transfer.

Trade-off Table

Criterion	Layered JAR	Buildpacks	Thin JAR
JAR size	Full (~30-50 MB)	Full (~30-50 MB)	Tiny (<100 KB)
Docker cache efficiency	High (manual Dockerfile)	Very High (automatic)	High (with separate dependency layer)
Setup complexity	Medium	Low	Medium-High
Runtime dependency resolution	None (embedded)	None (embedded)	Required
Rebasing support	Manual	Automatic	Manual
Buildpack ecosystem	N/A	Paketo / Spring	N/A
GraalVM native support	Manual	Via BP_NATIVE_IMAGE	Manual
CI/CD integration	Dockerfile-based	Native (Maven/Gradle)	Maven/Gradle + repository
Kubernetes init container	Not needed	Not needed	Useful for pre-caching
Enterprise repo compatibility	Works with any registry	Works with any registry	Best with Nexus/Artifactory

Mermaid Diagram: Layered JAR Structure and Docker Cache

graph TD
    subgraph "Spring Boot JAR Contents"
        JAR[JAR File]
        JAR --> LAYERS_IDX[layers.idx]
        JAR --> LOADER[spring-boot-loader layer]
        JAR --> DEPS[dependencies layer]
        JAR --> SNAP[snapshot-dependencies layer]
        JAR --> APP[application layer]
    end

    subgraph "Docker Image Layers"
        IMG_BASE[Base OS Image]
        IMG_BASE --> IMG_DEPS[dependencies layer<br/>Cached: unchanged unless pom.xml changes]
        IMG_DEPS --> IMG_LOADER[spring-boot-loader layer<br/>Almost never changes]
        IMG_LOADER --> IMG_SNAP[snapshot-dependencies layer<br/>Invalidated on SNAPSHOT version change]
        IMG_SNAP --> IMG_APP[application layer<br/>Invalidated on every code change]
    end

    subgraph "Cache Invalidation Flow"
        CODE_CHANGE[Code Change] -->|Rebuild| REBUILD[Rebuild JAR]
        REBUILD --> REBUILD_APP[Re-extract application layer]
        REBUILD_APP -->|Only application layer changes| DOCKER[Docker pulls only application layer]
        DEPS_CHANGE[pom.xml Change] -->|Rebuild| REBUILD_DEPS[Re-extract dependencies + application layers]
        REBUILD_DEPS --> DOCKER_DEPS[Docker pulls dependencies + application layers]
    end

Implementation Snippets

Complete Maven Configuration for Layered JAR

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.3</version>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>spring-boot-jar-optimization</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <layers>
                        <enabled>true</enabled>
                    </layers>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Complete Gradle Configuration for Buildpack

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.5.3'
    id 'io.spring.dependency-management' version '1.1.7'
}

group = 'com.example'
version = '1.0.0'

java {
    sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}

tasks.named('bootJar') {
    layered {
        application {
            intoLayer("spring-boot-loader") {
                include "org/springframework/boot/loader/**"
            }
            intoLayer("application")
        }
        dependencies {
            intoLayer("application") {
                includeProjectDependencies()
            }
            intoLayer("snapshot-dependencies") {
                include "*:*:*SNAPSHOT"
            }
            intoLayer("dependencies")
        }
        layerOrder = [
            "dependencies",
            "spring-boot-loader",
            "snapshot-dependencies",
            "application"
        ]
    }
}

// Buildpack configuration
tasks.named('bootBuildImage') {
    imageName = "registry.example.com/${project.name}:${version}"
    env = [
        BP_JVM_VERSION: '17',
        SPRING_PROFILES_ACTIVE: 'prod'
    ]
}

Failure Scenarios

Layer Ordering Causing Full Rebuilds

If your layers.xml places stable dependencies above your application code in the layer order, a code-only change will still invalidate the dependency layer. This happens when the layer extraction script or XML configuration has an incorrect layerOrder definition. Always verify the layer order reflects actual change frequency, with the most stable layers at the bottom.

Missing Classes in Thin JAR

Thin JARs require all dependencies to be resolved and available at runtime. If a transitive dependency is not captured by the thin launcher and your application dynamically loads classes from it, you will see NoClassDefFoundError at runtime. Common culprits are JDBC drivers loaded via ServiceLoader, XML transformers registered via META-INF/services, and agents attached via -javaagent. Run integration tests against the thin JAR artifact before deploying to staging.

Buildpack Compatibility Issues

Not all buildpack versions support every Spring Boot version. If you see Buildpack lifecycle failed with exit code 1, check that your buildpack builder image version is compatible with your Spring Boot version. Using an outdated Paketo builder with Spring Boot 3.5 can cause failures during the dependency resolution phase.

Classpath Ordering Issues

The Spring Boot loader constructs the classpath in a specific order: dependencies, then snapshot-dependencies, then application. If your application or a library relies on classpath ordering for resource override behavior, layered JAR extraction can break those expectations. Use the layerOrder configuration to enforce the correct ordering and test resource loading behavior after switching.

Snapshot Dependencies in Wrong Layer

Placing SNAPSHOT dependencies in the application layer instead of snapshot-dependencies causes Docker to re-download them on every code push, even when your code has not changed. This defeats the entire point of layered caching. Verify that your layered configuration routes SNAPSHOT artifacts to their own layer.

Trade-off Summary

Aspect	Layered JAR	Buildpacks	Thin JAR
Docker layer reuse	High (manual control)	Very High (automatic analysis)	High (with separate dep layer)
Setup effort	One-time Dockerfile update	Minimal	Moderate (repo + plugin config)
Runtime complexity	None	None	Dependency resolution at startup
Cold start time	Fastest (all-in-one JAR)	Fast (optimized layers)	Slower (first-run resolution)
Image size	Full JAR size per image	Full JAR size per image	Tiny image + dependency cache
Security patching	Manual rebuild	Rebase (no rebuild)	Manual rebuild
Works offline	Yes	No (needs builder)	Only with pre-cached deps
GraalVM native	Manual	Via BP_NATIVE_IMAGE	Manual

Observability Checklist

Tracking your build and deployment metrics over time tells you whether the optimization is actually working:

• JAR size over time: Record the size of bootJar output in CI. A sudden increase signals dependency bloat.
• Build duration: Track mvn package or gradle build times. Layered extraction should not meaningfully increase build time.
• Docker image push time: Measure the time to push the image to your registry. A well-layered image with good cache hit rate should push in seconds, not minutes.
• Docker layer pull time: In Kubernetes logs or registry analytics, track how much data is pulled per deployment. A properly layered deployment transfers only the changed layers.
• Rebase frequency: If using buildpacks, track how often you rebase versus full rebuilds. Rebases are orders of magnitude faster.
• Thin JAR resolve time: For thin JARs, track how long dependency resolution takes on first deployment. Cache this aggressively in production.
• Cache hit ratio: Query your Docker registry for layer reuse statistics. Target above 80% for the dependency layer.

Security Notes

Layer scanning: Vulnerability scanners like Trivy and Grype can scan individual Docker layers. Because layered JARs expose layers separately, you can scan only the changed layer rather than the entire image. This speeds up security reviews and reduces scanner fatigue.

Dependency updates: Spring Boot’s dependency management tracks known vulnerable library versions. Keep your spring-boot-starter-parent version current. When a CVE hits a library you depend on, you rebuild only the dependencies layer, not the full image.

Base image updates: Buildpack rebasing means OS security patches reach your application without a code rebuild. Enable automatic base image updates in your CI pipeline for production deployments.

Thin JAR repository access: If your thin JAR resolves from a remote Maven repository, make sure that repository is network-accessible from your deployment environment and uses HTTPS. An air-gapped environment will fail at runtime.

Secrets in layers: Never bake secrets into Docker layers. The application layer should not contain credentials, API keys, or certificates. Use Kubernetes secrets or a secrets manager at runtime.

Common Pitfalls

Forgetting to rebase: When using buildpacks, the base OS image can receive security patches without triggering a layers.idx change. You must explicitly run a rebase operation to incorporate those patches into your deployed images.

Classpath ordering with layered extraction: The order in which layers are copied into the Docker image determines the runtime classpath order. If your application uses libraries with overlapping resource files, the layer order decides which one wins. Test resource loading behavior after switching to a layered approach.

Snapshot dependencies in the wrong layer: SNAPSHOT dependencies that end up in the application layer will cause Docker cache invalidation on every build, even when your code has not changed. Audit your layered JAR contents regularly.

Assuming Docker layer sharing works across registries: Docker layer sharing is registry-specific. An image pushed to Docker Hub does not share layers with the same image pushed to Google Artifact Registry. Pick a single registry for all environments to maximize layer reuse.

Ignoring thin JAR resolution time: On first deployment, a thin JAR must download all dependencies. If your registry or network has latency, this adds startup time. Pre-warm the dependency cache with an init container or build-time resolution.

Interview Questions

Further Reading

• Spring Boot Layered JAR Documentation
• Paketo Buildpacks Documentation
• Spring Boot Thin JAR Documentation
• Cloud Native Buildpacks Specification
• Docker Multi-stage Builds Guide

Conclusion

Spring Boot gives you three distinct paths to optimize how your application lands in Docker — layered JARs for teams with existing Dockerfiles, Cloud Native Buildpacks for hands-off image building with automatic rebasing, and thin JARs for minimal artifact sizes backed by a dependency repository. None of the three is universally best: layered JARs give you control without abandoning Docker, buildpacks eliminate Dockerfile maintenance entirely, and thin JARs minimize network transfer at the cost of runtime resolution complexity. The right choice depends on your CI/CD maturity, registry setup, and how much operational overhead your team is willing to take on.