Docker for Java Applications

An image is an immutable, read-only stack of filesystem layers plus metadata (entrypoint, env, ports). Each Dockerfile instruction that changes the filesystem (RUN, COPY, ADD) creates a layer identified by a content hash; a container adds a thin writable layer on top.

• Layers are shared between images and cached by the builder: if an instruction and everything before it is unchanged, the cached layer is reused.
• Once a layer is invalidated, all layers after it are rebuilt.
• Deleting a file in a later layer does not shrink the image; the bytes still exist in the earlier layer.

ENTRYPOINT defines the executable; CMD supplies default arguments (or the default command if no entrypoint). Exec form (["java","-jar","app.jar"]) runs the process directly as PID 1; shell form (java -jar app.jar) wraps it in /bin/sh -c, so the shell is PID 1.

ENTRYPOINT ["java", "-jar", "/app/app.jar"]
CMD ["--spring.profiles.active=prod"]

• docker run image --foo replaces CMD only; --entrypoint overrides the entrypoint.
• In shell form, SIGTERM goes to sh, which usually does not forward it to Java, so graceful shutdown breaks.
• Shell form does not expand variables in exec form; use sh -c explicitly or JAVA_TOOL_OPTIONS when you need env expansion.

Order instructions from least to most frequently changing, keep the image small, run as non-root and pin versions.

• Copy dependency descriptors first, resolve dependencies, then copy source, so dependency layers stay cached.
• Use a .dockerignore (target/, .git, *.md, IDE files) to shrink build context and avoid cache busting.
• Pin base images by version (ideally digest), not latest.
• Combine related RUN commands, clean package caches in the same layer.
• Use exec-form ENTRYPOINT, a non-root USER, and HEALTHCHECK/probes.
• Never bake secrets into layers (ARG/ENV values are visible in docker history); use BuildKit --mount=type=secret.

A multi-stage Dockerfile uses several FROM stages; later stages COPY --from= only the artifacts they need. The build stage holds JDK and Maven/Gradle; the runtime stage holds only a JRE and the jar, so compilers and caches never ship.

FROM eclipse-temurin:21-jdk AS build
WORKDIR /src
COPY pom.xml mvnw ./
COPY .mvn .mvn
RUN --mount=type=cache,target=/root/.m2 ./mvnw -q dependency:go-offline
COPY src src
RUN --mount=type=cache,target=/root/.m2 ./mvnw -q package -DskipTests

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=build /src/target/app.jar app.jar
ENTRYPOINT ["java","-jar","app.jar"]

• Final image typically drops from ~600 MB to ~250 MB.
• BuildKit cache mounts keep ~/.m2 between builds without baking it into layers.

Spring Boot 2.3+ jars contain META-INF/layers.idx splitting content into dependencies, spring-boot-loader, snapshot-dependencies and application. Extracting them into separate Docker layers means a code change rebuilds only the tiny application layer, not ~100 MB of dependencies.

FROM eclipse-temurin:21-jre AS extract
WORKDIR /app
COPY target/app.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --launcher --destination extracted

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=extract /app/extracted/dependencies/ ./
COPY --from=extract /app/extracted/spring-boot-loader/ ./
COPY --from=extract /app/extracted/snapshot-dependencies/ ./
COPY --from=extract /app/extracted/application/ ./
ENTRYPOINT ["java","org.springframework.boot.loader.launch.JarLauncher"]

• Boot 3.3+ uses -Djarmode=tools and extract; Boot 2.3 to 3.2 used -Djarmode=layertools extract and org.springframework.boot.loader.JarLauncher.
• Faster pushes/pulls because registries and nodes cache unchanged layers.

Ship a JRE (or a jlink custom runtime) at runtime since you do not need javac; keep the JDK only in the build stage. Choose the base by size, glibc compatibility, security surface and debuggability.

