Docker Deployment: Image Layers and Compose

Plain language first. A container is not "a miniature computer" — it is a single Java process shut into a small room of its own: it has its own view of the filesystem, its own network card, its own memory allowance, but it shares one Linux kernel with the host. Because it virtualizes no hardware and installs no operating system, it starts in seconds and begins at a few dozen MB. An image is that packaged set of files and configuration — the same image expands to exactly the same thing on any machine with Docker installed, which is how it cures "it works on my machine".

Six terms, one line each (used throughout):

• Image: a template built by stacking read-only layers; built once, reused everywhere; it is a deliverable, not something running
• Container: a running instance of an image — the read-only layers plus one writable layer on top; delete the container and the writable layer is gone
• Layer: one COPY / RUN in a Dockerfile; a layer only cares whether "I and everything below me changed"
• Build cache: if a layer and everything below it is unchanged, it is not re-executed — this is the entire art of writing a Dockerfile
• cgroup: the Linux kernel's quota switch; docker run -m 512m limits memory through it, and a container-aware JVM reads it
• namespace: Linux's view-isolation mechanism, which is why a process inside a container cannot see the host's other processes or network

That tree splits the whole article into four gates: separate image from container → write a Dockerfile that does not waste the cache → how the JVM and the container behave once it runs → orchestration and graceful shutdown. Every later section sits somewhere on that tree; when you get stuck, come back and see which gate you are standing on.

After this article you should be able to answer three questions:

• Why does editing one line of business code make my image build re-download dependencies? In what order should Dockerfile instructions go?
• The container log says Exit code (137) / Reason: OOMKilled, but there is not a single OutOfMemoryError in the Java log — who killed whom?
• I configured graceful shutdown, yet docker stop still severs requests. Which step swallowed the signal?

Every backend engineer has heard: "it works on my machine." The real cause is environment drift — the dev box runs JDK 21 with MySQL 8.0, staging runs JDK 17 with MySQL 5.7, and production is something else again. Containerizing means packaging "app + dependencies + runtime" into one immutable artifact so all three environments run the same thing.

Containers are light because they virtualize no hardware and install no full OS — they share the host kernel, using namespaces for view isolation and cgroups for limits. That brings fast startup and high density at the cost of weaker isolation than a VM (a kernel vulnerability can be exploited across containers).

Separate the four most confused terms:

An image is not one blob but a stack of read-only layers, one per COPY, RUN, ADD. During a build, Docker compares the cache layer by layer: if a layer and everything below it are unchanged, that layer is reused and not re-executed.

This explains a classic optimization: copy pom.xml first.

This rule is easy to remember backwards when you only read about it; watching one cache decision once fixes it for good. The experiment below uses the default layer argument to spell out "which layer each instruction creates", "what the cache compares", "what CACHED in the build output means" — watch frame 3 (why COPY pom.xml goes first) and frame 6 (how much layered extraction saves):

The cache decision is not obvious from a picture alone; what people forget is what makes up a layer's fingerprint. The single-stepper below runs a five-line builder stage frame by frame — at each step, watch which fingerprint is recomputed. Step ③ is the heart of it:

Keep that fingerprint table in mind for 2.2: if COPY src ./src gets polluted with target/-type junk, every layer changes and the cache never hits again.

The build context is packaged as a whole and handed to the daemon first, so target/, .git/, node_modules/ are uploaded once even though they never make it into the image. Put a .dockerignore at the root:

A naive version that runs but is not yet production-grade:

The Dockerfile above assumes the host already ran mvn package. But CI machines may lack Maven, and even if they have it, build and runtime environments should not be mixed. The answer is a multi-stage build — two FROM sections in one Dockerfile, the first building, the second taking only the artifact.

Multi-stage builds fix the size, but a cache problem remains: every code change alters app.jar, invalidating the COPY app.jar layer and forcing the dependency layer to rebuild too. Spring Boot's layered extraction splits the fat jar into separate layers that can be copied independently:

Sections one to four are really three stages of one pipeline: first build a jar that runs, then cut that jar into layers inside an image, finally start the container and publish the port. Beginners break exactly at "which one holds which", so walk the whole road in order:

Step six deserves a note: -p 8080:8080 and /actuator/health/readiness are two different responsibilities — the first is Docker's job (mapping a host port into the container), the second is the application's own (answering "can I take traffic right now"). This article nails the Docker half; the probe half is Article 42.

