CicloUrbana is observable, knows which environment it lives in and works on its own. And it is still a JAR that somebody has to start by hand on a machine with Java 21 installed, the right time zone and the environment variables correctly set. That "somebody" and those conditions are the last hand-crafted link in the project: the reason it works on one server and not on another, and the reason deployment depends on a list of steps in one person's head.

This lesson removes it by packaging the application, its JRE and its configuration into a reproducible container image. We will look at why the Dockerfile everybody writes first is wrong, how to exploit Spring Boot's layered JAR so that rebuilding after changing one line takes seconds, which base image to choose, the buildpacks alternative, how the JVM behaves inside a container, the complete docker-compose.yml of the Ribalta network with PostgreSQL and its health checks wired to the probes from 07-01, and the security practices that stop you publishing an image with secrets inside it.

1. Why containerise
2. The minimum Docker concepts
3. The naive Dockerfile and why it is wrong
4. Spring Boot's layered JAR
5. CicloUrbana's multi-stage Dockerfile
6. Choosing the base image
7. Buildpacks: spring-boot:build-image
8. The JVM inside a container
9. The Ribalta network's docker-compose.yml
10. Configuring the application in the container
11. spring-boot-docker-compose for development
12. Native images with GraalVM
13. Image security
14. Publishing to a registry and tagging
15. Common Mistakes and Tips
16. Exercises

A container packages the application and everything it needs in order to run — the JRE, the system libraries, the default configuration, the time zone — into a single immutable artefact. What it solves, concretely:

And a strategic consequence: the image is the unit understood by Kubernetes (08-04), AWS managed services (08-03) and continuous delivery pipelines (08-05). Containerising is not an end in itself; it is the prerequisite for everything that comes next.

It is worth being honest about what it does not solve. A container does not isolate like a virtual machine — it shares the host's kernel — it does not fix an application with state on local disk, and it does not make bad configuration good: if the prod profile is not activated, it will be just as unactivated inside the container as outside it (07-02).

The key idea of the whole chapter is layers. An image is a stack of read-only layers; when rebuilding, Docker reuses from the cache every layer before the first change and redoes only the ones after it. And when publishing, only the layers the registry does not already have are transferred. The whole of the optimisation in section 4 consists of putting what rarely changes at the bottom and what changes often at the top.

This is the file almost everybody writes first:

It works. And it has five serious problems:

The first is the one that hurts most day to day. In a normal development cycle the dependencies change once a month and the code changes twenty times a day; with a monolithic JAR, each of those twenty changes rebuilds and transfers the whole of Spring Framework, Hibernate, Jackson and the PostgreSQL driver.

Spring Boot solves the problem by publishing the JAR already split into layers ordered from least to most volatile:

It is inspected and extracted with the JAR's own jarmode. In Spring Boot 3.3 and later:

In earlier versions the mode was called layertools (java -Djarmode=layertools -jar app.jar extract); the concept is identical and it is worth knowing both names, because the documentation and the examples in circulation mix the two.

The result is a directory tree, one per layer, which are copied into the image in order. Since the application layer weighs a few hundred kilobytes and goes last, a code change rebuilds only that one: the build-and-publish cycle drops from minutes to seconds.

The decisions, one by one:

