Skip to content

rrezartprebreza/spring-boot-skills / skills/spring-boot-3/container-native-deployment

container-native-deployment

Verified

Use when packaging a Spring Boot 3 application as an OCI image or GraalVM native executable. Covers buildpacks, layered images, JVM containers, AOT hints, probes, security, and verification.

FileKindSize
SKILL.mdskill md3.9 KB
agents/openai.yamlconfig221 B
examples/bad-dockerfileother154 B
examples/good-dockerfileother619 B
---
name: container-native-deployment
description: >
  Use when packaging a Spring Boot 3 application as an OCI image or GraalVM native executable.
  Covers buildpacks, layered images, JVM containers, AOT hints, probes, security, and verification.
---

# 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.

Scan the actual final image by immutable digest, including OS packages and bundled Java
dependencies; record the scanner database timestamp and findings that need manual triage.
Verify signatures against the expected signer identity and issuer or trusted key, and check
that provenance refers to the intended source commit and build workflow. A signature from
an arbitrary identity is not a release policy. Retain SBOM/provenance evidence for the promoted
digest; rebuilding the same tag produces a different artifact and requires new verification.
Test untrusted-signer and digest-mismatch rejection before enforcing a deployment policy.
For dependency/BOM remediation and CI trust-boundary review, use java-supply-chain-security
if installed; this skill remains responsible for image construction and runtime behavior.

## 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.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall