The commands below were run on this machine (Docker Engine 29.4.1, cgroup v2). Each namespace is an inode number in /proc/self/ns. A container gets new numbers for most namespaces; the host keeps the originals.

Six namespaces differ, so the container has its own PIDs, network, mounts, hostname, IPC and cgroup view. **The user namespace is identical to the host's.** By default Docker does not remap user IDs, so UID 0 inside the container is UID 0 on the host, just with fewer privileges. That is why running as a non-root user (chapter 10) matters, and why rootless mode and user-namespace remapping exist.

cpu.max is quota period in microseconds: 100000 100000 means "100 ms of CPU time per 100 ms window", one CPU. The Java process is PID 1 in its own namespace and PID 2482937 on the host. Same process, two numbers.

The pieces are specified by the Open Container Initiative (OCI): the image spec (what an image is), the runtime spec (how to run one) and the distribution spec (how registries serve them). That is why an image built with Docker runs on containerd, Podman or Kubernetes without change. On macOS and Windows, Docker Desktop runs a small Linux VM, because the container features above are Linux kernel features.

Because a layer is named by its hash, two images that start from the same base store the base once on disk, and a registry transfers only the layers you do not have yet. That is why pulling a new version of your app is quick if only the top layer changed, and why chapter 4 spends so much effort on layer order.

Deleting a file in a later layer does not shrink the image. The earlier layer still contains it, and the later layer only adds a marker (a whiteout, a file named .wh.<name>). Chapter 10 shows what that means for secrets.

The digest above is the one this machine received on 2026-10-31. The 21-jre tag will point at a different digest after the next Temurin release, which is exactly the point of the next section.

ENTRYPOINT is what the container is; CMD is the default arguments (or the default command if there is no entrypoint). Arguments after the image name in docker run replace CMD but are appended to ENTRYPOINT. --entrypoint replaces the entrypoint.

CMD java -jar app.jar (shell form) is run as /bin/sh -c "java -jar app.jar". CMD ["java","-jar","app.jar"] (exec form, a JSON array) runs the program directly. The difference decides who is PID 1, and PID 1 is special: the kernel gives it no default signal handlers, so a SIGTERM sent by docker stop is ignored unless the process installs a handler itself. A shell does not forward signals to its child.

We measured it with docker stop (default grace period 10 s, then SIGKILL) on this machine:

So the rule is not just "use exec form". It is: the process that is PID 1 must handle SIGTERM. The JVM does (it runs shutdown hooks, Spring Boot closes the web server gracefully and exits 143). A shell, sleep or a script does not. Fixes, in order of preference: exec form with a program that handles signals; exec java ... as the last line of any wrapper script so the shell replaces itself; or docker run --init / init: true in Compose to put a tiny init (tini, built into Docker) in front.

The build context is the directory you pass to docker build (usually .). It is sent to the builder in full, so a missing .dockerignore means .git, target/, node_modules and .env travel with every build and can end up inside a COPY . . layer. A .dockerignore file in the context root lists what to leave out; later !pattern lines add exceptions.

• Docker compares each instruction with the cache. For RUN it compares the instruction text (not what the command would produce); for COPY and ADD it compares a checksum of the files copied.
• As soon as one instruction misses the cache, every later instruction runs again.
• So order instructions from least to most frequently changing: base image, OS packages, dependency manifest, dependency download, source code, build.
• A RUN apt-get update && apt-get install -y x stays cached forever, even when packages have moved on. Rebuild with --pull --no-cache on a schedule so base images and packages get refreshed.

Measured with the multi-stage Dockerfile of chapter 5 (warm Maven cache mount, this machine): editing one Java file left COPY pom.xml, mvn dependency:go-offline and the dependency, loader and snapshot layers CACHED, and re-ran only COPY src, the Maven package step and the final application layer. A first, completely cold build (image pulls plus all Maven downloads) took 82 s here; rebuilds with a warm cache took roughly 14 to 25 s, dominated by the Maven package step. Treat these as one machine's numbers, not a benchmark.

A multi-stage Dockerfile has several FROM lines. Early stages carry the compiler, Maven, test tools and source; the final stage starts from a slim runtime image and copies in only the build output with COPY --from=build. Nothing from the earlier stages ships. The result is smaller, has fewer vulnerabilities to scan, and never contains your source or build credentials.

Multi-platform images (for example linux/amd64 and linux/arm64, so the same tag runs on Intel servers and Apple Silicon or Graviton) are built with docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/shop:1.4.2 --push .. A multi-platform result is an image index with one manifest per architecture, so it has to be pushed (or exported as an OCI archive) rather than loaded into a single local image store. It needs a builder that supports multiple platforms (see the buildx docs; QEMU emulation or native builders). The flags above exist in the buildx installed here (v0.30.1); the multi-platform build itself was not run for this page.

It works, and it is the version in most tutorials. Its problems: the JDK (compiler, jshell, tools) ships to production; it runs as root; the 25 MB jar is one layer, so changing one line of your code re-uploads and re-downloads all 25 MB; and running an uber jar un-unpacked adds startup overhead (Spring Boot docs call this out under "Efficient Container Images").

Spring Boot jars built by the Maven or Gradle plugin carry a layer index (BOOT-INF/layers.idx) that splits the jar into dependencies, spring-boot-loader, snapshot-dependencies and application, ordered from least to most likely to change. A helper mode of the jar unpacks those directories so each becomes its own Docker layer.

The extraction runs in a throw-away first stage; the runtime stage copies the four directories in order of volatility. Checking the result with docker history: the dependency layer is 25.7 MB, the loader and snapshot layers are about 4 kB each, and the application layer is 16.4 kB. After a code change only that 16 kB layer is rebuilt, pushed and pulled.

spring-boot:build-image needs a running Docker daemon and builds an OCI image with Cloud Native Buildpacks; the default builder in the Spring Boot docs is paketobuildpacks/builder-noble-java-tiny:latest, and the resulting image runs as a non-root user (docs: "images build and run as non-root users"). It sets up the JVM memory configuration for you and layers the image sensibly. The trade-off is less control: you tune through plugin properties and BP_*/BPL_* environment variables, not Dockerfile lines. It is a good default for teams that do not want to own Dockerfiles.

Smaller images mean faster pulls and fewer packages to patch. Distroless images from Google contain the runtime and its libraries but no shell and no package manager. The names below exist and were pulled for this page: gcr.io/distroless/java21-debian13:nonroot (also java21-debian12), gcr.io/distroless/cc-debian13:nonroot. The :nonroot tag runs as UID 65532.

For the last step, jlink builds a custom JRE containing only the JDK modules the application needs, which can then sit on a minimal base such as distroless/cc (it provides glibc and libstdc++ but no Java).

For reference, the bare base images on the same machine: eclipse-temurin:21-jdk 729 MB, eclipse-temurin:21-jre 462 MB, eclipse-temurin:21-jre-alpine 283 MB, distroless/java21-debian13:nonroot 262 MB (disk usage). Disk usage is the unpacked size on disk; content size is the compressed size that moves over the network. Alpine uses musl instead of glibc; test your native dependencies before choosing it. All five variants were started and served /actuator/health/liveness.

A newer option from the Spring Boot docs: with Java 25 or later, the layered Dockerfile can add a training run (java -XX:AOTCacheOutput=app.aot -Dspring.context.exit=onRefresh -jar application.jar) and start with -XX:AOTCache=app.aot for faster startup; for Java 24 and earlier the docs show the CDS equivalent. This page uses Java 21 and did not run it.

The conservative default leaves room for non-heap memory but wastes a lot of a small container. A starting point of **-XX:MaxRAMPercentage=70 to 75** is common; measure docker stats and tune. (InitialRAMPercentage defaults to about 1.56%, MinRAMPercentage to 50% and only matters for very small limits.)

Spring Boot service with -XX:MaxRAMPercentage=75, started with -m 512m --cpus 1 in Compose: /memory answered {"cpus":1,"maxHeapMiB":371}. (371 rather than 384 because the JVM reports the usable heap, which excludes one survivor space.) The same image started with no limit on this 31 GiB machine reported a maximum heap of 23808 MiB, 75% of the host. A percentage flag without a container limit is a request to use most of the machine. Always set both.

• Non-heap memory: metaspace (loaded classes), thread stacks (default ThreadStackSize is 1024 KiB per thread, and Tomcat has 200 request threads by default), the JIT code cache (ReservedCodeCacheSize 240 MiB reserved on this JDK, usually far less committed), direct ByteBuffers used by Netty and NIO, GC data structures and the C library.
• Rule of thumb: container limit = max heap + a few hundred MiB of overhead, then verify under load. With a 512 MiB limit, a 75% heap leaves 128 MiB for everything else, which a busy service may exceed.
• Runtime.availableProcessors() follows --cpus: the JVM sized cpus to 1 under --cpus 1 and to 2 under --cpus 2 (shown by -XshowSettings:system: Effective CPU Count: 2, Memory Limit: 256.00M). ForkJoinPool, GC thread counts and Tomcat tuning follow it. -XX:ActiveProcessorCount=N overrides it.

More on heap sizing, GC choice and what to measure is on the JVM Memory and GC page; the Kubernetes meaning of requests and limits is on page 04.

Publishing a port maps a host port to a container port: -p 8080:8080 (all host interfaces), -p 127.0.0.1:8080:8080 (host loopback only, which is what you want for a database during development), -p 8080 (random host port, see docker port). EXPOSE in the Dockerfile only documents; it publishes nothing.

• The writable container layer is slow and ephemeral: heavy writes (database files, uploads) belong on a volume.
• A bind mount to a directory owned by root is not writable by a non-root container user (UID 10001 in our image). Fix ownership on the host or use a volume.
• docker compose down keeps named volumes; docker compose down -v deletes them. That flag is how people lose a development database.
• In production on Kubernetes or ECS, persistent data uses the platform's volume types (EBS, EFS), not Docker volumes (page 03, ECS).

