Docker

In Hands-on 1 you run the account service with mvn spring-boot:run. That works because your laptop has the right JDK, Maven and environment variables. To run the same service on a colleague's machine, a CI server or a cloud VM, you would have to reproduce that whole setup by hand — and keep it in sync forever. Docker turns the setup into a file (the Dockerfile) and the result into an artifact (the image) that runs the same way everywhere.

Docker is a platform for building, shipping, and running applications in containers¹. It standardises the packaging of an application and all its dependencies — runtime, libraries, environment variables, configuration — into a single portable unit that runs identically on any machine with the Docker Engine installed.

Core concepts

flowchart LR
  df[Dockerfile] -->|docker build| img[Image]
  img -->|docker run| c1[Container A]
  img -->|docker run| c2[Container B]
  img -->|docker push| reg[(Registry\nDocker Hub)]
  reg -->|docker pull| img2[Image on\nanother host]

Dockerfile : A text file containing step-by-step instructions for building an image. Each instruction that changes the filesystem (RUN, COPY, ADD) creates a new read-only layer.

Image : An immutable snapshot built from a Dockerfile. Images are the artifact that gets versioned, pushed to a registry, and shipped. An image is identified by a name and a tag (eclipse-temurin:25-jre-alpine, store/account:1.0); when you omit the tag, Docker assumes latest.

Container : A running instance of an image. Containers are isolated processes on the host OS — they share the kernel but have their own filesystem, network, and process namespace (see What a container really is).

Registry : A server that stores and distributes images. Docker Hub³ is the default public registry. Private registries (AWS ECR, GitHub Container Registry, GitLab Registry) are used for proprietary images.

How Docker works: client, daemon, registry

The docker command you type is only a client. It sends each request to the Docker daemon (dockerd), a background service that builds images, pulls them from registries and asks the container runtime (containerd, which uses runc) to start the actual processes.

flowchart LR
    cli["docker CLI"] -->|REST API| daemon["dockerd daemon"]
    daemon -->|pull image| reg[(Registry)]
    daemon -->|create container| rt["containerd + runc"]
    rt -->|start process| proc["container process"]

This is why docker ps fails with "Cannot connect to the Docker daemon" when Docker Desktop is not running: the client is fine, but nobody is listening on the other side.

Dockerfile

A Dockerfile defines the environment the application runs in. Each instruction adds a layer to the image²:

# Base image — choose the smallest that fits
FROM eclipse-temurin:25-jre-alpine

# Working directory inside the container
WORKDIR /app

# Copy the built artifact from the host (run `mvn package` first)
COPY target/*.jar app.jar

# Expose the port the application listens on (documentation only)
EXPOSE 8080

# Command to run when the container starts
ENTRYPOINT ["java", "-jar", "app.jar"]

The Dockerfile used for the store's services in Hands-on 1 follows the same pattern: a Java 25 base image, the JAR built by Maven, and java -jar as entry point.

The instructions you will use most often:

.dockerignore

docker build . sends the whole directory (the build context) to the daemon. A .dockerignore file keeps out what the image does not need — making builds faster and preventing secrets from ending up in a layer:

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

Multi-stage builds

Multi-stage builds separate the build environment from the runtime environment, producing a smaller final image. They also remove the need to have Maven and a JDK installed on the machine that builds the image:

# Stage 1: build
FROM maven:3.9-eclipse-temurin-25 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline          # cache dependencies separately
COPY src ./src
RUN mvn package -DskipTests

# Stage 2: run — only the JRE, no Maven, no source
FROM eclipse-temurin:25-jre-alpine
WORKDIR /app
COPY --from=builder /build/target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

The final image contains only the JRE and the compiled JAR — Maven and the source tree are discarded.

Layer caching

Docker builds images layer by layer. If a layer has not changed since the last build, Docker reuses the cached version — skipping that step entirely. Once a layer changes, that layer and every layer after it are rebuilt. Layer order matters: place instructions that change infrequently (dependencies) before instructions that change often (source code).

flowchart LR
    subgraph bad [Poor order — cache busted on every code change]
        direction TB
        b1["COPY src ./src\n(changes every commit)"]:::changed --> b2["RUN mvn package"]:::changed --> b3["RUN mvn dependency:go-offline"]:::changed
    end
    subgraph good [Good order — dependencies cached separately]
        direction TB
        g1["COPY pom.xml ."]:::cached --> g2["RUN mvn dependency:go-offline"]:::cached --> g3["COPY src ./src\n(changes every commit)"]:::changed --> g4["RUN mvn package\n(only rebuilds app)"]:::changed
    end
    classDef cached fill:#6c6,color:#fff
    classDef changed fill:#f66,color:#fff

The multi-stage Dockerfile above already exploits this: RUN mvn dependency:go-offline runs only when pom.xml changes, not on every code change.

Essential commands

Managing containers

Managing images

Housekeeping

docker ps -a                    # STATUS shows "Exited (1) 3 seconds ago"
docker logs account             # the application's own error message (e.g. cannot reach the database)
docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}}' account   # 137 + true = killed for memory
docker run -it --rm --entrypoint sh store/account:1.0                 # open a shell in the image to look around

Networking

Each container gets its own network namespace — its own IP address and its own localhost. Docker provides several network drivers⁴:

docker network create store-net
docker run -d --name db --network store-net -e POSTGRES_PASSWORD=secret postgres:17
docker run --rm --network store-net postgres:17 pg_isready -h db   # "db" resolves to the database container

When using Docker Compose, all services are attached to a user-defined network that Compose creates automatically, so they can reach each other by their service name as the hostname (Docker Compose).

Volumes

Containers are ephemeral — data written inside a container is lost when the container is removed. Volumes persist data beyond the container lifecycle:

# Named volume (managed by Docker)
docker run -v mydata:/var/lib/postgresql/data postgres:17

# Bind mount (maps a host directory)
docker run -v /host/path:/container/path myapp

Named volumes are preferred in production because Docker manages their location. Bind mounts are useful during development to reflect local file changes without rebuilding the image.

Good practices and pitfalls

Connections

• Hands-on 1 — Containerization — the account service's Dockerfile and its Compose file.
• Docker Compose — running several containers together.
• Hands-on 4 — Jenkins builds and pushes images in a pipeline.
• Hands-on 5 — Kubernetes runs these images across a cluster.

Key takeaways

• The docker CLI talks to a daemon that builds images, pulls them from registries and starts containers through containerd/runc.
• A Dockerfile is a recipe; each filesystem-changing instruction is a cached layer — put dependencies before source code.
• Multi-stage builds keep Maven and the sources out of the final image; ENTRYPOINT in exec form lets the JVM shut down gracefully.
• Publish ports with -p host:container; containers on a user-defined network find each other by name, and localhost means the container itself.
• Containers are disposable: keep data in volumes, configuration in environment variables, and pin image versions.