• Debian/Ubuntu-based eclipse-temurin:21-jre: glibc, shell, easy debugging, ~200-270 MB.
• Alpine: small (musl libc); mostly fine on modern JDKs but native libs (Netty tcnative, some JNI, Snappy) may misbehave.
• Distroless (gcr.io/distroless/java21-debian12): no shell or package manager, fewer CVEs, harder to exec into; use :debug tags or ephemeral debug containers.
• Chainguard/UBI-minimal are other hardened options.
• jlink with jdeps --print-module-deps builds a minimal runtime image.

A root process in a container that escapes through a kernel or runtime bug becomes root on the host; non-root limits the blast radius and is required by many clusters (PodSecurity restricted, OpenShift).

FROM eclipse-temurin:21-jre
RUN groupadd -r app && useradd -r -g app -u 10001 app
WORKDIR /app
COPY --chown=app:app app.jar .
USER 10001:10001
ENTRYPOINT ["java","-jar","app.jar"]

• Use a numeric UID so Kubernetes runAsNonRoot can verify it.
• The app must not need to write outside /tmp or mounted volumes; pair with readOnlyRootFilesystem and an emptyDir for /tmp.
• Ports below 1024 need root or a capability; listen on 8080 instead.

Since JDK 8u191 and JDK 10, the JVM reads cgroup limits (UseContainerSupport, on by default) and sizes the default heap (25% of container memory) and availableProcessors() from them. Older JVMs saw the host's RAM and CPUs and got OOM-killed.

• Default max heap is 1/4 of the memory limit, which is usually too low; set -XX:MaxRAMPercentage=75 (or 70-80 depending on off-heap use).
• -Xmx fixed value overrides percentages; percentages adapt when the limit changes.
• CPU limit of 1500m yields availableProcessors() == 2 (rounded up); this sizes ForkJoin common pool, GC threads and Netty/Tomcat defaults.
• With fewer than 2 CPUs or under ~1792 MB the JVM may pick SerialGC instead of G1 ("not a server-class machine").
• JDK 17+/21 support cgroup v2 fully; JDK 8 needs 8u372+ for cgroup v2.

Container memory = heap + metaspace + thread stacks + code cache + direct/native buffers + GC structures + OS overhead. Heap at 70-75% of the limit is a common starting point; reduce it if you use lots of threads or off-heap.

• Thread stacks: -Xss (1 MB default) x threads, so 500 threads is ~500 MB.
• -XX:MaxMetaspaceSize, -XX:ReservedCodeCacheSize, -XX:MaxDirectMemorySize bound the non-heap parts.
• Inspect with -XX:NativeMemoryTracking=summary and jcmd <pid> VM.native_memory summary.
• Set requests = limits for memory to avoid surprises under node pressure.
• Spring Boot's Buildpack memory calculator does this math automatically from the limit.

JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=70 -XX:+ExitOnOutOfMemoryError -XX:MaxMetaspaceSize=256m"

java.lang.OutOfMemoryError: Java heap space is thrown inside the JVM when heap is exhausted; the JVM logs a stack trace and (optionally) writes a heap dump. OOMKilled (exit code 137) means the kernel cgroup OOM killer sent SIGKILL because total process RSS exceeded the container limit; the JVM gets no chance to log anything.

• Container: docker inspect -f '{{.State.OOMKilled}}' c or kubectl describe pod showing Reason: OOMKilled, Exit Code: 137.
• Heap OOM: fix leak/size, analyze -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/dumps.
• OOMKilled with a healthy heap: non-heap growth (threads, direct buffers, metaspace, native libs); lower MaxRAMPercentage or raise limit.

Docker HEALTHCHECK runs a command periodically and marks the container healthy/unhealthy; Docker Engine and Compose use it, but Kubernetes ignores it and uses its own probes. In Spring Boot, expose Actuator health groups for liveness and readiness.

HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD ["wget","-qO-","http://localhost:8080/actuator/health/readiness"]

management:
  endpoint.health.probes.enabled: true
  endpoints.web.exposure.include: health

• Boot enables /actuator/health/liveness and /readiness automatically when it detects Kubernetes.
• The image needs wget/curl; distroless has neither, so rely on orchestrator probes or a tiny Java health client.
• Do not make liveness depend on the database; a DB outage would restart all pods.