• name: shop fixes the project name (container names become shop-app-1, shop-db-1, and the network shop_backend). The old top-level version: field is no longer needed.
• depends_on with condition: service_healthy makes Compose wait until the db health check passes. The other conditions are service_started (the default) and service_completed_successfully (for one-shot jobs such as migrations).
• healthcheck on db uses pg_isready, which ships in the PostgreSQL image. The app's check uses curl against Spring Boot's readiness endpoint, which works because the eclipse-temurin image contains curl; a distroless image would need a different mechanism.
• ${DB_PASSWORD:?message} stops Compose with an error if the variable is unset, instead of starting a database with an empty password. Never commit the real .env.
• mem_limit and cpus are plain service attributes; the memory limit is what made the JVM size its heap at 371 MiB in chapter 6. (deploy.resources.limits expresses the same thing and is also honoured by docker compose today.)
• restart: unless-stopped restarts the app after a crash or a daemon restart, but not after you stopped it deliberately.

• Build once, promote the same image. The artifact tested in staging is the artifact in production, referenced by the same digest. Rebuilding per environment tests a different image.
• Make tags immutable where the registry supports it (Amazon ECR has a tag-immutability repository setting) so a second push to 1.4.2 is rejected rather than silently replacing it.
• Add labels that link back to the source (org.opencontainers.image.source, .revision, .version), so anyone with a running image can find its commit.
• Expire untagged and old images with a registry lifecycle policy, or storage grows without bound. Keep whatever is currently deployed plus a rollback window.
• Scan on push and again on a schedule: a clean image today can have a known CVE next week (chapter 10).

The script uses registry.example.com, a placeholder; it was syntax-checked, not run against a registry.

Layers are tar files that anyone with the image can read. The Dockerfile below copies a token file, uses it, then deletes it, and also takes the token as a build argument. It builds fine, and the secret is still in the image twice.

Three leaks from three lines: the ARG value in the image history, the COPY'd file inside its layer, and a rm that hides nothing. The fix is the BuildKit secret mount from chapter 4, which never writes the secret into a layer. At run time, inject secrets as environment variables from the orchestrator's secret store, or as mounted files (Compose secrets:, Kubernetes Secrets, AWS Secrets Manager), not as ENV in the image. Also keep .env and credentials out of the build context with .dockerignore.

• Never run --privileged or mount /var/run/docker.sock into an application container; either one is equivalent to root on the host.
• Do not publish database ports to 0.0.0.0 on shared machines (-p 127.0.0.1:5432:5432).
• Rootless Docker and user-namespace remapping make container root a regular host user, at the cost of some features; consider them on shared build hosts.

A scanner unpacks the image, inventories the OS packages and the language libraries (Maven jars here), and matches them against vulnerability databases. We scanned two of the images with Trivy 0.76.1 (run from its container image against docker save tarballs, on 2026-10-31, so the counts are a snapshot of that day's database).

Two lessons. The application's own dependencies often dominate: the Java findings are identical in every variant, because the jar is identical, and were reported in Jackson, embedded Tomcat, Spring MVC and the PostgreSQL driver of this particular dependency set. A smaller base image does not fix them; upgrading the dependencies does (Spring Boot patch releases bump the managed versions). And counts are not equally actionable: triage by whether a fixed version exists and whether the vulnerable code path is reachable.

• Docker Scout (docker scout quickview, docker scout cves) is the scanner integrated into Docker Desktop and Hub. The CLI plugin is installed here, but it needs a Docker login, so it was not run for this page.
• SBOM (software bill of materials): a machine-readable inventory of what is in the image. BuildKit can attach one with --sbom=true (flag present, not run here); Spring Boot can also expose its own dependency list through the Actuator sbom endpoint. Scanners can consume an SBOM instead of re-inspecting the image, and an SBOM lets you answer "are we affected?" the day a new CVE is published.
• Provenance attestations (--provenance=mode=max) record how and where an image was built. Signing (cosign/Notary) lets clusters admit only images your pipeline produced.
• Rebuild on a schedule even without code changes: base images get patched, and a pinned digest stays vulnerable until you bump it.

The app uses 149 MiB of its 512 MiB while idle, with a 384 MiB heap ceiling; docker stats shows the container total (heap plus everything else), which is what the kernel compares with the limit.

• Write logs to stdout and stderr, not to files inside the container. Spring Boot logs to the console by default; do not add a file appender in a container.
• The default driver is json-file, and by default no log rotation is performed, so a chatty container can fill the disk (Docker logging docs). Set max-size and max-file, or switch to the local driver, which rotates by default.
• Other drivers ship logs off the host: syslog, journald, fluentd, gelf, awslogs and more. Recent Engine versions keep a local copy as well, so docker logs still works with them ("dual logging").
• The default delivery mode is blocking: if the driver is slow, the application's writes to stdout block. mode: non-blocking uses a buffer instead, at the risk of dropping messages when it is full.