Java container image best practices with Docker
Help teams build secure, reproducible, and maintainable Docker container images for Java applications without coupling the guidance to Spring Boot, Quarkus, or Micronaut.
What is covered in this Skill?
- Dockerfile structure for Java applications: multi-stage builds, Maven dependency caching, deterministic artifact copies,
jlink custom runtimes, and .dockerignore
- Runtime image selection: micro distributions such as Alpaquita, minimal JRE images, pinned versions or digests where appropriate, image labels, and explicit entrypoints
- JVM container ergonomics: memory percentage flags, startup behavior, graceful shutdown signals, time zones, and predictable runtime options
- Security defaults: non-root users, least privilege, no secrets in layers, reduced package managers, vulnerability scanning, SBOM awareness, and avoiding privileged containers
- Operational readiness: health checks when suitable, stdout/stderr logging, port declaration, image size control, build reproducibility, and CI verification
Scope: Framework-agnostic Docker and container-image quality for Java projects. For framework runtime wiring, defer to the matching Spring Boot, Quarkus, or Micronaut skill. For Testcontainers-based tests, defer to the relevant testing skill.
Constraints
Keep recommendations at the Dockerfile, image-build, and runtime-container layer unless the user explicitly asks for framework-specific configuration. After editing this repository's XML sources, regenerate skills and verify the build.
- MANDATORY: Run
./mvnw compile or mvn compile before proposing Java or Maven changes in the same change set
- SECRETS: Never bake credentials, tokens, private keys, Maven settings with secrets, or environment-specific secrets into image layers, labels, arguments, or logs
- SECURITY: Prefer non-root execution, least-privilege filesystem permissions, micro runtime images, and explicit container capabilities over privileged defaults
- JLINK: Prefer
jlink custom runtimes for production images when the module graph is known, validated at runtime, and compatible with the application's dependencies
- REPRODUCIBILITY: Pin base image versions intentionally, document digest trade-offs, keep build inputs explicit, and avoid network-dependent runtime startup steps
- JVM: Account for container memory and CPU limits with JVM flags, graceful shutdown behavior, and observable startup failures before claiming production readiness
- BOUNDARIES: Defer Spring Boot runtime behavior to
@301-frameworks-spring-boot-core, Quarkus runtime behavior to @401-frameworks-quarkus-core, Micronaut runtime behavior to @501-frameworks-micronaut-core, and Testcontainers setup to the matching testing skill
- MANDATORY: Regenerate skills with
./mvnw clean install -pl skills-generator after editing skill or system-prompt XML in this repo
- VERIFY: Run
./mvnw clean verify or mvn clean verify before promoting changes
- EDGE CASE: If the target Java version, build tool, deployment platform, base-image policy, registry policy, or security scanner is missing and affects the recommendation, ask a clarifying question before editing container artifacts
- EDGE CASE: If requested changes conflict with security policy, image provenance, air-gapped builds, or runtime platform constraints, explain the trade-off and ask for confirmation
When to use this skill
- Review Java Dockerfile
- Improve Docker image security
- Add jlink runtime to a Java container
- Add containerization to a Java project
- Optimize Java container image size
- Review Docker build reproducibility
Workflow
- Read reference and assess container context
Read references/706-technologies-containers-docker.md and inspect current Dockerfiles, .dockerignore, Maven build inputs, image build scripts, CI jobs, registry policy, and deployment constraints before proposing changes.
- Identify runtime and supply-chain constraints
Confirm Java version, build tool, jlink module requirements, micro distro compatibility, target platform, base-image policy, registry requirements, vulnerability scanner, SBOM expectations, memory limits, exposed ports, and operational readiness needs.
- Apply container-aligned changes
Implement or refactor Docker and container build artifacts following the reference patterns and project conventions, keeping framework-specific runtime behavior out of scope unless explicitly requested.
- Run verification and report results
Execute appropriate build, image build, scan, smoke-test, and generator checks; summarize what changed, what was verified, and any remaining container risks.
Reference
For detailed guidance, examples, and constraints, see references/706-technologies-containers-docker.md.
1---2name: 706-technologies-containers-docker3description: Use when you need framework-agnostic Docker and container image guidance for Java projects - Dockerfile design, multi-stage Maven builds, jlink custom runtimes, micro runtime distributions such as Alpaquita, JVM container ergonomics, non-root execution, image metadata, .dockerignore, reproducible builds, vulnerability scanning, SBOM awareness, and production-safe container defaults. This should trigger for requests such as Review Java Dockerfile; Improve Docker image security; Add jlink runtime to a Java container; Add containerization to a Java project; Optimize Java container image size; Review Docker build reproducibility. Part of cursor-rules-java project4license: Apache-2.05---6# Java container image best practices with Docker
7
8Help teams build secure, reproducible, and maintainable **Docker container images** for Java applications without coupling the guidance to Spring Boot, Quarkus, or Micronaut.
9
10**What is covered in this Skill?**
11
12- Dockerfile structure for Java applications: multi-stage builds, Maven dependency caching, deterministic artifact copies, `jlink` custom runtimes, and `.dockerignore`
13- Runtime image selection: micro distributions such as Alpaquita, minimal JRE images, pinned versions or digests where appropriate, image labels, and explicit entrypoints
14- JVM container ergonomics: memory percentage flags, startup behavior, graceful shutdown signals, time zones, and predictable runtime options
15- Security defaults: non-root users, least privilege, no secrets in layers, reduced package managers, vulnerability scanning, SBOM awareness, and avoiding privileged containers
16- Operational readiness: health checks when suitable, stdout/stderr logging, port declaration, image size control, build reproducibility, and CI verification
17
18**Scope:** Framework-agnostic Docker and container-image quality for Java projects. For framework runtime wiring, defer to the matching Spring Boot, Quarkus, or Micronaut skill. For Testcontainers-based tests, defer to the relevant testing skill.
19
20## Constraints
21
22Keep recommendations at the Dockerfile, image-build, and runtime-container layer unless the user explicitly asks for framework-specific configuration. After editing this repository's XML sources, regenerate skills and verify the build.
23
24- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before proposing Java or Maven changes in the same change set
25- **SECRETS**: Never bake credentials, tokens, private keys, Maven settings with secrets, or environment-specific secrets into image layers, labels, arguments, or logs
26- **SECURITY**: Prefer non-root execution, least-privilege filesystem permissions, micro runtime images, and explicit container capabilities over privileged defaults
27- **JLINK**: Prefer `jlink` custom runtimes for production images when the module graph is known, validated at runtime, and compatible with the application's dependencies
28- **REPRODUCIBILITY**: Pin base image versions intentionally, document digest trade-offs, keep build inputs explicit, and avoid network-dependent runtime startup steps
29- **JVM**: Account for container memory and CPU limits with JVM flags, graceful shutdown behavior, and observable startup failures before claiming production readiness
30- **BOUNDARIES**: Defer Spring Boot runtime behavior to `@301-frameworks-spring-boot-core`, Quarkus runtime behavior to `@401-frameworks-quarkus-core`, Micronaut runtime behavior to `@501-frameworks-micronaut-core`, and Testcontainers setup to the matching testing skill
31- **MANDATORY**: Regenerate skills with `./mvnw clean install -pl skills-generator` after editing skill or system-prompt XML in this repo
32- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` before promoting changes
33- **EDGE CASE**: If the target Java version, build tool, deployment platform, base-image policy, registry policy, or security scanner is missing and affects the recommendation, ask a clarifying question before editing container artifacts
34- **EDGE CASE**: If requested changes conflict with security policy, image provenance, air-gapped builds, or runtime platform constraints, explain the trade-off and ask for confirmation
35
36## When to use this skill
37
38- Review Java Dockerfile
39- Improve Docker image security
40- Add jlink runtime to a Java container
41- Add containerization to a Java project
42- Optimize Java container image size
43- Review Docker build reproducibility
44
45## Workflow
46
471. **Read reference and assess container context**
48
49Read `references/706-technologies-containers-docker.md` and inspect current Dockerfiles, `.dockerignore`, Maven build inputs, image build scripts, CI jobs, registry policy, and deployment constraints before proposing changes.
50
512. **Identify runtime and supply-chain constraints**
52
53Confirm Java version, build tool, `jlink` module requirements, micro distro compatibility, target platform, base-image policy, registry requirements, vulnerability scanner, SBOM expectations, memory limits, exposed ports, and operational readiness needs.
54
553. **Apply container-aligned changes**
56
57Implement or refactor Docker and container build artifacts following the reference patterns and project conventions, keeping framework-specific runtime behavior out of scope unless explicitly requested.
58
594. **Run verification and report results**
60
61Execute appropriate build, image build, scan, smoke-test, and generator checks; summarize what changed, what was verified, and any remaining container risks.
62
63## Reference
64
65For detailed guidance, examples, and constraints, see [references/706-technologies-containers-docker.md](references/706-technologies-containers-docker.md).
majiayu000