• Two stages. The first brings in Maven and the full JDK; the second starts from an image with only the JRE. The final image contains no Maven, no JDK, no source code and no .m2 repository: it goes from around 800 MB to around 200.
• COPY pom.xml before COPY src. This is the central trick: as long as the POM does not change, the dependency:go-offline layer comes from the cache and the dependency download is skipped entirely. Copying everything together would make any code change download the whole internet again.
• -DskipTests is correct here, even though it sounds like heresy after module 6: the tests already ran in the pipeline (08-05) before the image was built. Running them again inside the container doubles the time and, with Testcontainers, would require Docker inside Docker.
• extract --layers produces the four directories from the previous section.
• Unprivileged user. addgroup/adduser is the Alpine syntax; on Debian-based images it would be groupadd/useradd. The --chown on each COPY avoids an extra layer just to change permissions.
• The four COPY instructions in that exact order. This is where the whole optimisation materialises: a change in RentalService only invalidates the last one.
• EXPOSE 8080 8081 documents the API port and the management port from 07-01. It is informative; on its own it opens nothing.
• TZ=Europe/Madrid avoids the time zone problem from 07-03: without it, a container runs in UTC and the nightly cron shifts.
• ENTRYPOINT in list form, not as a string. The string form starts the process under a sh -c, which stays as PID 1 and does not forward signals: the SIGTERM of the graceful shutdown (01-05, 07-03) never reaches the JVM and the container dies abruptly after ten seconds.

Building and running:

The warning about Alpine. Alpine uses musl as its C library instead of glibc. Most Java applications work without any trouble, but there are two problem areas: libraries with native code (some cryptographic clients, compressors, netty-tcnative) may fail or perform worse, and certain DNS and name resolution scenarios behave differently. If the alpine image works with CicloUrbana's test suite run inside the container, go ahead; if a strange native error turns up, this should be your first hypothesis.

About distroless: it has no shell, so docker exec -it ... sh does not work. That is exactly what makes it secure — an attacker who gains execution has no shell either — and what makes it awkward to debug. It is the right choice when diagnostics are done through Actuator and centralised logs (09-05), which is precisely where this course is heading.

Spring Boot can build the image with no Dockerfile at all, using Cloud Native Buildpacks:

The plugin inspects the project, detects that it is a Java application, picks a suitable JRE, applies layers by itself, creates an unprivileged user and adds calculated memory settings. The result is an OCI image ready to run.

The honest recommendation: if the team has no Docker experience and wants best practices by default, buildpacks. If it needs fine control — a native library, an approved corporate base image, a specific vulnerability scan — the Dockerfile from section 5. Both paths are legitimate and both produce correct images; what is not legitimate is the naive Dockerfile from section 3.

There was a time when the JVM could not see the container's limits: it read the host machine's memory, sized the heap at a quarter of those 64 GB and the orchestrator killed the process for exceeding its 512 MB limit. That has been solved since Java 10: UseContainerSupport is on by default and the JVM reads the cgroups. There is no need to enable it.

What you do have to understand is how memory is divided up. -Xmx sets an absolute number that has to be revisited every time the container's limit changes; MaxRAMPercentage sets a proportion of the limit and adapts on its own:

Why 75 and not 100. A JVM does not consume only heap: there is metaspace, thread stacks, direct buffers, compiled code and the operating system itself. Leaving a 25 % margin stops the orchestrator killing the container with OOMKilled — a failure that is also hard to diagnose, because it leaves no trace in the application log.

JAVA_TOOL_OPTIONS is the variable to use, rather than putting the options in the ENTRYPOINT, for two reasons: the JVM reads it automatically, and it can be overridden when starting the container without rebuilding the image. Startup itself records it in the log (Picked up JAVA_TOOL_OPTIONS: ...), which serves as confirmation.

In 04-02 we created a docker-compose.yml with PostgreSQL only. Now it is completed with the application:

The points to understand:

• depends_on with condition: service_healthy stops the application starting until PostgreSQL answers pg_isready. Without that condition, depends_on only guarantees the start order, not that the service is ready, and CicloUrbana would fail to connect and enter a restart loop.
• ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is missing} makes docker compose up fail immediately if the variable is not defined, instead of starting with an empty string. It is the same fail-early philosophy as 07-02.
• The URL points at postgres, not at localhost. Inside the Compose network, each service is reachable by name thanks to the internal DNS. localhost inside the application's container is the container itself.
• 127.0.0.1:8081:8081 publishes the management port on the host only, not on every interface. It is the Docker translation of the practice from 07-01: Actuator never reachable from outside.
• The application's healthcheck queries /actuator/health/readiness, the probe we wrote in 07-01. Here you can see why it was called "the piece the orchestrator needs": it is exactly the same mechanism Kubernetes will use in 08-04.
• start_period: 45s gives Spring's startup room — context, Flyway, pool — without the failures in that window counting as retries.
• limits.memory: 1g is what gives MaxRAMPercentage=75 its meaning: with no declared limit, the percentage is computed against the host's memory.

