Docker

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production; see the section bibliography for the reference material consulted while preparing these pages.

Welcome to the Docker reference. Docker packages an application with everything it needs to run into an image — a stack of read-only filesystem layers plus a configuration, standardised by the Open Container Initiative — and runs that image as an isolated process called a container on any host with a container engine. The same image is built once, tested, pushed to a registry and pulled unchanged into every environment, from a developer laptop through CI to production, which is why Docker has become the default unit of packaging and deployment for backend services.

The examples in this section are written and verified against Docker Engine 29.8.x, Docker Compose v5.5.x, Buildx 0.37.x with BuildKit 0.33.x and the docker/dockerfile:1 frontend, and Docker Desktop 4.91 or later; the Java pages add Testcontainers for Java 2.0.5, Spring Boot 4.1.x and Java 25, and the CI pages use the current majors of the official GitHub Actions (actions/checkout@v7, actions/setup-java@v6, docker/* actions such as docker/build-push-action@v7).

New here? Read in this order: Getting Started with Docker, then Docker Architecture and the OCI, Images, Layers and Tags and Dockerfile Fundamentals; next Running Containers, followed by Storage and Networking; then Docker Compose Fundamentals; and finally the Java and Spring Boot pages, starting with Java and Spring Boot Images and ending with Spring Boot Integration Tests with Testcontainers.

What’s covered

Foundations

Getting Started with Docker — the problem Docker solves and what it is not, containers vs. virtual machines, the platform map, installing Docker Desktop or Docker Engine, the first commands, contexts, and the version history behind older books.
Docker Architecture and the OCI — the CLI, the Engine API and its socket, dockerd, containerd, the shim and runc, API versioning, BuildKit, the OCI image, runtime and distribution specifications, namespaces, cgroups v2, storage drivers vs. the containerd image store, Docker Desktop’s VM and alternative runtimes.
Images, Layers and Tags — layers and copy-on-write, image references, tags vs. digests, manifest lists, the image commands, save/load, and labels vs. annotations.

Building images

Dockerfile Fundamentals — every instruction, parser directives, CMD vs. ENTRYPOINT, COPY vs. ADD, ENV vs. ARG, here-documents, the build context, .dockerignore and docker build.
Build Cache and Multi-Stage Builds — cache invalidation, instruction ordering, RUN --mount caches, secrets and SSH, multi-stage builds and base-image choice.
BuildKit and Buildx — builders and drivers, multi-platform builds, exporters, remote caches, build checks, SBOM and provenance attestations, Bake and build policies.
Image Best Practices and Supply-Chain Security — the building best practices with reasons, build secrets, reproducible builds, linting, Docker Scout, Docker Hardened Images, and provenance and signing.

Running containers

Running Containers — the lifecycle, docker run options, the everyday container commands, signals, exit codes and graceful shutdown, and restart policies.
Storage: Volumes, Bind Mounts and tmpfs — volumes, bind mounts, tmpfs and image mounts, backups, and Docker Desktop file sharing.
Networking — network drivers, user-defined bridges and DNS, port publishing, reaching the host, IPv6, iptables/nftables and firewalls.
Resources, Logging and Monitoring — cgroup limits, OOM behaviour and the JVM, logging drivers and rotation, docker stats/events, and Prometheus metrics.
Debugging Containers — the debugging toolbox, docker debug, namespace-sharing sidecars, daemon logs and a table of common failures.

Compose

Docker Compose Fundamentals — Compose and the Compose Specification, the application model, service essentials, startup order, interpolation and the CLI.
Compose in Practice — multiple files, profiles, Compose Watch, lifecycle hooks, secrets, provider services, models, Compose Bridge, OCI artifacts, production and the trust model.

Registries and distribution

Registries and Docker Hub — the OCI distribution API, Docker Hub, access tokens and pull limits, pushing, cloud registries, a private registry with CNCF Distribution, and OCI artifacts.

Security

Docker Security — the threat model, protecting the daemon, rootless mode, user namespaces, capabilities, seccomp, AppArmor/SELinux, run-time hardening, secrets and a consolidated checklist.

Orchestration and beyond

Orchestration: Swarm Mode and Kubernetes — when one host is not enough, Swarm mode in summary, Kubernetes as the default, and the Twelve-Factor recap.

Docker in the Java and Spring Boot development loop

Java and Spring Boot Images — a layered multi-stage Dockerfile, Cloud Native Buildpacks with spring-boot:build-image, and Jib.
Compose for Local Development — the house compose.yaml and Spring Boot’s Docker Compose support with every spring.docker.compose.* property.
Testcontainers Fundamentals — how Testcontainers uses Docker, the 2.0 artifact model, GenericContainer, wait strategies, lifecycles, ComposeContainer and modules.
Spring Boot Integration Tests with Testcontainers (Locally and in GitHub Actions) — the three wiring options, the house shared-Compose harness, running locally and in GitHub Actions, and a complete worked example.
Docker CI/CD with GitHub Actions — the docker/* actions, tags and caching, test-before-push, multi-platform images, Scout gates and the house deploy.yml.

Other framework bindings

Quarkus: Container Images — the Quarkus counterpart of the Java images page (Jib, Docker, Buildpacks and OpenShift extensions).
Quarkus: Developer Experience — Dev Services, the Testcontainers-backed counterpart of Spring Boot’s Compose and Testcontainers development-time support.
Quarkus: Kubernetes and OpenShift — deploying the images to Kubernetes and OpenShift.

Reference

Docker Cheat Sheet — a one-page, printable summary of the whole section, with a downloadable PDF.

Relationship to the other references

SpringBoot. The SpringBoot Reference already covers @SpringBootTest with Testcontainers in Unit and Integration Testing and the Surefire/Failsafe split in Maven Quality Plugins. This section links to those pages and adds the Docker side: building the service’s image, the local Compose stack, how Testcontainers talks to Docker, and running the integration tests locally and in GitHub Actions.

Hibernate. Hibernate integration testing and Hibernate Search integration testing use PostgreSQL and Elasticsearch containers; Testcontainers Fundamentals explains the machinery underneath them.

Messaging. Spring Boot Testing for Messaging covers Kafka and RabbitMQ containers and broker-specific Docker Compose usage; this section documents the general spring.docker.compose.* support once, on Compose for Local Development, and links back for the brokers.

Quarkus. The Quarkus pages listed under "Other framework bindings" are the Quarkus equivalents of the Java and Spring Boot pages here; Jib and Buildpacks are cross-referenced rather than repeated.

Prometheus. Containers & Kubernetes monitoring in the Prometheus reference covers cAdvisor and container metrics; Resources, Logging and Monitoring covers the Docker daemon’s own metrics and links there for the rest.

Bibliography

Docker documentation (primary source for every Docker page) — the documentation entry point and its machine-readable indexes llms.txt and llms-full.txt; getting started: Docker overview, Get Docker, Docker concepts (the basics: What is a container?, What is an image?, What is a registry?, What is Docker Compose?; building images: Understanding the image layers, Writing a Dockerfile, Build, tag, and publish an image, Using the build cache, Multi-stage builds; running containers: Publishing and exposing ports, Overriding container defaults, Persisting container data, Sharing local files with containers, Multi-container applications) and Run an app; Docker Engine: Docker Engine, Install Docker Engine (with Install on Ubuntu and its convenience script), Linux post-installation steps, Running containers, Resource constraints, Runtime metrics, Start containers automatically, Run multiple processes in a container, GPU access, Storage (with volumes, bind mounts, tmpfs, image mounts, the containerd image store and storage drivers), Networking (with network drivers — bridge, host, none, overlay, IPvlan and Macvlan — port publishing, packet filtering and firewalls, iptables, nftables and legacy links), the daemon (with starting the daemon, remote access, Prometheus metrics, alternative runtimes, live restore, IPv6, daemon proxy, daemon logs and troubleshooting), logging, logging drivers and dual logging, contexts, labels, pruning, output formatting, filtering commands, CLI proxy configuration, security (with rootless mode, user namespaces, seccomp, AppArmor, protecting the socket, security non-events and content trust), Swarm mode (with key concepts, the routing mesh, secrets, stacks and rolling updates), deprecated features, the Engine release notes (in particular Engine 29) and retired features; Docker Build: Docker Build, overview, build context, Dockerfile concepts, best practices, multi-stage builds, multi-platform builds, base images, build variables, build secrets, exporting binaries, the build cache (with cache invalidation, cache optimisation, garbage collection and cache backends, including the registry and GitHub Actions backends), BuildKit and its Dockerfile frontend release notes, builders and build drivers, exporters, build checks and the build checks reference, attestations (with SBOM and SLSA provenance), annotations, Bake (with targets, matrix targets and building from a Compose file), build policies and their introduction, GitHub Actions (with cache management, multi-platform images, tags and labels, test before push, sharing images between jobs, attestations, reproducible builds and the GitHub builder) and the Build release notes; Docker Compose: overview, why use Compose, the application model, history, installation, quickstart, how-tos (with environment variables — precedence and interpolation — startup order, networking, profiles, Compose Watch, lifecycle hooks, init containers, secrets, multiple Compose files — merge, extends and include — project name, dependent images, provider services, GPU support, OCI artifacts and production), Compose Bridge and its usage, the Compose SDK, the trust model and the Compose release notes; Docker Desktop: Docker Desktop, installation, the containerd image store, virtual machine managers, WSL 2 and using WSL, synchronized file shares, networking, the Desktop CLI, Kubernetes, Enhanced Container Isolation and the Desktop release notes; Docker Hub and supply chain: Docker Hub quickstart, repositories (with creating a repository, tags, immutable tags, OCI artifacts, migrating from autobuilds and webhooks), the image library (with trusted content and mirroring), pull limits, access tokens, Docker Scout (with the quickstart, image analysis, policy evaluation, SBOMs and the GitHub Actions integration), Docker Hardened Images (with what they are, security concepts, using them, the migration checklist and the Java migration example); guides: Testcontainers, the Java guide (containerize, develop, run tests, CI/CD and deploy — now a single page), the Testcontainers for Java guides Getting started, Testing a Spring Boot REST API with Testcontainers, Testcontainers container lifecycle management, Replacing H2 with a real database, Configuration of services running in a container, Testing Spring Boot Kafka listeners, Testing REST API integrations using WireMock, Testing REST API integrations using MockServer, Testing AWS service integrations using LocalStack, Securing Spring Boot with Keycloak and Testing Quarkus applications, and the GitHub Actions, Docker Compose, databases, container-supported development, Kafka, Bake, Docker Scout, pre-seeding databases, WireMock and LocalStack guides; reference: the Dockerfile reference, the Compose file reference (with the services, configs and develop pages), the CLI reference (with docker container — including run, exec, logs, inspect, stats, top, stop, diff, commit and export — docker image — including pull, push, save and load — docker network, docker volume, docker system (with df and events), docker context, docker buildx (with build, imagetools create and imagetools inspect), docker compose, docker scout, docker init, docker debug, docker manifest, docker inspect and docker version), the dockerd reference, the Engine API reference (with its version history and SDK examples), the Docker Hub API, the Registry API and the samples; named on the getting-started page only, not documented: Docker AI, Sandboxes, Model Runner, models in Compose, the MCP Catalog and Toolkit, Gordon, Docker Offload, Docker Build Cloud, Docker Extensions and Hardened Docker Desktop.
Open Container Initiative and runtime components — the Open Container Initiative, the image specification (with its pre-defined annotations), the runtime specification, the distribution specification (with the specification text), runc, containerd, BuildKit, Moby, the Docker CLI, Buildx, Compose, the Compose Specification and CNCF Distribution (with deploying a registry server and the pull-through cache mirror recipe).
Testcontainers (primary source for the Testcontainers pages) — Testcontainers for Java (the JUnit 5 quickstart, features — networking, executing commands, files and volumes, startup and waits, container logs, reusable containers, image name substitution and configuration — JUnit 5 integration, manual lifecycle control, the modules catalog, the Docker Compose module, database modules (with PostgreSQL), the Kafka module, the MockServer module and supported Docker environments (with Docker wormhole and DinD patterns and image registry rate limiting)), the release notes, the Testcontainers guides, Testcontainers Desktop and Testcontainers Cloud.
Spring documentation (primary source for the Spring Boot pages) — Spring Boot Testcontainers support, development-time services, efficient container images, Dockerfiles, Cloud Native Buildpacks, the Maven plugin’s build-image goal, the Gradle plugin’s OCI images, the Docker Compose how-to, graceful shutdown, Actuator endpoints, GraalVM Native Image support, using the Maven plugin, Cloud Native Buildpacks, Paketo Buildpacks, Jib (with its Maven plugin), the java launcher reference and the Eclipse Temurin image.
GitHub Actions — docker/setup-qemu-action, docker/setup-buildx-action, docker/login-action, docker/metadata-action, docker/build-push-action, docker/bake-action, docker/setup-docker-action, docker/setup-compose-action, docker/scout-action, Communicating with Docker service containers, Creating PostgreSQL service containers, Running jobs in a container, Publishing Docker images, Working with the Container registry, GitHub-hosted runners, the runner images, actions/checkout, actions/setup-java, actions/cache and actions/upload-artifact.
Patterns and tooling — The Twelve-Factor App, The Reactive Manifesto, hadolint, SLSA, Sigstore (with signing containers with cosign), the CIS Docker Benchmark, the Maven Failsafe plugin (with its usage page), the official PostgreSQL image, the Apache Kafka Docker examples, the OpenTelemetry Java agent and Awesome Compose.
Consulted reference books (bibliography only — not the primary or main source for any page):
- Matthias, Karl; Kane, Sean P. Docker: Up & Running — Shipping Reliable Containers in Production. O’Reilly Media, 1st ed., June 2015. ISBN 978-1-491-91757-2 — publisher page. Written against Docker 1.3 to 1.6 on the pre-containerd, pre-BuildKit, pre-Compose-v2 platform, it predates multi-stage builds, BuildKit and Buildx, user-defined networks as the default, Swarm mode, Docker Desktop, rootless mode, the containerd image store, Scout, Hardened Images and Testcontainers, and it describes Boot2Docker, Docker Machine, standalone Swarm, Centurion, execution drivers, AUFS/devicemapper and nsenter, all since replaced or removed. It informs only the conceptual narrative on the getting-started, architecture, running-containers, debugging, security and orchestration pages. A third edition (April 2023, ISBN 978-1-098-13182-1 — publisher page) is current; it was not consulted.
- Raj, Pethuru; Chelladhurai, Jeeva S.; Singh, Vinod. Learning Docker — Optimize the power of Docker to run your applications quickly and easily. Packt Publishing, 1st ed., June 2015. ISBN 978-1-78439-793-7 — publisher page. Written against Docker 1.5 on Ubuntu 14.04; its MAINTAINER instruction, --link container linking, --volumes-from data-volume containers, docker-compose v1, the Python docker-registry, Docker Hub automated builds, the Jenkins integration and Docker Content Trust have all been deprecated, replaced or removed. It informs only the terminology and CLI walk-through, the Dockerfile instruction survey, the volume and namespace/cgroup explanations and the security best-practices list.

Both books above are consulted references only. Neither is the primary or main source for any page, and wherever either one and the Docker, OCI, Testcontainers, Spring or GitHub documentation disagree — or wherever a book is silent on something introduced after 2015 — the official documentation is authoritative.