docker stop sends SIGTERM to PID 1, waits 10 s (default), then SIGKILL. The JVM must be PID 1 (exec form) or the signal must be forwarded; otherwise the app is killed abruptly. PID 1 also has special kernel semantics: no default signal handlers, and it must reap zombie children.

• Use exec form, or exec java ... in a wrapper script, or docker run --init / tini.
• Enable Spring Boot graceful shutdown: in-flight requests finish before the context closes.

server.shutdown: graceful
spring.lifecycle.timeout-per-shutdown-phase: 25s

• Set docker stop -t 30 or Kubernetes terminationGracePeriodSeconds above the Spring timeout.
• The JVM exits with 143 (128+15) on SIGTERM; that is normal.

All three produce OCI images; they trade control for convenience.

• Spring Boot Buildpacks (./mvnw spring-boot:build-image): Paketo builds a layered image with a JRE, memory calculator and non-root user; needs a Docker daemon; reproducible.
• Jib (jib-maven-plugin/Gradle): builds without a Docker daemon or Dockerfile, layers dependencies/resources/classes separately, pushes straight to a registry; great for CI.
• Dockerfile: full control (custom packages, jlink, CDS), but you maintain it.

./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=reg.io/shop/api:1.4.0
./mvnw compile jib:build -Djib.to.image=reg.io/shop/api:1.4.0

Default drivers: bridge (private network per host, NAT to outside), host (shares host network stack), none. On a user-defined bridge (the Compose default) containers resolve each other by service name through Docker's embedded DNS; the default bridge network has no name resolution.

• -p 8080:8080 publishes a container port on the host; inter-container traffic needs no published port.
• localhost inside a container is the container itself, so an app must use jdbc:postgresql://db:5432/app, not localhost.
• Reach the host from a container via host.docker.internal (Docker Desktop, or --add-host=host.docker.internal:host-gateway on Linux).
• EXPOSE is documentation only.

Compose declares multi-container apps in YAML so one docker compose up starts the app with Postgres, Redis, etc. Use depends_on with health conditions so the app waits for readiness, not merely start.

services:
  db:
    image: postgres:16
    environment: { POSTGRES_PASSWORD: secret, POSTGRES_DB: app }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10
    volumes: [pgdata:/var/lib/postgresql/data]
  api:
    build: .
    ports: ["8080:8080"]
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/app
      SPRING_DATASOURCE_PASSWORD: secret
    depends_on:
      db: { condition: service_healthy }
volumes:
  pgdata:

• Spring Boot 3.1+ has spring-boot-docker-compose support that starts the compose file automatically and wires connection details; Testcontainers is the equivalent for tests.
• Named volumes persist data across down; down -v deletes them.

Container filesystems are ephemeral. Volumes (managed by Docker) and bind mounts (host paths) persist data beyond the container lifecycle. A stateless Spring Boot app should persist nothing locally: logs go to stdout, state to a DB/object store.

• Mount volumes for databases or for heap dumps (-XX:HeapDumpPath=/dumps).
• tmpfs or emptyDir for /tmp when the root FS is read-only (Tomcat uses /tmp for uploads/work dirs).
• Writing logs to files inside the container grows the writable layer and is lost on restart.

COPY . . before the build invalidates the cache on any change, so the dependency-resolving step reruns. Copy only pom.xml first, resolve dependencies, then copy sources; or use a BuildKit cache mount.

COPY pom.xml .
RUN mvn -B dependency:go-offline
COPY src ./src
RUN mvn -B package -DskipTests

Expected: after the first build, a source-only change reuses the dependency layer and only recompiles. Also add .dockerignore for target/ and .git.

The kernel killed the process because RSS (heap + non-heap) hit the container limit; the heap itself never overflowed. Suspect something in non-heap: threads, direct buffers, metaspace/classloader leaks, JNI/native libs, or heap set too close to the limit.

Steps:

1. Check config: limit 1 GiB with -Xmx1g is guaranteed to die; use MaxRAMPercentage=70.
2. Enable NMT: -XX:NativeMemoryTracking=summary, then jcmd 1 VM.native_memory summary over time and diff.
3. Monitor jvm_memory_used_bytes{area="nonheap"}, jvm_buffer_memory_used_bytes, jvm_threads_live_threads.
4. Common culprits: unbounded thread pools, Netty direct buffers, large Xss, glibc malloc arenas (try MALLOC_ARENA_MAX=2).

Heap alone consumes the entire limit; metaspace, stacks and code cache push RSS above 512 MB so the kernel kills it. Make the heap a fraction of the limit and (probably) raise the limit.

ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=65 -XX:+ExitOnOutOfMemoryError"

With 512 MB, 65% gives about 332 MB heap and leaves ~180 MB for non-heap. A Spring Boot app often needs at least 768 MB to 1 GiB to be comfortable.

SIGTERM is not reaching the JVM, so Docker escalates to SIGKILL after 10 s. Root cause is shell-form CMD/ENTRYPOINT (or a wrapper script without exec).

# wrong
ENTRYPOINT java -jar /app/app.jar
# right
ENTRYPOINT ["java","-jar","/app/app.jar"]

Wrapper scripts should end with exec java .... Then add server.shutdown=graceful and a timeout; set the stop timeout above it. Expected: stop completes in a second or two on an idle app, and in-flight requests finish before exit code 143.

Under a CFS quota of 0.5 CPU the JVM sees 1 processor, picks small thread pools and possibly SerialGC, and the container gets throttled when its threads use the quota in bursts. JIT compilation and GC threads at startup burn the quota, so startup and tail latency suffer.

• Check container_cpu_cfs_throttled_periods_total / throttling metrics.
• Raise the CPU limit (or remove limits and keep requests, a debated but common practice), and give at least 1 to 2 CPUs for JIT warm-up.
• Override: -XX:ActiveProcessorCount=2, explicitly choose -XX:+UseG1GC or -XX:+UseParallelGC.
• Consider CDS/AppCDS, Spring AOT or native image to cut start-up CPU.

The writable layer dies with the container, so write dumps to a mounted volume.

docker run -v /data/dumps:/dumps -m 1g \
  -e JAVA_TOOL_OPTIONS="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/dumps -XX:+ExitOnOutOfMemoryError" \
  shop/api:1.4.0

• In Kubernetes use a PVC or emptyDir plus a sidecar/uploader; the dump is about the size of used heap, so size the volume accordingly.
• Analyze with Eclipse MAT or VisualVM; look at dominator tree for retained size.
• With ExitOnOutOfMemoryError the dump is written first, then the JVM exits.

Typical causes: JDK base, build tools left in the final stage, target/ and .git in context, one huge fat-jar layer.