The secrets live in a .env file next to the docker-compose.yml and outside Git:

A committed .env is the same mistake as an application-prod.yml with credentials (07-02), made worse by the fact that it looks like a harmless infrastructure file. And it is worth knowing that a container's environment variables are visible through docker inspect to anyone who can talk to the Docker daemon: for real secrets, production uses the orchestrator's secrets mounted as files and read with spring.config.import: optional:configtree:/run/secrets/ (07-02).

The rule is factor III of the 12-Factor App, already applied in 07-02: configuration comes from the environment. Inside a container that means the image is identical in every environment and the only thing that changes is the variables:

The profile is never baked into the image. Writing ENV SPRING_PROFILES_ACTIVE=prod in the Dockerfile produces an image that is only good for production and breaks the principle from 07-02: the image tested in pre-production would no longer be the one deployed. The profile is decided at run time.

When the configuration is too large for variables, a file is mounted:

Spring finds it on its own, because ./config/ next to the JAR is one of the locations in the chain from 07-02, and :ro mounts it read-only.

And about shutdown: Docker sends SIGTERM and waits ten seconds before the SIGKILL. Since the application has a graceful shutdown with up to forty seconds of waiting (07-03), that window has to be widened or the container will die mid-request:

In 06-05 we met the module that starts the docker-compose.yml services alongside the application in development:

When you run ./mvnw spring-boot:run, Spring brings up the declared services, detects PostgreSQL and configures spring.datasource.* on its own with the assigned port — just as @ServiceConnection did in the tests — and stops them when the application stops. Anyone who clones CicloUrbana needs to install nothing and remember no preliminary command.

Two precautions. The file it points at must be a development one (compose-dev.yml, with PostgreSQL only), not the production docker-compose.yml that also builds and starts the application itself: that would produce two CicloUrbanas fighting over port 8080. And lifecycle-management: start-only is preferable if it is annoying to have the containers stop every time, at the cost of having to stop them by hand.

GraalVM compiles the application ahead of time into a native executable, with no JVM at run time:

Where it shines: serverless functions, scale to zero, very frequent startups, environments where memory is expensive. Where it does not pay off: an application like CicloUrbana, which starts once and runs for weeks, gains little and pays a ten-minute compilation on every build.

The technical obstacle is reflection: ahead-of-time compilation needs to know at build time every class that will be instantiated dynamically. Spring Boot 3 generates a large part of that metadata automatically, but your own code that uses reflection must declare it with RuntimeHints:

It is worth knowing about and worth knowing it exists; for CicloUrbana, the JRE image from section 5 is the right choice today.

An image is an artefact that gets published and distributed. Everything that goes into it goes in forever: deleting a file in a later layer does not remove it from the earlier one, it is still there and can be extracted.

The .dockerignore is more important than it looks. Without it, COPY . . puts the entire .git directory inside the image — with the whole history, including the secrets somebody committed and deleted afterwards — and also the .env we took such care not to commit. On top of that, the entire build context is transferred to the Docker daemon, which slows down every build.

And a warning about secrets during the build: ARG TOKEN followed by a RUN that uses it leaves the value in the image's metadata, visible with docker history. For credentials during the build there is RUN --mount=type=secret, which persists nothing in the layers.

The tagging policy decides whether a deployment is reproducible:

The rule: always deploy by version or by commit, never by latest. With the sha-9f3a2b1 tag and /actuator/info from 07-01 returning that same hash, the question "what is running in Ribalta?" has an exact, verifiable answer. In 08-05 this tagging is generated automatically by the pipeline.

