Container and Native Deployment

Choose JVM or native from measured startup, memory, throughput, and build constraints.

Container image

• Prefer the Spring Boot build-image task with Cloud Native Buildpacks for standard services.
• Keep dependency and application layers separate to maximize cache reuse.
• Pin builder and run-image families in reproducible release pipelines.
• Run as a non-root user on a read-only filesystem where the application permits it.
• Supply secrets at runtime; never bake credentials or environment files into an image.
• Configure graceful shutdown and align platform termination grace with application timeouts.

Runtime behavior

• Set memory and CPU limits, then verify JVM ergonomics inside those limits.
• Expose dedicated readiness and liveness probes through Actuator.
• Keep startup probes for slow initialization instead of weakening liveness.
• Write temporary files only under an explicit writable location.

Native image

• Use Spring AOT and the supported GraalVM native build tools.
• Add RuntimeHints for reflection, resources, serialization, or proxies that analysis cannot infer.
• Avoid runtime bean-shape changes and other closed-world violations.
• Run native integration tests; a successful JVM test suite is not sufficient.

Supply chain

• Generate an SBOM, scan the final image, and patch builder/run images regularly.
• Use immutable image digests for promotion between environments.

Examples

• See examples/good-dockerfile and examples/bad-dockerfile.

The good example targets Boot 3.3+ and uses jarmode=tools extraction in a builder stage. For Boot 3.0-3.2, use the older -Djarmode=layertools ... extract command. A normal Maven package does not create target/dependencies/ or target/application/ directories by itself.

Official sources

• Container images: https://docs.spring.io/spring-boot/reference/packaging/container-images/
• Dockerfiles and layer extraction: https://docs.spring.io/spring-boot/reference/packaging/container-images/dockerfiles.html
• Boot 3.3 tools jarmode: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.3-Release-Notes#cds-support

Gotchas

• Agent copies one fat jar into a mutable root container - use layers and a non-root runtime.
• Agent bakes secrets into image layers - inject secrets only at runtime.
• Agent adds broad reflection configuration to make native builds pass - register narrow runtime hints.
• Agent uses liveness to test every dependency - use readiness for traffic-affecting dependencies.
• Agent chooses native without measuring throughput and build cost - benchmark both deployment modes.
• Agent copies nonexistent target/dependencies directories - extract the packaged jar in a builder stage.
• Agent uses jarmode=tools on Boot 3.0-3.2 - use layertools until the project reaches Boot 3.3.