1. Multi-stage build; runtime on eclipse-temurin:21-jre or distroless.
2. Layered jar extraction, so dependency layers are cached on nodes.
3. .dockerignore for build output and VCS.
4. Remove unused starters/dependencies; check with mvn dependency:analyze.
5. Optional: jlink custom runtime (~50-80 MB JRE), or a GraalVM native image (tens of MB, different tradeoffs).
6. Clean apt caches in the same RUN (rm -rf /var/lib/apt/lists/*).

Expected: ~900 MB to ~200-250 MB, and subsequent pulls transfer only changed layers.

depends_on without a condition only orders container start. Use a DB healthcheck with condition: service_healthy, and make the app tolerant: connection-retry settings and restart: on-failure.

api:
  depends_on:
    db: { condition: service_healthy }
  restart: on-failure

• HikariCP's initializationFailTimeout defaults to 1 ms, so startup fails fast if the DB is down; a larger positive value makes it retry for that long, and a negative value skips the initial check.
• In Kubernetes you rely on readiness and retries rather than ordering.

localhost inside the container is the container's own loopback. Point at the host with host.docker.internal (Docker Desktop; on Linux add --add-host=host.docker.internal:host-gateway), or run the DB as another container on the same user-defined network and use its service name.

docker run --add-host=host.docker.internal:host-gateway \
  -e SPRING_DATASOURCE_URL=jdbc:postgresql://host.docker.internal:5432/app shop/api

Also ensure Postgres listens on a non-loopback address and pg_hba.conf allows the source.

Files copied by root are owned by root, and the unprivileged user cannot write into them. Fix ownership or, better, stop writing logs to files.

RUN mkdir -p /app/logs && chown -R 10001:10001 /app
USER 10001

Best practice: log to stdout (Logback console appender) so the platform collects logs, and mount /tmp as writable if needed. Expected: no permission errors and docker logs shows output.

Treat the secret as compromised: rotate it first. Removing the layer later does not help since published layers and docker history expose it and the image may be cached elsewhere. Then fix the build so it never writes secrets to a layer.

# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=nexus,target=/root/.m2/settings.xml \
    mvn -B package

docker build --secret id=nexus,src=$HOME/.m2/settings.xml .

• Runtime secrets come from env vars/mounted files via the orchestrator, never from the image.
• Add image scanning (Trivy, Grype) and secret scanning in CI.

Spring Boot can take 20-60 s to start; the healthcheck runs from container start and consecutive failures exceed retries. Add --start-period (failures during it do not count), and probe a lightweight readiness endpoint.

HEALTHCHECK --interval=15s --timeout=3s --start-period=60s --retries=3 \
  CMD wget -qO- http://localhost:8080/actuator/health/liveness || exit 1

If it is unhealthy even after start: the tool (curl/wget) may be missing in the image, so the command exits non-zero. Test with docker exec.

Use a distroless/jre-only runtime, readOnlyRootFilesystem, a writable /tmp, dropped capabilities, and a non-root user.

securityContext:
  runAsNonRoot: true
  runAsUser: 10001
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities: { drop: ["ALL"] }
volumeMounts:
  - { name: tmp, mountPath: /tmp }

• Tomcat work dir and multipart uploads use java.io.tmpdir; set -Djava.io.tmpdir=/tmp.
• Heap dumps and any file logging need explicit writable mounts.
• Debug using kubectl debug with an ephemeral container or a :debug image.

Cold start of a Spring Boot app (5-30 s) delays scale-out. Options in increasing effort:

• Reduce work: lazy init (spring.main.lazy-initialization=true, with trade-offs), trim auto-configurations and classpath scanning.
• Class Data Sharing: JDK 13+ AppCDS archive; Spring Boot 3.3+ supports CDS with -Djarmode=tools and -XX:SharedArchiveFile; JDK 19+ -XX:+AutoCreateSharedArchive.
• Spring AOT processing.
• Project CRaC (checkpoint/restore) with supported JDKs; Boot 3.2+ integrates.
• GraalVM native image: ~100 ms startup, lower memory; costs: slower builds, closed-world constraints, lower peak throughput.
• Give startup enough CPU (startup CPU boost / higher limits during start).

A checklist of mistakes seen repeatedly:

• Using latest tags, so deploys are non-reproducible and rollbacks ambiguous.
• Running as root; shipping the JDK and build tools; huge images.
• Shell-form entrypoint, so no graceful shutdown.
• -Xmx equal to the limit, or old JVMs ignoring cgroups.
• No memory limit (host OOM) or limit without understanding non-heap.
• Logging to files instead of stdout; leaking secrets in layers or env dumps.
• Healthcheck depending on external systems, causing restart storms.
• Baking environment-specific config into the image instead of externalizing it.
• Unscanned base images with known CVEs; never rebuilding to pick up patches.

Publish only what humans or external clients need (the gateway); keep databases and internal services on a private network reachable by service name. Use separate networks to segment.

services:
  gateway: { ports: ["8080:8080"], networks: [front, back] }
  orders:  { networks: [back] }
  db:      { networks: [back] }
networks: { front: {}, back: {} }

Orders reaches the database via db:5432 on back; the browser reaches only the gateway on localhost:8080. Expected: db and orders are not reachable from the host or front clients.