COPY . . before resolving the dependencies. Every code change downloads the whole Maven repository again. The pom.xml first, the src afterwards.

The JAR as a single layer. Changing one line invalidates 60 MB. Extract the layers with the jarmode.

Running as root. It is the default and it has to be changed explicitly.

ENTRYPOINT in string form. The intermediate sh -c swallows the SIGTERM and the graceful shutdown never happens.

depends_on without condition: service_healthy. It guarantees the start order, not that the database is ready.

Using localhost in the database URL inside the container. Every container has its own localhost; you have to use the service name.

Not declaring a memory limit. MaxRAMPercentage is computed against the host's memory and the container ends up OOMKilled.

Baking SPRING_PROFILES_ACTIVE=prod into the image. The image stops being the same one in every environment and the principle from 07-02 is broken.

Committing the .env or having no .dockerignore. Both put secrets where they must not be: in Git or inside the image's layers.

Tip: pin the versions of every base image, and schedule periodic rebuilds so that the base's security patches are picked up.

Tip: test the image, not just the JAR. Starting the container and querying /actuator/health/readiness in the pipeline catches time zone, permission and variable problems that no JVM test can see.

Tip: measure the rebuild time. If changing one line takes more than thirty seconds to produce a new image, the layer order is wrong.

Find every problem in this file, explain the consequence of each one and write the corrected version.

Write a compose-pre.yml for the council's pre-production environment with: PostgreSQL 16 with a volume and a health check; CicloUrbana on the pre profile, limited to 1 GB, waiting for the database to be healthy, with the management port reachable from the host only and its own health check against readiness; secrets from .env; and a shutdown grace period consistent with the 40 seconds from section 13 of 07-03. Explain the order in which everything starts and what happens if PostgreSQL takes a minute to become ready.

The team complains that changing one line in StationService and seeing the result in a container takes four minutes. The Dockerfile is multi-stage and correct apart from the build stage:

Diagnose the problem, propose the fix and estimate roughly how long it should take afterwards. Also say what else you would check if it still took more than a minute after the fix.

Solution 1

Nine problems:

The fix is the Dockerfile from section 5, with two qualifications about the exercise. The password is not passed at build time in any form: it is runtime configuration and is injected as a variable when the container starts; if a credential really were needed during the build — for a private Maven repository, say — the correct form is RUN --mount=type=secret,id=maven, which leaves no trace in the layers. And the profile disappears from the Dockerfile entirely, moving to docker run -e SPRING_PROFILES_ACTIVE=... or to Compose.

Solution 2

Start order. Compose creates the network and the volume; it starts postgres; during the first 20 seconds (start_period) the pg_isready failures do not count; when it answers, the service becomes healthy; only then does app start, resolving postgres over the internal DNS, applying the Flyway migrations and bringing up the context; for 45 seconds its own healthcheck does not penalise it, and once it answers /actuator/health/readiness with 200 the service becomes healthy and can receive traffic.

If PostgreSQL takes a minute, the behaviour is still correct: with interval: 10s, retries: 6 and start_period: 20s there is enough margin and app simply waits. If it exceeded that margin, PostgreSQL would be marked unhealthy, app would not start at all — which is the desired behaviour: better not to start than to start without a database — and docker compose ps would show clearly which service is failing.

stop_grace_period: 50s is the piece that makes the shutdown chain coherent: the application needs up to 40 seconds to finish requests and drain the executors (07-03), so giving it only Docker's default 10 seconds would cut the graceful shutdown right in half. The general rule is stop_grace_period > timeout-per-shutdown-phase > await-termination-period.

Solution 3

The diagnosis. COPY . . copies the code before resolving the dependencies, so the layer that runs mvn package is invalidated by any file change. Docker cannot reuse anything: every build downloads the whole Maven dependency tree again — Spring Boot, Hibernate, Jackson, Spring Security, JJWT, MapStruct, the drivers — from scratch. Those four minutes are, almost entirely, repeated downloads of artefacts that were already downloaded yesterday.

