Skip to content
notes.vinhnq.com

Search

Git, DevOps & ToolingMid18 min read

Docker for Spring Boot: images, multi-stage Dockerfiles, the JVM in a container and Compose

Review 16 cards
On this page

Interviews love the places where Java containers break: a 1 GB image that takes 8 minutes to build, pods that get OOMKilled, requests cut off on every deploy. This post goes from what a container is to a production Dockerfile for Spring Boot and a compose.yaml for local development. The kernel side is covered in the posts on the operating system and on virtual memory and the JVM; here we only wire it into the Dockerfile.

1. What a container is: an isolated process, not a virtual machine

Key idea: a container is a process (or group of processes) that the kernel shows a private world through namespaces, and whose CPU and RAM it limits through cgroups. There is no second kernel, so it starts in milliseconds.

A namespace is how the kernel gives a group of processes its own copy of a system resource:

Namespace What the container gets its own copy of
pid process tree; the app is PID 1
net network interfaces, IP, ports, routes
mnt directory tree (the image’s file system)
uts hostname
ipc shared memory, semaphores
user UIDs (root inside can be an unprivileged user outside)
cgroup sees only its own cgroup

A cgroup (control group) limits and accounts resources for the whole group: memory.max, cpu.max, pids.max. How CPU quota causes throttling is in the operating system post; how exceeding memory.max triggers the OOM killer is in the virtual memory post.

flowchart LR
  subgraph VM["Virtual machines"]
    H1[Hypervisor] --> G1[Guest kernel A] --> A1[JVM A]
    H1 --> G2[Guest kernel B] --> B1[JVM B]
  end
  subgraph CT["Containers"]
    K[One host Linux kernel] --> C1["JVM A (namespaces + cgroup)"]
    K --> C2["JVM B (namespaces + cgroup)"]
  end

2. Images and layers: why instruction order decides build speed

Key idea: each RUN, COPY and ADD creates a read-only layer on top of the FROM image; Docker reuses a layer when the instruction and its input files haven’t changed. Once one layer changes, every layer after it rebuilds, so what rarely changes goes first.

  • Image = layers + config (ENTRYPOINT, ENV, USER). Layers are shared between images and only missing ones are pulled.
  • Container = image + one writable layer on top (overlayfs). Removing the container drops that layer; data you need must live in a volume.
  • The cache key of COPY is file content, of RUN the command string (so RUN apt-get update won’t rerun when new packages appear).
  • .dockerignore keeps target/ and .git out of the build context: faster builds, no leaked sensitive files.

3. A multi-stage Dockerfile for Spring Boot

Key idea: the first stage has the JDK and Maven to build; the last stage has only a JRE and the layered output. The runtime image carries no compiler, no source and no .m2 repository.

# syntax=docker/dockerfile:1
FROM eclipse-temurin:21-jdk AS build
WORKDIR /src
COPY mvnw pom.xml ./
COPY .mvn .mvn
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -ntp dependency:go-offline
COPY src src
RUN --mount=type=cache,target=/root/.m2 ./mvnw -B -ntp package -DskipTests \
 && java -Djarmode=tools -jar target/*.jar extract --layers --destination /extracted

FROM eclipse-temurin:21-jre
RUN groupadd --system app && useradd --system --gid app --no-create-home app
WORKDIR /app
COPY --from=build /extracted/dependencies/ ./
COPY --from=build /extracted/spring-boot-loader/ ./
COPY --from=build /extracted/snapshot-dependencies/ ./
COPY --from=build /extracted/application/ ./
USER app
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError"
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "orders-0.0.1-SNAPSHOT.jar"]

extract --layers (Spring Boot 3.3+) splits the jar into four directories by how often they change: dependencies, spring-boot-loader, snapshot-dependencies, application; each COPY is one layer. With the Spring Boot 4.0.9 app I tried: dependencies is 21 MB, application 4 KB, so a code change ships a 4 KB layer.

In CI the build stage is usually replaced by the existing Maven step, and the Dockerfile just copies the tested jar (CI/CD post). Set <finalName>app</finalName> in the POM for a tidy jar name (Maven).

4. Choosing a base image: JRE, distroless or Alpine

Key idea: the base image decides size, how many vulnerabilities you patch, and how you debug. The safe default is a JRE on Debian/Ubuntu; distroless for a small attack surface; Alpine only once you’ve verified the app on musl.

Base image Compressed size (amd64, Docker Hub) Shell Notes
eclipse-temurin:21-jdk 225 MB yes build only, don’t run it in production
eclipse-temurin:21-jre 116 MB yes glibc, safe default
eclipse-temurin:21-jre-alpine 74 MB yes (ash) musl libc
gcr.io/distroless/java21-debian12 small, estimated close to Alpine no glibc, :nonroot tag runs as UID 65532

Sizes are from Docker Hub on 18 Nov 2026; distroless isn’t on Docker Hub, so it’s only an estimate.

5. The JVM in a container: getting memory right

Key idea: the JVM reads the memory limit from the cgroup and by default takes 25% as max heap. Set -XX:MaxRAMPercentage=75 for a typical web service, leaving 25% for metaspace, thread stacks and direct buffers; the exact number must be measured.

The non-heap areas, the NMT experiment and how to pick the percentage are in the virtual memory, page cache and JVM post. What’s specific to the Dockerfile:

  • Set flags via JAVA_TOOL_OPTIONS: the JVM reads it by itself, so no shell is needed to expand $JAVA_OPTS and the ENTRYPOINT stays in exec form.
  • Add -XX:+ExitOnOutOfMemoryError so the JVM dies cleanly when the heap is full and gets restarted, instead of limping on.
  • OutOfMemoryError is thrown by the JVM and leaves a stack trace; OOMKilled, exit code 137 is the kernel killing the process because RSS exceeded memory.max, and the log says nothing.

6. Running safely and stopping cleanly: non-root, PID 1, healthchecks

Key idea: run as a normal user, make Java PID 1 with an exec-form ENTRYPOINT, and enable server.shutdown=graceful. Docker’s healthcheck is useful with Compose; Kubernetes ignores it and uses its own probes.

  • Non-root: USER app as in the Dockerfile in section 3. Why, and the “Permission denied” on volumes, is in the Linux post.
  • PID 1 and signals: docker stop and Kubernetes send SIGTERM to PID 1, wait (Docker 10 seconds by default, Kubernetes 30), then SIGKILL. Shell form ENTRYPOINT java -jar app.jar makes sh PID 1 and it swallows SIGTERM; the mechanism is in the operating system post.
  • Graceful shutdown: I sent SIGTERM while the app was serving a 5-second request: that request still returned 200 and new requests were refused immediately (exercise 2).

Healthcheck. HEALTHCHECK tells Docker whether the container is healthy (every 30 seconds by default, 3 failures means unhealthy) and fits Compose (condition: service_healthy). Kubernetes ignores it and calls probes on /actuator/health/liveness and /actuator/health/readiness; probe configuration and rollout strategies belong to the post on deployment strategies.

7. Docker Compose for local development

Key idea: one compose.yaml starts PostgreSQL and Redis at the production versions, waits until they’re ready, then starts the app. The whole team gets the same environment with one docker compose up.

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: orders
      POSTGRES_USER: orders
      POSTGRES_PASSWORD: dev-only
    ports: ["5432:5432"]
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orders -d orders"]
      interval: 5s
      retries: 10
  redis:
    image: redis:7.4
    ports: ["6379:6379"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10
  app:
    build: .
    profiles: [full]
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/orders
      SPRING_DATASOURCE_USERNAME: orders
      SPRING_DATASOURCE_PASSWORD: dev-only
      SPRING_DATA_REDIS_HOST: redis
    ports: ["8080:8080"]
    depends_on:
      postgres: { condition: service_healthy }
      redis: { condition: service_healthy }
volumes:
  pgdata:
  • On the Compose network, services reach each other by service name (postgres), not localhost.
  • depends_on without condition only waits for the container to start, not for PostgreSQL to accept connections.
  • profiles: [full]: by default only infrastructure starts and developers run the app from the IDE. With the spring-boot-docker-compose dependency (Spring Boot 3.1+), the app runs docker compose up itself and wires the datasource.
  • These passwords are for laptops only; production reads secrets from the environment (12-factor).

8. Image size, tags and vulnerability scanning

Key idea: small images pull fast and have fewer packages to patch. Use immutable tags (version or commit SHA), never deploy latest, and scan for vulnerabilities in CI before the image is used.

  • Smaller: multi-stage, JRE instead of JDK, apt-get install and cache cleanup in the same RUN (deleting in a later layer doesn’t shrink the image).
  • Tags: latest is just the default tag name, not “newest”, and it can be overwritten. Deploy orders:1.4.2 or orders:sha-a1b2c3; safest is by digest orders@sha256:..., which is tied to content.
  • Scanning: Trivy, Grype or Docker Scout compare the image’s packages against CVE databases; CI blocks fixable CRITICAL/HIGH findings. Export an SBOM (bill of materials) to find quickly which images a new CVE hits.
  • Rebuild regularly even without code changes, to pick up JRE and OS patches.

Exercises

Exercise 1: Review a Dockerfile

Task. The Dockerfile below takes 6 minutes to build after a one-line change, the image is over 600 MB, and every deploy fails a few requests. Find at least six problems and rewrite it.

FROM maven:3-eclipse-temurin-21
COPY . /app
WORKDIR /app
RUN mvn package
ENV JAVA_OPTS="-Xmx1g"
EXPOSE 8080
CMD java $JAVA_OPTS -jar target/orders-0.0.1-SNAPSHOT.jar
Solution to Exercise 1: eight problems and the fixed Dockerfile
  1. Single stage: the runtime image carries the JDK, Maven, source and .m2.
  2. COPY . before building: one changed line re-downloads every dependency; no .dockerignore.
  3. Floating maven:3-... tag: next month builds a different image. Pin the version (and digest).
  4. mvn package runs the tests during the image build: slow, and Testcontainers fails without Docker. Tests belong in CI.
  5. Fat jar as one layer: every deploy pushes 20+ MB instead of a few KB.
  6. Runs as root.
  7. Shell-form CMD: sh is PID 1, Java never gets SIGTERM, gets SIGKILLed, in-flight requests are cut: exactly the deploy errors.
  8. Hard-coded -Xmx1g: ignores the limit; with a 1 GiB limit it will be OOMKilled.

The fix is the Dockerfile from section 3, plus a .dockerignore:

target/
.git/
.idea/
*.iml
.env

and server.shutdown=graceful in application.properties. To verify: a second docker build after editing one Java file only reruns from COPY src; docker history <image> shows an application layer of a few KB; docker stop finishes in a few seconds with “Graceful shutdown complete” and exit code 143 or 0.

Not run on my machine: the Docker daemon isn’t running, so docker build and docker stop weren’t tried. What did run is in exercise 2.

Exercise 2: Measure layered jars and graceful shutdown

Task. Without Docker: build a small Spring Boot app, run extract --layers and measure each layer. Then run the app from the extracted directory (as in a container) and check whether an in-flight request completes on SIGTERM.

Solution to Exercise 2: commands, measurements and explanation

App: Spring Boot 4.0.9, spring-boot-starter-webmvc + actuator, an endpoint /slow that sleeps 5 seconds, server.shutdown=graceful. JDK 21, macOS.

$ ./mvnw -q package -DskipTests && ls -la target/*.jar
22017207  target/orders-0.0.1-SNAPSHOT.jar
$ java -Djarmode=tools -jar target/orders-0.0.1-SNAPSHOT.jar list-layers
dependencies
spring-boot-loader
snapshot-dependencies
application
$ java -Djarmode=tools -jar target/*.jar extract --layers --destination extracted
$ du -sh extracted/*
4.0K  extracted/application
 21M  extracted/dependencies
  0B  extracted/snapshot-dependencies
  0B  extracted/spring-boot-loader

application contains just a thin jar (orders-0.0.1-SNAPSHOT.jar) whose Class-Path points to lib/; dependencies contains lib/*.jar. Here spring-boot-loader is empty because the thin jar runs directly with java -jar without Spring Boot’s launcher.

Running it as in a container (all layers merged into one directory), sending SIGTERM while /slow is in progress:

$ java -jar orders-0.0.1-SNAPSHOT.jar &      # Started App in 0.654 seconds
$ curl localhost:8080/slow &                 # 5-second request
$ kill -TERM <pid>                           # one second later
$ curl localhost:8080/actuator/health        # new request: connection refused
done 200 5.014432s                           # the old request still completes
INFO ... GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
INFO ... GracefulShutdown : Graceful shutdown complete

Explanation: outside a container, kill goes straight to the JVM, so this always works. Inside a container it only repeats if Java is PID 1 (exec form). In shell form, SIGTERM goes to sh and nobody forwards it to Java. The in-container run wasn’t tried because Docker isn’t running on this machine.

Remember

  • Explain how a container differs from a VM: namespaces isolate, cgroups limit, one shared kernel.
  • Write a multi-stage Dockerfile for Spring Boot, and explain why COPY order and layered jars make builds and deploys fast.
  • Know when to pick JRE, distroless or Alpine, and why musl can bite.
  • Tell OOMKilled from OutOfMemoryError, and set MaxRAMPercentage via JAVA_TOOL_OPTIONS.
  • Verify graceful shutdown: exec form, non-root, server.shutdown=graceful, and which healthcheck belongs to Compose and which to Kubernetes.

Interview questions

Junior

How is a container different from a virtual machine?

A container is a process sharing the host kernel, isolated by namespaces and limited by cgroups; a VM has its own kernel running on a hypervisor.

Since no kernel boots, a container starts in milliseconds and is much lighter. The price is a weaker security boundary than a VM, and Linux containers need a Linux kernel (on Mac/Windows, Docker runs inside a Linux VM).

What’s the difference between CMD and ENTRYPOINT?

ENTRYPOINT is the program that always runs; CMD is the default arguments, replaced by whatever follows the image name in docker run.

A common combination: ENTRYPOINT ["java", "-jar", "app.jar"] and CMD ["--spring.profiles.active=prod"]. Both should be in exec form (a JSON array) so the process is PID 1 and receives signals; shell form runs through /bin/sh -c.

What’s the difference between COPY and ADD? Which should you use?

Use COPY. ADD does two extra implicit things: downloads from URLs and auto-extracts local tar files.

Implicit behaviour makes a Dockerfile hard to predict (a .tar.gz gets unpacked when the reader doesn’t expect it), and URL downloads via ADD are hard to checksum and cache. If you need a download, use RUN curl with a checksum check in the build stage.

Mid

Why shouldn’t you deploy images tagged latest?

Because latest is a label that can be overwritten: you can’t tell what code production runs, two nodes may pull different images, and rollback is undefined.

latest is only the default tag name, not “the newest build”. Tag by version or commit SHA and deploy by digest (@sha256:...) so the content can’t change. Immutable tags also give traceability: an error in an image maps to a commit.

Why shouldn’t a container run as root?

Because if the app is exploited, the attacker has root inside the container, one step closer to the host given a kernel bug or loose configuration.

Create a system user in the Dockerfile and USER app; on Kubernetes add runAsNonRoot: true and readOnlyRootFilesystem: true with an emptyDir for /tmp. Spring Boot doesn’t need root, since port 8080 isn’t privileged.

Senior

A Spring Boot pod keeps restarting with exit code 137 and nothing in the logs. How do you investigate?

137 means death by SIGKILL: usually the kernel OOM killer because RSS crossed the memory limit, or a kill after the grace period because the app didn’t stop in time on SIGTERM.

  • kubectl describe pod: Last State: Terminated, Reason: OOMKilled means memory. Compare -Xmx or MaxRAMPercentage with the limit; measure RSS and NMT to see the non-heap part (metaspace, threads, direct buffers).
  • Not OOMKilled but restarts during deploys: check for a shell-form ENTRYPOINT and shutdown time versus terminationGracePeriodSeconds.
  • An aggressive liveness probe also causes restarts (the pod is killed during a long GC pause).
  • Fix: a sensible heap percentage, ExitOnOutOfMemoryError, limit = measured usage plus 20–30% headroom.
A Spring Boot image is 900 MB and each build takes 8 minutes. How do you optimise it?

Split build and runtime stages, use a JRE, order layers by change frequency, split the jar into layers, and cache Maven dependencies.

  • Multi-stage: the runtime image has only the JRE and the app, no JDK, Maven or source.
  • COPY pom.xml and fetch dependencies before COPY src; cache-mount /root/.m2 with BuildKit; add .dockerignore.
  • extract --layers: a code change only touches the few-KB application layer.
  • In CI: BuildKit layer cache (cache-from/cache-to), and don’t run tests twice (test in the CI step, the Dockerfile only packages).
  • Measure before and after with docker history and build times, don’t guess.
Would you pick Alpine or distroless for a production Java service?

Usually distroless or a JRE on Debian/Ubuntu, not Alpine, because Alpine trades glibc for musl to save only a few dozen MB.

musl can break native libraries built for glibc and resolves DNS differently. Distroless keeps glibc and has very few packages, so few CVEs, but no shell: exec form only, debugging via kubectl debug or the :debug tag. If the team needs a shell for operations, a JRE on Ubuntu is a reasonable compromise.

Useful phrases for interviews

  • “Namespaces decide what a container can see; cgroups decide how much it can use.”
  • “A container is just a process on the host kernel, so it starts in milliseconds but isolates less than a VM.”
  • “Changing one layer invalidates every layer after it, so dependencies go before source code.”
  • “A multi-stage build keeps the JDK and Maven out of the runtime image.”
  • “With layered jars, a code change ships a few kilobytes instead of the whole fat jar.”
  • “We picked a JRE base image over Alpine to stay on glibc.”
  • “Distroless images have no shell, so the entrypoint must be in exec form.”
  • “Exit code 137 with OOMKilled is the kernel, not the JVM; the heap percentage was too high for the limit.”
  • “Use exec form so the JVM is PID 1 and receives SIGTERM.”
  • “We deploy by digest, because tags can be moved.”

Self-compiled notes from official documentation and hands-on practice.