Why split the build and runtime into two stages?

The build stage needs the full JDK plus Maven or Gradle to compile and package the jar, which is large. The runtime stage only needs a JRE to run the jar, so copying just the built jar into a slim JRE image produces a much smaller and more secure final image.

Why does the build cache dependencies separately?

Copying pom.xml (or the Gradle build files) and resolving dependencies before copying your source means Docker caches that layer. As long as your dependencies do not change, rebuilds reuse the cache and skip the slow download step.

What does the Actuator HEALTHCHECK do?

It calls the /actuator/health endpoint and checks the response contains UP. Docker and orchestrators like Kubernetes use this to know when the container is ready and to restart it if it becomes unhealthy. It requires the spring-boot-starter-actuator dependency in your project.

Why run the container as a non-root user?

Running as root means any process escape inside the container has root over the container filesystem and mounted volumes. Creating a dedicated unprivileged user and switching to it with USER follows least privilege and satisfies most container security scanners.

What does MaxRAMPercentage do?

MaxRAMPercentage tells the JVM to size its heap as a fraction of the container memory limit rather than the host's total memory. Setting it to 75 percent lets the JVM use most of the container's allocation while leaving headroom for metaspace and native memory.

Dockerfile Builder for Java Spring Boot

A Dockerfile builder for Spring Boot that produces a clean multi-stage Dockerfile for Java microservices. You choose Maven or Gradle, a JDK, a port, and whether to wire in an Actuator health check, and it emits a build that compiles your jar in one image and runs it in a slim JRE image as a non-root user.

How it works

The build stage uses a full image that contains both the JDK and your build tool. For Maven it runs mvn dependency:go-offline after copying only pom.xml, so dependency resolution is cached as its own layer, then runs mvn package -DskipTests. For Gradle it resolves dependencies, then runs bootJar. Either way the resulting fat jar is copied to a predictable path, app.jar.

The runtime stage starts from eclipse-temurin:<jdk>-jre-alpine — a slim image with only the Java runtime. It creates a dedicated spring user, copies the jar with the right ownership, switches to that user with USER, and starts the app with MaxRAMPercentage so the JVM sizes its heap against the container limit. When enabled, the HEALTHCHECK polls /actuator/health and looks for the UP status.

Tips and notes

Tests are skipped in the image build (-DskipTests / -x test) on purpose — run your test suite in CI before building the image, not inside the container build.
For even faster startup and smaller images you can extract the Spring Boot layered jar with java -Djarmode=layertools -jar app.jar extract; this builder keeps the simpler single-jar form, which is correct for the vast majority of services.
Always pin an LTS JDK (21, 17, or 11) so your runtime matches what you tested against.
Make sure spring-boot-starter-actuator is on the classpath and management.endpoint.health.probes.enabled=true is set before relying on the health check.

Dockerfile Builder for Java Spring Boot

Email me this result

How it works

Tips and notes