The fix is to split the copy into two steps, with the dependency resolution in between:

Now a change in StationService invalidates the COPY src layer and the ones after it, but the dependencies layer comes from the cache. The time drops to however long compiling plus packaging takes: between twenty and forty seconds on a project the size of CicloUrbana. And since the final image's dependencies and spring-boot-loader layers do not change either, publishing to the registry transfers a few hundred kilobytes instead of sixty megabytes.

If it still took more than a minute after the fix, there are four things to check, in this order:

1. Are the tests running? Without -DskipTests, mvn package runs the whole module 6 suite, Testcontainers included, which would need Docker inside Docker. Tests belong in the pipeline, before building the image.
2. Is there a .dockerignore? Without one, the build context includes .git and target/, and transferring them to the daemon before starting can take tens of seconds.
3. Is the cache being invalidated some other way? A COPY of a file that always changes — a timestamp, a generated file — above the dependencies stage has the same effect as the original problem.
4. Does the cache exist at all? In continuous integration, each run usually starts on a clean machine with no layer cache; there the answer is a layer cache of its own (--cache-from, cache-to) or a persistent volume for the .m2 repository via RUN --mount=type=cache,target=/root/.m2, which is the modern form and the one that works best in pipelines (08-05).

CicloUrbana is no longer a JAR that somebody starts by hand: it is a reproducible image that runs identically on a developer's laptop, on the pre-production server and on the Ribalta council's infrastructure. You know what a container solves and what it does not, and you handle the concepts that underpin it — image, layer, container, registry, tag, volume, network — with the central idea that layers are cached and that this is why what rarely changes goes at the bottom and what changes often goes at the top.

You know why the three-line Dockerfile is wrong — monolithic layer, dependence on the local Maven, root, a fat image, signals that never arrive — and you have written the one that is right: multi-stage, with the pom.xml copied before the src so the dependencies come from the cache, with the JAR split into its four layers by the tools jarmode, with an unprivileged user, a fixed time zone, memory settings through JAVA_TOOL_OPTIONS and an ENTRYPOINT in list form that does let SIGTERM reach the graceful shutdown. You know the base images and their trade-offs, including the warning about musl on Alpine and the price of distroless, and you know there is a path with no Dockerfile — the buildpacks of spring-boot:build-image, with pack rebase to patch the base without recompiling — along with clear criteria for choosing between the two.

You understand how the JVM behaves inside a container: UseContainerSupport no longer needs enabling, but MaxRAMPercentage=75 does, and that 25 % margin is what avoids the silent OOMKilled. You have the complete docker-compose.yml of the Ribalta network, with PostgreSQL 16, a named volume, its own network, depends_on: condition: service_healthy, the management port published only on 127.0.0.1, secrets in a .env outside Git and — the piece that links this lesson to the module's first — a HEALTHCHECK that queries /actuator/health/readiness. You know how to configure the application from the environment without ever baking the profile into the image, how to mount an external read-only YAML and how to widen stop_grace_period so that the graceful shutdown fits. And you have spring-boot-docker-compose bringing up the database in development, the overview of GraalVM with its real timings and its RuntimeHints, the list of image security practices — non-root user, minimal base, zero secrets in layers, .dockerignore, scanning with docker scout or Trivy — and a tagging policy that makes it verifiable which version is running in Ribalta.

Up to here, everything we have built is a single application: a well-made monolith, tested, observable, configurable and now containerised. It is a perfectly respectable architecture and, for a municipal bike network, probably the correct one. But sooner or later somebody asks the question: what if the billing module had its own lifecycle? What if the stations team deployed without coordinating with the rentals team? What if we had to scale only the part that queries availability, which gets a hundred times more traffic than the rest? The next lesson, Spring Boot and Microservices, answers those questions honestly: what problem microservices really solve, what you pay for them, how you decide where to cut, what breaks when each service has its own database, and why the first correct answer is nearly always modularise the monolith.