And the premise of steps one and two is that you really know what the jar you baked into the image looks like. The previous article opened up the executable jar: Main-Class is JarLauncher rather than your startup class, and the dependencies sit in BOOT-INF/lib read by a custom class loader. Confirm that with this experiment before containerizing — especially the war branch: once you deploy to an external Tomcat, COPY target/*.jar simply finds nothing.

Containers run on the bridge network by default, and each container has its own IP — inside a container localhost means the container itself, not the host. Within a custom network, containers reach each other by service name:

Hand-typing docker run quickly spirals out of control. Compose describes the whole environment declaratively, and docker compose up brings it all up:

Section by section:

• Service dependencies and order: depends_on alone guarantees only "start order", not "readiness". Adding condition: service_healthy waits for the health check — the key to avoiding "the app starts before the database is ready"
• Health checks: healthcheck.test is the liveness command — mysqladmin ping for MySQL, redis-cli ping for Redis. service_healthy in depends_on relies on its result
• Injecting DB config via env vars: the app never hard-codes a connection string; it reads DB_HOST / DB_NAME injected by Compose. ${MYSQL_ROOT_PASSWORD:-root} means "take the env var, default to root"
• Volumes: mysql-data and redis-data are named volumes declared at the top level, so data survives container recreation
• Build vs image: build: . lets Compose build on the spot; image: names it for reuse

Compose's healthcheck tells the orchestrator whether a container can take work — and the Spring Boot app inside has to answer that question itself. Article 42 covered the Actuator health endpoint; here it is through the container lens: a health check is not a ping, it is the worst result after several contributors vote:

• DB up, Redis up → UP; anything down → the whole chain reports DOWN, and K8s readiness pulls you out of the load balancer
• So never put a business query in the health check: one slow SQL turns "the process is alive" into "the instance is unavailable"
• To see which contributor drags the status down, turn on management.endpoint.health.show-details=always

Containerizing is more than a Dockerfile; the app needs two adjustments too.

Never hard-code localhost in application.yml; use placeholders with defaults:

One container principle: the process writes to stdout; where logs go is the platform's business. So production config should log to the console only, not to files:

This is the spot in containerizing that "is fine in normal times and explodes right after a scale-out". When the JVM decides how large a heap to open, it looks by default at the physical memory of the whole machine, not at the quota handed to it. A process running inside a 512m container that sizes its heap as if the host had 32GB will race up to the cgroup ceiling and get erased by the kernel. Since Java 8u191 UseContainerSupport is on by default and the JVM reads the cgroup limit files (v1 memory.limit_in_bytes, v2 memory.max) — but it reads the limit, not "your heap".

The correct form is to declare a percentage rather than hard-code -Xmx:

Two failure modes must be kept apart, because their investigation directions are opposite:

The boundary between the two failure modes comes down to one number: what percentage of the limit the heap takes. Drag -XX:MaxRAMPercentage from 25 to 100 inside a 512MB container and watch heap, off-heap and the total bill split apart at every stop — note the far end, where it becomes equivalent to hard-coding -Xmx512m:

The left column explains why "just give it more memory" so often only hides the problem: the root cause may be Netty direct memory that was never released, and off-heap memory is not governed by -Xmx at all. This experiment walks "how much does the JVM read → how is the default heap computed → what each failure looks like" in one pass:

Checklist read; now turn it into your own project's behavior. The generator below turns "which blocks a production-grade Dockerfile needs" into checkboxes. Tick only multi-stage + layered first for the minimal skeleton, then add non-root, the memory ratio, the health check and the stop signal one by one, verifying each against the benefits in the table above:

The most common misconception: that localhost:3306 inside a container reaches the host's MySQL. Wrong — a container's network namespace is separate, so localhost means the container itself. Either use the host IP (172.17.0.1 on Linux), or — better — put the database in Compose and use service names.

EXPOSE 8080 only declares; it does not make the port reachable from outside. What publishes a port is docker run -p 8080:8080 (or ports in Compose). Forget -p and the container runs fine while your browser cannot connect.

Containers default to UTC, so log timestamps and database times are 8 hours behind Beijing. Fix it with ENV TZ=Asia/Shanghai in the Dockerfile, or -e TZ=Asia/Shanghai at run time, plus serverTimezone=Asia/Shanghai in the JDBC URL.

Some images (especially slim ones) have a small entropy pool, so SecureRandom blocks reading /dev/random — the app appears stuck at startup while Tomcat never binds the port. Linux kernel 5.6+ no longer blocks on /dev/random; on older kernels mount /dev/urandom or pass -Djava.security.egd=file:/dev/./urandom.

Running an x86-only image on an Apple Silicon (M-series) Mac, or pushing a locally built arm64 image to an amd64 server, produces:

This has nothing to do with Java — Docker failed while trying to execute the ENTRYPOINT binary: the image carries a linux/arm64 java, the host kernel is linux/amd64, the instruction sets differ and the loader refuses. Three self-rescue routes:

• Declare the platform at build time: docker buildx build --platform linux/amd64 -t bee-app:1.0 .
• Declare it at run time (only on machines with qemu emulation — slow and unstable): docker run --platform linux/amd64 bee-app:1.0
• Produce both architectures in CI: docker buildx bake, or multiple --platform linux/amd64,linux/arm64 values plus a manifest push

One command is enough to investigate — read the image's own architecture rather than your machine's:

Article 36 covered the six actions of a graceful shutdown; the premise is that the JVM actually received that signal. In a container the easiest link to break is exactly this one.

The fork sits at frames 2 and 3:

• exec (JSON array) form: ENTRYPOINT ["java","-jar","app.jar"] — java itself is PID 1, SIGTERM reaches the JVM directly and the shutdown hooks run as usual
• shell form: ENTRYPOINT java -jar app.jar — what actually starts is /bin/sh -c "java -jar app.jar", so the shell is what occupies slot 1; /bin/sh does not forward received signals by default, so none of your graceful-shutdown configuration executes and the process is hard-killed by SIGKILL ten seconds later

The symptom is remarkably fixed: not one shutdown-related line in the log, yet the container did stop cleanly. Three fixes — use the exec form; or keep the shell form and write ENTRYPOINT exec java -jar app.jar; or let tini / dumb-init act as PID 1 to manage signals and reap zombies.

Align both sides too: if Spring's server.shutdown=graceful plus spring.lifecycle.timeout-per-shutdown-phase waits 30 seconds while Docker's grace period is the 10-second default, the last 20 seconds of requests are severed anyway.

The verification method is crude but the most effective: run docker stop -t 30 bee-app in one shell and docker logs -f bee-app in another; you only pass if you can see Closing org.springframework.... This experiment walks the whole signal path — focus on the fork at frames 2 and 3:

Container environment variables and conditional wiring are the same idea: one codebase assembling different results per environment. This demo runs the IoC container's condition switches — just like toggling container env vars.

• Flip switches like @ConditionalOnProperty and watch which beans are registered
• Container env vars (such as DB_HOST) bind via Spring's @ConfigurationProperties and ultimately affect wiring
• Grasp this and you grasp the mechanism behind "one image, many environments"

With images, containers and the app itself covered, one layer of verification is left: the command line. This console is wired to the same Java kernel in your browser — start with whoami, then type the lab experiments from this section one by one; every line comes back computed by the kernel itself:

All of the above finally lands on one real rolling release: the new container takes over while the old one retires, and users must not feel the hiccup in between. Retiring an old container is not "kill the process" but three things happening in order — stop receiving traffic, finish the in-flight requests, then exit. Docker only owns half of the first step; the rest belongs to the application and the orchestrator.

The two Actuator probe endpoints from Article 42 have completely different semantics, and mixing them up causes "the database wobbles and the whole fleet restarts":

• /actuator/health/liveness answers "does this process still have hope" — it should only judge the process itself; misconfiguring it causes restart loops
• /actuator/health/readiness answers "can I take traffic now" — when a dependency is unhealthy this is what should pull you out of the load balancer, not kill the process

• Align the grace period: K8s's terminationGracePeriodSeconds (30s by default) must exceed Spring's spring.lifecycle.timeout-per-shutdown-phase, otherwise you are SIGKILLed halfway through waiting
• The preStop sleep is not mysticism: endpoint updates propagate with delay, so an old instance may still receive new requests the instant SIGTERM arrives — the convention is to sleep 2~5 before starting to wind down
• docker stop -t is the same story: locally or under Compose there is no preStop, and the only knob is -t; the trap in Section 5 is exactly this

Every "error text" below can be pasted into a search engine as-is — no paraphrasing, no abbreviating. The three places beginners get stuck most: the entrypoint script that will not run, the port that will not bind, and the memory limit nobody configured correctly.

Row five of the error table above (OutOfMemoryError: Java heap space) looks a lot like row one (137) and yet is a completely different scene. The stack below is real; don't peek at the answer — click the line you blame, then read the boundary between the two failure modes:

A warm-up on the caching rule from Section 2:

Then a comprehensive one, tying 8.3, 10.6 and Section 13 together:

"Just raise the limit" is the most expensive form of comfort in container debugging — it removes the symptom while ensuring you never learn who was eating the memory. The sandbox below turns heap ratio and container limit into two switches; flipping one shows the computed default heap, where total usage lands, and which failure you end up with:

Goal: starting from an empty directory, produce an image with "multi-stage build + layered COPY + limit awareness + exec-form entry point", then bring it up together with MySQL via Compose. Every step has an expected output; stop and check when it does not match.

Create three files: pom.xml, .dockerignore and src/main/java/com/example/lab/LabApplication.java. The pom.xml needs layered extraction enabled, because that is the precondition for the four-layer COPY later:

.dockerignore — without this line, tens of seconds of context upload are wasted:

The minimal application, with one endpoint that reports what the JVM believes its heap is:

The Dockerfile — multi-stage, layered, exec entry point, proportional heap:

Build and watch the cache:

Expected output (the key is how many layers print CACHED):

Run it with a limit and check your arithmetic against Section 8.3:

Expected response:

384 is exactly 75% of 512, proving MaxRAMPercentage took effect. If you read a large fraction of the host's physical memory instead, your base image JDK is too old and UseContainerSupport is off.

Edit one line of business code and rebuild to confirm the dependency layer is still CACHED:

Expected: the build-stage line RUN mvn -B dependency:go-offline still prints CACHED, and only the layers after COPY src rerun. If you see dependencies downloading again, go back to Section 2.1 and re-check the instruction order.

Verify that graceful shutdown really reaches the JVM:

You should see a line like Closing org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.... If not, return to Section 10.6 and inspect the form of your ENTRYPOINT.

Finally, settle it as Compose (docker-compose.yml, next to the Dockerfile):

Expected: app is running and mysql is healthy; the PORTS column for app must contain 0.0.0.0:8080->8080/tcp — if it does not, Section 7 lost its ports.

Acceptance checklist: ① explain why the dependency layer still hits the cache in the second build (the Section 2 rule);② where does the 384MB come from in your curl;③ what does docker inspect lab --format '{{.State.ExitCode}} {{.State.OOMKilled}}' return after your manual docker stop, and why is it not 137 True.

Change exactly one thing and watch the conclusion flip:

1. Turn ENTRYPOINT into shell form, ENTRYPOINT java -jar app.jar (dropping the JSON array). You will observe: docker stop -t 30 lab still ends after about ten seconds, and the log contains no Closing ... at all — the signal swallowed by the shell as described in 10.6. Then run docker exec lab ps -ef and look at who occupies slot 1: it is sh.
2. Delete the target/ line from .dockerignore, run mvn package locally, then docker build. You will observe: transferring context at the start of the build grows from a few hundred KB to tens of MB and takes noticeably longer; and any change outside COPY src ./src invalidates the layers above. That is "the context is a cost too".
3. Change -m 512m to -m 256m without touching JAVA_TOOL_OPTIONS. You will observe: curl becomes connection-refused, docker inspect reports OOMKilled true with Exit Code 137, and the last line of docker logs is still the normal startup banner — a perfect sample of "external execution, no evidence". Now drop the ratio to 50 and try again: the symptom flips from 137 to an in-heap error the log can record.
4. Switch the base image to eclipse-temurin:21-jre-alpine. You will observe: the image does shrink by about 20MB, but if you connect by service name rather than IP you may hit sporadic resolution failures — compare the Section 9 tip with frame 4 of the build experiment.

After finishing item 1, go back to the Section 16 sandbox: set policy to fixed-xmx and limit to 512m; the two conclusions should line up.

Give yourself a "one-command reproducible environment plus a release health check", so that anyone who receives the repository can run it without asking you a single question.

Requirements:

• One compose.yaml with three services — mysql (with healthcheck and init SQL), redis (persisted by a named volume), app (depends_on: condition: service_healthy) — all declaring explicit memory limits
• The app Dockerfile must satisfy all of: multi-stage, .dockerignore, four-layer layertools COPY, exec-form entry point, MaxRAMPercentage rather than -Xmx, non-root user (USER app)
• A Makefile with at least four targets: make build, make up, make smoke (curl the health endpoint plus /hello, exit non-zero if either fails), make graceful-test (background docker stop -t 30 while docker logs -f scrapes the shutdown output; the assertion must see Closing, otherwise it reports "the signal never reached the JVM" and exits non-zero)
• A "memory budget table" in your README: the ratio you picked, the resulting heap size, Metaspace, thread count × -Xss, your direct-memory estimate, and why the sum stays under the limit

Acceptance checklist: ① make up && make smoke is all green on a brand-new machine;② if you deliberately make one bean's constructor throw, make smoke must fail rather than hang;③ make graceful-test passes with the exec form and fails after you switch the entry point to shell form (proving the script really catches regressions);④ the final image is under 300MB in docker images, and docker inspect --format '{{.Os}}/{{.Architecture}}' matches the deployment target;⑤ explain "why does docker stop end with ExitCode 143 rather than 137".