Docker is a containerization platform that packages applications with their dependencies into lightweight, portable containers. It revolutionized software deployment by solving the "works on my machine" problem through consistent, isolated environments that run identically across development, testing, and production. Docker containers share the host OS kernel, making them far more efficient than traditional virtual machines while maintaining strong isolation. Docker Engine 29 (2026) ships BuildKit v0.30 as its default builder and Docker Compose V5 as the standard for multi-container orchestration; the legacy docker-compose v1 binary was fully removed in April 2025 — only docker compose (no hyphen) works now. The 2025–2026 release cycle significantly expanded Docker's scope: Docker Model Runner enables local AI inference with an OpenAI-compatible API; Docker Scout provides integrated vulnerability scanning and SBOM analysis; Docker Hardened Images (DHI) offer free, distroless-based images with CVE patches within 24 hours; Docker Build Cloud offloads builds to remote infrastructure for faster CI; Gordon (docker ai) is an AI-powered assistant that manages containers, debugs failures, and rewrites Dockerfiles from the CLI; and the Docker MCP Toolkit (docker mcp) makes it trivial to run and connect 120+ containerized Model Context Protocol servers to any AI client. The key mental model: a container is a running instance of an image, where images are immutable blueprints built in layers, and layers are cached for speed — understanding this layer caching mechanism is critical for optimizing build times and image sizes.
36 tables, 265 concepts. Select a concept node to jump to its table row.
Table 1: Container Lifecycle Management
These commands move a container through every phase of its life — from initial creation, through running and pausing, to graceful or forced termination. Knowing which command uses which signal (and which preserves the writable layer) is what separates clean production shutdowns from corrupted state.
| Command | Example | Description |
|---|---|---|
docker run -d -p 8080:80 --name web nginx | • Creates and starts a new container from an image • -d runs detached, -p maps ports, --name assigns a custom name. Most commonly used command. | |
docker start web | • Starts an existing stopped container • preserves all container state and configuration. | |
docker stop web | Gracefully stops a running container by sending SIGTERM then SIGKILL after grace period (default 10s). | |
docker restart web | • Stops then starts the same container instance • equivalent to stop + start; preserves the writable layer. | |
docker pause web | • Freezes all processes in a container using the cgroups freezer • no CPU usage, but memory stays allocated; instant resume with unpause. | |
docker unpause web | • Resumes a paused container • restores execution exactly where it stopped. | |
docker rm -f web | • Removes a stopped container • -f forces removal of running containers by SIGKILL-ing them first (no grace period). | |
docker kill web | • Immediately stops a container by sending SIGKILL • no graceful shutdown, use for unresponsive containers. | |
docker create --name web nginx | • Creates a container without starting it • useful for preparing containers before start. | |
docker wait web | • Blocks until a container stops, then prints its exit code • useful in scripts. | |
docker rename web web-old | • Renames an existing container • works on running and stopped containers; log driver tags keep the original name. | |
docker update --cpus 2 --memory 1g web | • Dynamically updates resource limits and restart policy on running containers • cannot change image, env vars, ports, or volumes. |
Table 2: Container Inspection and Interaction
Once a container is running, day-to-day work is about seeing what it is doing and reaching inside it. These commands cover listing containers, reading their logs and metrics, running ad-hoc commands inside them, and pulling out the metadata Docker keeps about each one.
| Command | Example | Description |
|---|---|---|
docker ps -a | • Lists containers • default shows running only, -a includes stopped; --filter health=unhealthy filters by health state; --format '{{.HealthStatus}}' prints health as a dedicated field (Engine 29.5+). | |
docker logs -f --tail 100 web | • Shows container stdout/stderr of the main process • -f follows live output, --tail limits lines. | |
docker exec -it web bash | • Runs a new process inside a running container • -it allocates interactive TTY for shell access. | |
docker attach web | • Connects to container's main process (PID 1) stdin/stdout/stderr • Ctrl+C sends SIGINT and usually stops the container; detach with Ctrl+P, Ctrl+Q. | |
docker inspect --format '{{.NetworkSettings.IPAddress}}' web | • Returns detailed JSON with all container metadata (config, state, network, mounts) • --format Go templates extract single fields. | |
docker stats --no-stream web | • Live stream of CPU, memory, network, disk I/O metrics • --no-stream prints one snapshot then exits (use in scripts). | |
docker top web | • Shows running processes inside a container, using the host's ps• PID column reports host PIDs, not the container's PID 1. | |
docker port web | • Lists all published port mappings for a container • shows host port → container port bindings (only ports published with -p/-P). | |
docker diff web | Shows filesystem changes vs the starting image (A=added, C=changed, D=deleted). |
Table 3: Image Management
Commands for getting images onto and off your machine: building from a Dockerfile, pulling and pushing through registries, tagging, inspecting layers, and moving images between hosts as tar archives. The two biggest gotchas live here too — save vs export (image vs container, layered vs flat) and docker commit as a production anti-pattern.
| Command | Example | Description |
|---|---|---|
docker build -t myapp:1.0 . | • Builds an image from a Dockerfile • -t tags it; . is the build context directory sent to the daemon. | |
docker images | Lists local images with repository, tag, image ID, creation date, and size. | |
docker pull nginx:alpine | • Downloads an image from a registry (default Docker Hub) • only missing layers are fetched thanks to content-addressable storage. | |
docker push myuser/myapp:1.0 | • Uploads an image to a registry • requires docker login first. | |
docker tag myapp:1.0 myapp:latest | • Adds a new name pointing to the same image ID • does not copy or duplicate layers. | |
docker rmi nginx:alpine | • Removes an image • fails if any container (running or stopped) references it unless -f forces removal. | |
docker history nginx | • Shows each layer in an image with its size and creating command • the go-to tool for diagnosing image bloat. | |
docker save -o app.tar myapp:1.0 | Exports an image to a tar archive, preserving all layers and metadata. | |
docker load -i app.tar | • Imports an image from a docker save tarball• restores all layers and original tags. | |
docker import rootfs.tar myapp:1.0 | • Creates an image from a raw filesystem tarball • result is a single layer with no build history. | |
docker export web -o web.tar | • Exports a container's filesystem as a flat tar • layers collapsed, image metadata lost. | |
docker commit web myapp:snapshot | • Creates a new image from a container's filesystem changes • fine for ad-hoc debugging, an anti-pattern for production (no Dockerfile, not reproducible). | |
docker search --limit 5 nginx | • Searches Docker Hub only (not arbitrary registries) • --filter narrows by stars or official status. |
Table 4: Dockerfile Instructions
A Dockerfile is a recipe of instructions that BuildKit executes top-to-bottom to assemble an image, with most instructions producing a new layer. The instructions below are the building blocks every Dockerfile uses, and the trickiest part is knowing which ones run at build time versus runtime, and which ones only attach metadata.
| Instruction | Example | Description |
|---|---|---|
FROM node:18-alpine | • Sets the base image and starts a build stage • every Dockerfile begins with FROM (after optional ARG/parser directives) • pin a specific tag or digest, never latest in production. | |
RUN apt-get update && \ apt-get install -y curl |• Executes commands during image build and commits the result as a new layer • always chain apt-get update and apt-get install in the same RUN to avoid stale-cache bugs. | | ||
CMD ["npm", "start"] | • Provides the default command (or default args for ENTRYPOINT) when a container starts • replaced by any command passed to docker run• prefer the exec form (JSON array) for correct signal handling. | |
ENTRYPOINT ["python", "app.py"] | • Configures the container to run as a fixed executable • args to docker run are appended to it; override only with --entrypoint• when both ENTRYPOINT and CMD are exec form, CMD becomes default arguments. | |
COPY package*.json ./ | • Copies files and directories from the build context into the image • preferred default for local files — predictable, no hidden behavior. | |
ADD app.tar.gz /app/ | • Like COPY, but also auto-extracts local tar archives and can fetch remote URLs • use COPY unless you specifically need extraction or URL/Git fetching. | |
WORKDIR /app | • Sets the working directory for the RUN, CMD, ENTRYPOINT, COPY, and ADD that follow • creates the directory if missing — prefer absolute paths. | |
ENV NODE_ENV=production | • Sets environment variables that persist in subsequent build steps and in running containers • never use for secrets — values leak into image layers and docker history. | |
ARG VERSION=1.0 | • Defines a build-time variable settable with --build-arg• not present in the running container's environment, and re-scoped per stage in multi-stage builds. | |
EXPOSE 8080 | • Documents which ports the container listens on (image metadata only) • does NOT publish ports — docker run -p or -P is still required for host access. | |
VOLUME /data | • Declares a path as a mount point for an external/anonymous volume • with the legacy builder, writes to that path in later RUN steps are discarded (kept under BuildKit). | |
USER node | • Sets the UID/GID used by subsequent RUN, CMD, and ENTRYPOINT and at runtime • place it after any RUN that needs root (package install, chown) — running as non-root is a security baseline. | |
LABEL version="1.0" | • Attaches metadata to the image as key=value pairs • visible via docker inspect and filterable with docker image ls --filter, no runtime behavior. | |
HEALTHCHECK CMD curl -f || exit 1 | • Defines a command Docker runs periodically to test if the container is healthy (exit 0=healthy, 1=unhealthy, 2 reserved) • only flips the container's health status; Compose/Swarm/K8s decide whether to restart. | |
STOPSIGNAL SIGQUIT | • Sets the signal sent to PID 1 when stopping the container • defaults to SIGTERM; signals only reach the process directly when CMD/ENTRYPOINT use exec form. | |
SHELL ["/bin/bash", "-c"] | • Overrides the shell used for shell-form RUN/CMD/ENTRYPOINT • default is ["/bin/sh", "-c"] on Linux and ["cmd", "/S", "/C"] on Windows — essential for picking PowerShell on Windows. | |
ONBUILD COPY . /app | • Registers a trigger instruction that runs only when this image is used as a FROM base in a downstream build• useful for framework base images; triggers do not cascade to grandchildren. |
Table 5: Build Optimization Techniques
These techniques shrink final images, speed up rebuilds, and keep secrets out of layer history. Most are built on BuildKit, the modern Dockerfile frontend (# syntax=docker/dockerfile:1) — multi-stage stages, cache mounts, and secret mounts only behave as described when BuildKit is the active builder.
| Technique | Example | Description |
|---|---|---|
FROM golang AS builderFROM alpineCOPY --from=builder /app . | • Uses multiple FROM statements to create separate build stages; only artifacts copied into the final stage end up in the published image• intermediate stages (compilers, dev tools) are discarded entirely, drastically reducing size and attack surface. | |
COPY package*.json ./RUN npm installCOPY . . | • Docker caches each instruction's output as a layer; if a layer's inputs change, that layer and every layer after it must rebuild • order instructions least- to most-frequently changed (manifests + install before COPY . .) to maximize hits. | |
COPY --link requirements.txt . | • Creates an independent layer that doesn't depend on earlier ones — changes to instructions above it don't invalidate it • enables remote cache reuse ( --cache-from) and image rebasing across multi-stage and large builds. | |
node_modules*.log.git | • Excludes files from the build context (the bundle sent to the BuildKit daemon), not from the image directly • shrinks context upload, blocks accidental COPY of node_modules / .git / secrets, and keeps the cache stable across machines. | |
RUN --mount=type=cache,target=/root/.npm npm install | • Mounts a persistent build-time cache at the target path for one RUN only — contents survive between builds but are never stored in image layers• target the package manager's download dir ( /root/.npm, /var/cache/apt, /root/.cache/pip), not the install dir. | |
RUN --mount=type=secret,id=token curl -H "Auth: $(cat /run/secrets/token)" | • Mounts a secret as a tmpfs file (e.g. /run/secrets/token) for a single RUN; never written to layers, docker history, or build cache• replaces the leaky --build-arg / ENV SECRET=... pattern. | |
FROM alpine:3.21FROM gcr.io/distroless/staticFROM scratch | • Smaller base = smaller image and smaller attack surface (alpine ~5 MB musl-libc vs ubuntu ~80 MB) • distroless drops the shell and package manager; scratch is empty — best for statically-compiled Go/Rust binaries. | |
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/* | • Chain commands with && so the install and the cleanup happen in the same layer — files deleted in a later RUN still live in earlier layers' history• also prevents the stale- apt-get update caching trap. | |
docker buildx build --platform linux/amd64,linux/arm64 -t app . | • buildx (the BuildKit-backed CLI) builds for multiple architectures in one invocation, producing a single multi-arch manifest• cross-arch builds need either QEMU emulation or native builder nodes per platform. |
Table 6: Port Publishing and Networking
Container ports stay isolated from the host until you explicitly publish them. The -p family of flags wires a host address and port to a container port; getting the syntax — especially the host-then-container order, the default 0.0.0.0 bind, and the implicit TCP protocol — right is the difference between a reachable service and a silent failure.
| Option | Example | Description |
|---|---|---|
docker run -p 8080:80 nginx | • Maps a host port to a container port using HOST_PORT:CONTAINER_PORT• with no host IP, binds to 0.0.0.0 on every interface. | |
docker run -P nginx | • Publishes every EXPOSEd port to a random ephemeral host port• query the chosen ports with docker port <container>. | |
docker run -p 127.0.0.1:8080:80 nginx | • Binds the published port to a specific host interface • use 127.0.0.1 to restrict access to the host (e.g. behind a reverse proxy). | |
docker run -p 8000-8010:8000-8010 app | • Maps a range of ports one-to-one • a range-to-single form like 8000-9000:5000 picks one free host port from the range. | |
docker run -p 53:53/udp dns | • -p publishes TCP by default; append /udp for UDP services like DNS, QUIC, or SIP• to publish both, repeat the flag: -p 53:53/tcp -p 53:53/udp. |
Table 7: Network Modes
Docker networking is driven by a pluggable set of built-in drivers — each one shapes how a container's network namespace is wired up, what it can reach, and how it appears to the rest of the world. Picking the right one is the difference between a quick local test and a setup that survives a multi-host production deployment.
| Mode | Example | Description |
|---|---|---|
docker run --network bridge nginx | • Containers get private IPs on a virtual L2 bridge with NAT for outbound traffic • the default bridge has no name-based DNS between containers — only user-defined bridge networks do. | |
docker run --network host nginx | • Container shares the host's network namespace — no isolation, no NAT, binds host ports directly • fastest but largest security blast radius. Linux only (Desktop 4.34+ via VM bridge). | |
docker run --network none app | • Isolated network namespace with only lo (loopback)• no other interfaces, no external connectivity — useful for batch jobs that must not touch the network. | |
docker network create -d overlay --attachable my-net | • Multi-host networking over VXLAN for Docker Swarm • requires docker swarm init even for single-node use; containers on different swarm nodes see each other as if on one LAN. | |
docker network create -d macvlan --subnet=192.168.1.0/24 -o parent=eth0 my-net | • Each container gets its own MAC and appears as a physical device on the parent NIC's LAN • Linux-only; most cloud providers block it (hypervisor MAC-spoof protection). | |
docker network create -d ipvlan --subnet=192.168.1.0/24 -o parent=eth0 my-net | • Like macvlan but containers share the parent's MAC (L2 mode) • works where macvlan is blocked, and avoids upstream-switch MAC-table exhaustion at scale. |
Table 8: Network Management
Docker networking glues containers to each other and to the outside world. The commands here create and manage user-defined networks (almost always what you want — they enable automatic container-name DNS, unlike the default bridge), connect and disconnect running containers, and reach back to the host machine from inside a container.
| Command | Example | Description |
|---|---|---|
docker network create mynet | • Creates a user-defined network — default driver is bridge; use -d overlay for Swarm or -d macvlan for L2• user-defined bridges enable automatic DNS resolution between containers by name (the default bridge network does not). | |
docker network ls | • Lists all networks with NETWORK ID, NAME, DRIVER, and SCOPE• always includes the three predefined networks bridge, host, and none that ship with the daemon. | |
docker network connect mynet web | • Attaches a running container to an additional network — containers can be on multiple networks at once • on the primary network they resolve each other by name; on secondary networks they must use IP. | |
docker network disconnect mynet web | • Removes a container from a network while it is still running — no need to stop it first • commonly used before docker network rm to free a network that's blocking removal. | |
docker network inspect mynet | • Returns the full JSON config for a network: driver, IPAM Subnet/Gateway, every connected container, IP and MAC addresses, driver options• the first stop when containers can see each other by IP but not by name. | |
docker network rm mynet | • Removes a user-defined network — fails with "has active endpoints" if any container is still attached • disconnect or stop+remove the container first, then retry. -f only ignores "no such network", it does not force-detach. | |
docker network prune | • Removes every unused user-defined network (no container attached) and prompts for confirmation; -f skips the prompt, --filter "until=24h" narrows by age• the predefined bridge, host, and none networks are never touched. | |
curl http://host.docker.internal:3000 | • Special DNS name that resolves to the host machine from inside a container — built in on Docker Desktop (Mac/Windows/WSL) • on Linux Docker Engine it does not exist by default; add --add-host=host.docker.internal:host-gateway to docker run (or extra_hosts in Compose). |
Table 9: Volume Management
Containers are ephemeral, but most real applications need data that outlives any single container. Docker offers three storage primitives — named volumes, bind mounts, and tmpfs — each with very different durability, portability, and host-coupling trade-offs, plus two CLI shapes (-v and --mount) whose subtle differences trip people up.
| Type | Example | Description |
|---|---|---|
docker run -v data:/app/data nginx | • Docker-managed storage under /var/lib/docker/volumes/, lifecycle independent of the container• preferred for production; easy to back up, share between containers, and reference by name. | |
docker run --mount type=volume,source=mydata,target=/data nginx | • Explicit, key-value alternative to -v that supports type=volume, type=bind, and type=tmpfs• recommended for scripting because it errors on a missing bind source instead of silently creating a directory. | |
docker run -v /host/path:/container/path nginx | • Maps an absolute host path straight into the container • changes sync in real time, ideal for development; portability and permission ownership are your problem, not Docker's. | |
docker run --tmpfs /tmp nginx | • Stores data only in host RAM, never written to disk; removed when the container stops • good for caches and short-lived secrets, not for anything that must survive a restart. | |
docker run -v /app/data nginx | • Created automatically with a random hash name when no source is given • persist after the container exits unless you used --rm; accumulate quickly and are hard to identify. | |
docker run -v data:/app:ro nginx | • :ro (or readonly with --mount) makes the mount read-only inside the container• the host can still modify the underlying files; it is a container-side guard, not a host-side lock. | |
docker run --volumes-from web nginx | • Mounts all volumes from another container at their original paths • classic backup/restore trick; modern setups usually share a single named volume by name instead. |
Table 10: Volume Commands
Volumes are Docker's managed mechanism for persisting data outside a container's writable layer, so data survives container restarts and deletions. The docker volume subcommands let you create, inspect, and clean up that storage — and most of the gotchas live in what they don't do (auto-show usage, expose host paths on Docker Desktop, or prune named volumes by default).
| Command | Example | Description |
|---|---|---|
docker volume create mydata | • Creates a named volume with a chosen driver and options • rarely required for plain use — docker run -v mydata:/path auto-creates it. | |
docker volume ls | • Lists all volumes with driver and name • does not show which container uses each — pair with docker ps --filter volume=<name>. | |
docker volume inspect mydata | • Shows volume metadata including the Mountpoint • on Docker Desktop, that path lives inside the utility VM, not on the host filesystem. | |
docker volume rm mydata | • Removes a volume • fails if any container references it — including stopped ones (check with docker ps -a). | |
docker volume prune | • By default removes only unused anonymous volumes • use -a / --all to also delete unused named volumes (API 1.42+). |
Table 11: Resource Constraints
By default a Docker container can use as much memory and CPU as the host kernel will give it, which makes "noisy neighbor" problems and OOM cascades easy to trigger. These flags map directly onto Linux cgroup controllers (memory, CPU CFS, cpuset, pids, blkio) and let you pick between hard caps, soft reservations, relative weights, and device pinning — distinctions that decide whether a container crashes with exit 137 or simply slows down.
| Flag | Example | Description |
|---|---|---|
docker run -m 512m nginx | • Hard memory limit (cgroup) • OOM killer sends SIGKILL on breach (exit 137), suffixes: b k m g. | |
docker run --memory-reservation 256m nginx | • Soft limit only enforced under host memory pressure • must be lower than --memory to take effect; container may exceed it. | |
docker run --cpus 1.5 nginx | • Hard cap on total CPU time via CFS quota/period • 1.5 = --cpu-period=100000 + --cpu-quota=150000; kernel picks which cores. | |
docker run --cpu-shares 512 nginx | • Relative weight (default 1024) for CFS — not a cap • only honored under CPU contention; idle host = no effect. | |
docker run --cpuset-cpus 0,1 nginx | • Pins the container to specific physical CPUs (cores 0 and 1) • used for NUMA locality and cache-sensitive workloads. | |
docker run --pids-limit 100 nginx | • Caps total PIDs (processes + threads) via the pids cgroup • mitigates fork bombs; thread-heavy JVM/Python apps can hit it. | |
docker run --blkio-weight 500 nginx | • Relative block-I/O weight (default 500, range 10-1000) • effective only on schedulers that honor it (e.g., BFQ/CFQ) and under disk contention. | |
docker run --gpus all nvidia/cuda:12.0-base nvidia-smi | • Exposes host GPUs to the container • requires the NVIDIA Container Toolkit on the host; use "device=0,1" to target specific GPUs. |
Table 12: Restart Policies
Restart policies tell the Docker daemon when to bring a container back up on its own — after a crash, a host reboot, or a daemon restart. Pick the right one and a single-host stack stays available through reboots; pick the wrong one and a "stopped" container quietly comes back during maintenance.
| Policy | Example | Description |
|---|---|---|
docker run --restart no nginx | • Never restart container automatically • manual docker start still works. | |
docker run --restart on-failure:3 nginx | • Restarts only on non-zero exit code • optional :N cap; not triggered by daemon restart. | |
docker run --restart always nginx | • Always restarts, including after daemon restart • brings back even manually-stopped containers on reboot. | |
docker run --restart unless-stopped nginx | • Like always but respects manual stops across daemon restarts• preferred for single-host production stacks. |
Table 13: Health Checks
Docker can probe a running container with a periodic command and surface a healthy / unhealthy / starting state on top of the normal running state. Set the probe in the image via the HEALTHCHECK Dockerfile instruction, or attach/override it at runtime with docker run --health-* flags. The health state shows up in docker ps and docker inspect, but Docker itself does not restart unhealthy containers — that's the orchestrator's (Swarm/Compose with condition: service_healthy/Kubernetes) job.
| Option | Example | Description |
|---|---|---|
HEALTHCHECK --interval=30s CMD curl -f http://localhost/|| exit 1 | • Dockerfile instruction defining the probe baked into the image • exit 0 = healthy, 1 = unhealthy, 2 is reserved• only the last HEALTHCHECK in a Dockerfile takes effect; HEALTHCHECK NONE disables one inherited from the base image. | |
docker run --health-cmd "curl -f http://localhost/" nginx | • Runtime override that attaches (or replaces) the probe command without rebuilding the image • useful for ad-hoc testing or images shipped without a HEALTHCHECK. | |
docker run --health-interval=10s nginx | • Wait time between checks (after the previous one completes), default 30s• the first check also runs one interval after container start. | |
docker run --health-timeout=5s nginx | • Max time for a single check to complete, default 30s• if exceeded, the probe is SIGKILL-ed and that run counts as a failure. | |
docker run --health-retries=3 nginx | • Number of consecutive failures needed to flip the state to unhealthy, default 3• one successful check resets the failing streak to zero. | |
docker run --health-start-period=60s nginx | • Initialization grace window, default 0s — checks still run during it, but failures do not count toward --health-retries• any single success ends the start period early. |
Table 14: Docker Compose Services
How each services: entry is configured — the attributes that decide what runs, how it reaches the network, what it depends on, and how the platform treats it. Most startup-order, port, and resource bugs in Compose stacks trace back to misreading one of these keys.
| Attribute | Example | Description |
|---|---|---|
image: nginx:alpine | • Names the image to run • pulled from the registry if not present locally. | |
build: context: . dockerfile: Dockerfile.prod | • Builds an image from a Dockerfile • context is resolved relative to the Compose file's directory, not the shell's cwd. | |
ports: - "8080:80" | • Publishes ports as "HOST:CONTAINER"• always quote short syntax — YAML parses unquoted xx:yy as a base-60 number. | |
volumes: - ./data:/data:ro | • Mounts volumes or bind mounts • trailing :ro mounts the path read-only inside the container. | |
environment: NODE_ENV: production | • Sets runtime environment variables • only Compose's ${VAR} interpolation expands — a literal $BAR is passed through, not shell-expanded. | |
depends_on: db: condition: service_healthy restart: true required: false | • Controls startup order; default service_started only waits for the container to start• service_healthy waits for the dependency's healthcheck to pass• restart: true restarts the dependent if the dependency restarts; required: false allows startup even if the dependency is unavailable. | |
networks: - frontend | • Attaches the service to named networks • inside a shared network, services reach each other by service name on the container port. | |
restart: unless-stopped | • Sets the container restart policy • options: no (default), always, on-failure[:N], unless-stopped. | |
command: npm run dev | • Overrides the image's CMD only• the image's ENTRYPOINT still runs and receives this as its arguments. | |
entrypoint: /app/entrypoint.sh | • Replaces the image's ENTRYPOINT entirely• setting it does not clear the image's CMD, which is still passed as arguments. | |
healthcheck: test: ["CMD", "curl", "-f", "http://localhost/"] interval: 30s start_interval: 2s | • Defines a container health probe • CMD execs the args directly; CMD-SHELL wraps in /bin/sh -c so operators like || work• start_interval sets a faster check rate during start_period so dependent services start sooner. | |
deploy: resources: limits: memory: 512M | • Most keys ( replicas, placement, update_config) are Swarm-only and ignored by docker compose up• deploy.resources for limits and GPU reservations does apply to plain Compose. |
Table 15: Docker Compose Commands
The Compose CLI manages multi-container apps defined in a compose.yaml file as a single Compose project — a scope Compose tracks by project name. Note: the legacy docker-compose (v1, hyphenated) was permanently removed in April 2025; only docker compose (space, no hyphen) works. Knowing what each command actually mutates (containers, networks, volumes, images) is the difference between a clean restart and accidentally deleting your database.
| Command | Example | Description |
|---|---|---|
docker compose up -d | • Builds, (re)creates, starts all services and their networks • -d detaches; recreates containers whose config changed since last up. | |
docker compose down -v | • Stops and removes containers and the project's networks • Keeps named volumes by default; -v also removes named volumes (data loss). | |
docker compose ps | • Lists running containers for the current Compose project • add -a for stopped ones. | |
docker compose logs -f web | • Shows aggregated logs from services • -f follows; pass a service name to filter to one. | |
docker compose exec web sh | • Runs a command inside a running service container • allocates a TTY by default; --index picks a replica. | |
docker compose build --no-cache | • Builds or rebuilds service images from each service's build:• --no-cache discards the build cache; pair with --pull to refresh base images. | |
docker compose pull | • Pulls images for services from their registries • does not start containers. | |
docker compose restart web | Restarts the existing containers without re-reading the Compose file — config edits do not apply (use up -d instead). | |
docker compose stop | • Stops services without removing containers, networks, or volumes • faster than down; resume with start. | |
docker compose start | • Starts previously stopped containers for the project • never creates new containers — use up for that. | |
docker compose run --rm web npm test | • Runs a one-off command in a new container based on the service • --rm removes it after exit; starts linked services unless --no-deps. | |
docker compose watch | • Reacts to file changes declared under develop.watch• actions: sync, rebuild, sync+restart (modern replacement for bind-mount-and-restart). |
Table 16: Docker Compose Advanced Features
Compose's advanced primitives go beyond a basic compose.yaml: profiles toggle optional services per environment, extends/include/override files compose larger stacks out of smaller pieces, secrets and configs mount files instead of leaking env vars, develop.watch keeps containers in sync with source changes, and the models top-level element declares AI/ML model dependencies alongside services.
| Feature | Example | Description |
|---|---|---|
profiles: [debug] | • Groups services for selective activation • docker compose --profile debug up only starts debug services. | |
extends: file: common.yml service: base | • Inherits configuration from another service • enables reusable base definitions. | |
docker-compose.override.yml | • Automatically merged with docker-compose.yml• environment-specific overrides without modifying base file. | |
include: - monitoring.yml - oci://docker.io/org/stack:latest | • Includes separate Compose files or OCI artifacts to combine projects • ⚠️ update to v2.40.2+ if using OCI includes — CVE-2025-62725 path-traversal fix. | |
env_file: - .env.prod | • Loads environment variables from files • keeps secrets out of Compose file. | |
secrets: - db_password | • Injects secrets as files in container • mounted at /run/secrets/. | |
configs: - nginx.conf | • Like secrets but for non-sensitive config files • also mounted as files. | |
develop: watch: - action: sync path: ./src target: /app/src - action: rebuild path: package.json | • Configures hot-reload for development (formerly x-develop — drop the x- prefix)• actions: sync (copy files), rebuild (rebuild image), sync+restart (copy and restart)• initial_sync syncs all matching files immediately on docker compose watch start. | |
models: llm: model: ai/smollm2 context_size: 4096 | • Top-level element declaring AI/ML model dependencies as OCI artifacts alongside services • platform (e.g. Docker Model Runner) injects <NAME>_URL and <NAME>_MODEL env vars into consuming services; portable across cloud platforms. | |
x-common: &common restart: alwaysservices: web: <<: *common | • Reuses config blocks with anchors and aliases • x- prefix defines extension fields that Compose ignores. | |
deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu] | • Requests GPU access for a service (NVIDIA and AMD supported) • requires NVIDIA Container Toolkit or AMD ROCm driver on host. |
Table 17: Registry and Authentication
Authenticating to a Docker registry sets up the credentials that later push and pull commands silently reuse, so the way you log in directly shapes how exposed those secrets are. This table covers the day-to-day commands and the two safer non-interactive patterns to prefer over -p.
| Command | Example | Description |
|---|---|---|
docker login registry.example.com | • Authenticates to a registry and caches credentials for later push/pull• stores them via the configured credential helper, or base64-encoded in ~/.docker/config.json as a fallback. | |
docker logout registry.example.com | • Removes the locally stored credential for the given server (or the default registry) • does not revoke the token on the registry — rotate it there if it may have leaked. | |
docker login -u user -p pass | • Non-interactive login with the password as an argument • avoid — leaks into shell history and ps; Docker prints WARNING! Using --password via the CLI is insecure. | |
echo $TOKEN | docker login -u user --password-stdin | • Reads the password or PAT from stdin so it never appears in history or process listings • the recommended pattern for CI and short-lived cloud tokens (ECR, GCR, ACR). |
Table 18: Image Tagging Strategies
A Docker tag is just a mutable, human-readable pointer — docker tag a b creates an alias to the same image ID, and any tag (including latest) can be reassigned later. Choosing a tagging convention is really choosing how much version, source, and environment information you bake into that pointer so future-you can answer "what is actually running?" without guessing.
| Strategy | Example | Description |
|---|---|---|
myapp:1.2.3 | • Uses major.minor.patch format • best practice for release tracking and rollbacks. | |
myapp:a3f2c1b | • Tags with Git commit hash • enables exact source code traceability. | |
myapp:prod-1.2.3 | • Includes environment prefix • clearly indicates deployment target. | |
myapp:2026-03-01 | • Timestamps with YYYY-MM-DD • useful for nightly builds or time-based releases. | |
myapp:feature-auth | • Tags with branch name • tracks feature development images. |
Table 19: Cleanup and Maintenance
Cleanup commands reclaim disk space, but each one targets a different scope and several carry real data-loss risk if used carelessly. Knowing what each prune does and does not touch — especially --volumes, -a, and the until= filter — is the difference between a tidy host and an outage.
| Command | Example | Description |
|---|---|---|
docker system prune -a | • Removes stopped containers, unused networks, dangling images, and unused build cache • -a also removes any image not used by a container; volumes are NOT included unless --volumes is passed. | |
docker image prune -a --filter "until=168h" | • Without -a removes only dangling images (untagged, <none>)• -a removes all unused images; --filter "until=168h" keeps images created in the last 7 days. | |
docker container prune | • Removes all stopped containers and their writable layers • running containers are untouched; prompts before deletion unless -f. | |
docker volume prune | • Deletes unused volumes (any volume not attached to a container) • Data-loss risk — back up first, and remember docker system prune does NOT touch volumes by default. | |
docker network prune | • Removes unused custom networks • built-in networks ( bridge, host, none) are never pruned. | |
docker builder prune | • Clears the BuildKit build cache for the active builder • does not touch images or containers; next build rebuilds layers from scratch. |
Table 20: Logging Drivers
Docker streams every container's stdout/stderr through a logging driver, and the choice between the default json-file driver and alternatives like local, journald, or remote forwarders shapes disk usage, queryability, and how logs reach a central pipeline.
| Driver | Example | Description |
|---|---|---|
--log-driver json-file | • Stores logs as JSON on disk • queryable with docker logs, no rotation by default — set max-size/max-file to avoid filling /var/lib/docker. | |
--log-driver local | • Optimized local file driver with automatic log rotation and compression by default • Docker's recommended local driver; now supports label, env, and tag log options (Engine 29.5+). | |
--log-driver syslog --log-opt syslog-address=udp://host:514 | • Forwards logs to a syslog daemon over UDP/TCP/TLS • integrates with centralized logging. | |
--log-driver journald | • Sends logs to the systemd journal (Linux only) • query with journalctl CONTAINER_NAME=foo. | |
--log-driver fluentd --log-opt fluentd-address=host:24224 | • Forwards to a Fluentd collector • popular for Kubernetes and centralized logging. | |
--log-driver awslogs --log-opt awslogs-group=myapp | • Sends logs to AWS CloudWatch Logs • credentials come from the daemon/host (EC2 instance profile or ECS task role), not container env vars. | |
--log-driver gcplogs | • Forwards to Google Cloud Logging • auto-detects project, zone, and instance from the GCE metadata server. | |
--log-driver splunk --log-opt splunk-token=XXX --log-opt splunk-url=https://host:8088 | • Sends logs to the Splunk HTTP Event Collector • enterprise logging solution. |
Table 21: Security Practices
Container security is layered defense: drop privileges, shrink the attack surface, and constrain what the kernel will let the container do. These practices stack — running as non-root, dropping capabilities, applying a seccomp profile, and starting from a minimal base image each close a different escape path, and together they're what stands between a single application bug and host compromise.
| Practice | Example | Description |
|---|---|---|
USER node | • Creates and switches to non-root user • prevents privilege escalation attacks. | |
docker run --read-only nginx | • Makes container filesystem immutable • prevents tampering; use tmpfs for writable dirs. | |
docker run --cap-drop ALL --cap-add NET_BIND_SERVICE nginx | • Removes Linux capabilities • principle of least privilege — drop ALL then add only what's needed. | |
RUN --mount=type=secret,id=token | • Never hardcode secrets in images • use BuildKit secrets or runtime secrets. | |
docker scout cves nginx:latest | • Scans for vulnerabilities • integrates with Docker Scout, Trivy, Snyk. | |
FROM gcr.io/distroless/static | • Use distroless or alpine • fewer packages = smaller attack surface. | |
Avoid --privileged | • Never use in production • gives full host access, defeats containerization. | |
--security-opt seccomp=profile.json | • Apply seccomp/AppArmor/SELinux profiles • restricts syscalls and actions. | |
docker run --security-opt no-new-privileges nginx | • Prevents processes from gaining additional privileges via setuid/setgid • critical for defense in depth. | |
dockerd-rootless-setuptool.sh install | • Runs Docker daemon without root privileges • mitigates potential vulnerabilities in daemon and container runtime; Engine 29.5+ uses gvisor-tap-vsock as the default rootless network driver. | |
FROM dhi.io/python:3.12 | • Docker's distroless-based, CVE-free base images • free since Dec 2025, auto-patched within 24hrs, include SBOM and provenance attestations; manage via docker dhi CLI. |
Table 22: Signal Handling
How Docker delivers Unix signals to your container's PID 1 — and why a misplaced shell wrapper or a too-short grace period quietly turns "graceful shutdown" into data corruption. These rows cover the signals Docker actually sends, who receives them, and the form choices that decide whether your app ever gets a chance to clean up.
| Signal | Example | Description |
|---|---|---|
Sent by docker stop | • Graceful shutdown signal delivered to the container's PID 1 • after a grace period (default 10s on Linux, 30s on Windows), Docker follows up with SIGKILL. Tune with -t / --stop-timeout. | |
Sent after grace period, or by docker kill | • Force kill signal — kernel-enforced, cannot be caught, blocked, or ignored • immediate termination with no cleanup. | |
Ctrl+C in attached mode | • Interrupt signal sent to PID 1 • most apps treat it like SIGTERM and exit, so Ctrl+C while attached typically stops the container. | |
docker kill -s SIGHUP web | • Hangup signal — historically "controlling terminal closed" • many daemons (nginx, HAProxy) repurpose it to reload configuration without restarting. | |
CMD ["app"] vs CMD app | • Exec form (JSON array): the app IS PID 1 and receives signals directly • shell form wraps in /bin/sh -c, sh becomes PID 1 and does not forward signals — the app never sees SIGTERM. |
Table 23: Context and Remote Docker
A Docker context bundles the endpoint URL, TLS material, and name of one daemon so a single docker CLI can manage many daemons — local Docker Desktop, an SSH-reachable production server, an ECS endpoint — and switch between them. SSH-based contexts are the canonical secure pattern for remote control because they reuse your SSH keys and avoid exposing the Docker daemon socket on a public TCP port.
| Command | Example | Description |
|---|---|---|
docker context create prod --docker "host=ssh://user@host" | • Registers a named connection to a Docker daemon (local, tcp://, or ssh://)• metadata is stored under ~/.docker/contexts/. | |
docker context use prod | • Sets the active context in ~/.docker/config.json• persists across shells until changed or overridden by DOCKER_HOST / DOCKER_CONTEXT / --context. | |
docker context ls | • Lists every context with its DOCKER ENDPOINT URL• the active one is marked with *. | |
docker context rm prod | • Removes a context • fails on the active context unless you pass -f / --force or docker context use default first. | |
export DOCKER_HOST=ssh://user | • Per-shell daemon-socket override • beats the active context but is itself overridden by DOCKER_CONTEXT and --host / --context. |
Table 24: Docker Swarm Basics
Swarm mode is the orchestrator built directly into the Docker Engine — no separate install needed. One docker swarm init turns the current engine into a single-node cluster (a manager), and additional engines join as workers or managers via a join token. From there you create services (replicated containers spread across the cluster) and stacks (a whole Compose file deployed as a unit), and the managers schedule tasks, run rolling updates, and keep the desired replica count alive on the routing mesh.
| Command | Example | Description |
|---|---|---|
docker swarm init | • Turns the current Docker Engine into a single-node Swarm cluster • the current node becomes the leader manager. | |
docker swarm join --token TOKEN host:2377 | • Joins a node to an existing Swarm • the token used (worker or manager) determines the role of the joining node. | |
docker service create --replicas 3 --name web nginx | • Creates a new Swarm service distributed across the cluster • --replicas N declares the desired task count the schedulers keep alive. | |
docker service scale web=5 | • Scales an already-running replicated service to a new replica count • cannot be used on global-mode services. | |
docker service update --image nginx:1.21 web | • Applies a rolling update — by default updates 1 task at a time, controlled by --update-parallelism and --update-delay• supports --rollback on failure. | |
docker node ls | • Lists every node the Swarm manager knows about, with status, availability, and manager status • only runs on a manager node. | |
docker stack deploy -c compose.yml myapp | • Deploys a Compose file (v3.0+) as a Swarm stack — creating its services, networks, and volumes • build: is ignored — images must already exist in a registry. |
Table 25: Environment Variables
Docker lets you inject configuration into containers through several distinct channels — runtime CLI flags, files, Dockerfile baked-in values, build-time-only arguments, and Compose declarations. Picking the right one matters: some persist into the image (visible in docker history), some live only during the build, and none of them are a safe place for secrets.
| Method | Example | Description |
|---|---|---|
docker run -e NODE_ENV=prod nginx | • Sets single runtime variable at container start • visible in docker inspect, so unsuitable for secrets. | |
docker run --env-file .env nginx | • Loads variables from a file, one VAR=value per line• # starts a line comment; no shell-style $VAR interpolation. | |
ENV NODE_ENV=production | • Bakes a variable into the image for build AND runtime • persists in every container; bad for secrets (visible in docker history). | |
ARG VERSION=1.0 | • Build-time only, passed with --build-arg• not in the final image's runtime env, but still visible in docker history. | |
environment: NODE_ENV: prod | • Sets variables on a service via list or map syntax • supports ${VAR} interpolation from host shell or project .env file. | |
env_file: webapp.env | • Loads container env from one or more external files • later files override earlier ones; distinct from the project .env used for ${VAR} interpolation. |
Table 26: Inspect and Debug
Once a container is running you need ways to look inside it, watch what the daemon is doing, see where your disk went, and get a shell into images that don't have one. This table covers the broader Docker inspect family — the --format Go template idiom for scripting, the system-level views (events, df, info, version), and Docker Desktop's debug and init helpers.
| Command | Example | Description |
|---|---|---|
docker inspect --format '{{.State.Status}}' web | • Returns low-level JSON config for any Docker object • pair with --format Go templates to extract one field (canonical scripting pattern). | |
docker events --since 1h --filter type=container | • Continuous stream of daemon lifecycle events (create, start, die, kill, oom, etc.) • bound it with --since/--until and --filter or it blocks forever. | |
docker system df -v | • Reports Docker-managed disk usage across images, containers, volumes, and build cache • -v adds a per-item reclaimable breakdown. | |
docker system info | • Shows runtime configuration — storage driver, cgroup driver, kernel version, containerd/runc versions, container counts • aliased as docker info. | |
docker version | Prints client and server version numbers, the Engine API version, and component versions (containerd, runc, docker-init). Different from docker info. | |
docker debug web | • Attaches a debug shell with its own toolbox (vim, htop, curl, plus Nix packages) to any container or image, even distroless/scratch with no shell • Docker Desktop only, paid subscription required. | |
docker init | • Scaffolds Dockerfile, compose.yaml, .dockerignore, README.Docker.md for a new project • templates for Go, Node, Python, Rust, Java, PHP, ASP.NET Core. |
Table 27: Copy Operations
How to move files in and out of containers with docker cp — a one-shot snapshot copy (not a live sync like a bind mount) that works on both running and stopped containers, making it the right tool for post-mortem retrieval and surgical config injection.
| Command | Example | Description |
|---|---|---|
docker cp web:/app/log.txt ./log.txt | • Copies file from container to host • works on running and stopped containers. | |
docker cp ./config.yml web:/app/config.yml | • Copies file from host to container • immediately available in running container. | |
docker cp web:/app/logs ./logs | Recursively copies entire directories (no -r flag — recursion is the default). | |
docker cp -a web:/app ./backup | • Preserves UID/GID and permissions • equivalent to cp -a. |
Table 28: BuildKit Advanced Features
BuildKit unlocks the modern Docker build pipeline: persistent caches that survive between builds, secret and SSH credentials that never touch image layers, attestations that prove what shipped, and Bake for orchestrating multi-target build matrices.
| Feature | Example | Description |
|---|---|---|
RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt | • Mounts a persistent package-manager cache for one RUN step• data lives in the builder, not in image layers, and is reused across builds. | |
RUN --mount=type=ssh git clone git:repo(invoke with docker build --ssh default) | • Forwards the host's SSH agent socket into a single RUN step• lets builds clone private Git repos without a key entering the image. | |
RUN --mount=type=bind,target=. go build -o /app/hello | • Mounts build-context files into the step without COPY• files are read-only by default and never enter image layers or the cache. | |
docker buildx build --cache-from type=registry,ref=user/app:buildcache --cache-to type=registry,ref=user/app:buildcache,mode=max . | • Pushes/pulls build cache to a remote location (registry, S3, GHA) • lets ephemeral CI runners share cache and stay fast. | |
docker buildx build --cache-to type=inline --cache-from <image> -t app . | • Embeds cache metadata inside the published image itself • simplest registry-backed cache, but only supports mode=min. | |
docker buildx build --sbom=true -t myapp . | • Attaches an SPDX Software Bill of Materials as an OCI attestation • lists packages found in the image so scanners (Scout, Trivy) can flag CVEs. | |
docker buildx build --provenance=mode=max -t myapp . | • Attaches a SLSA-format provenance record proving what source, frontend, and parameters produced the image • mode=max adds the Dockerfile and LLB; mode=min is the default. | |
docker buildx bake -f docker-bake.hcl(HCL defines target and group blocks) | • Runs multiple build targets concurrently from an HCL/JSON/Compose file • supports variables, inheritance, and matrix targets for monorepos and multi-arch fan-out. |
Table 29: Docker Scout Commands
Docker Scout is Docker's built-in supply-chain security tool: it reads an image's SBOM (generating one if missing), looks up known CVEs against it, and suggests safer base images. These CLI commands are the day-to-day surface — triaging vulnerabilities, comparing image versions, and enrolling an organization for policy enforcement.
| Command | Example | Description |
|---|---|---|
docker scout cves nginx:latest | • Scans an image for CVEs • shows severity, CVSS score, affected package, and fix availability. | |
docker scout quickview nginx:latest | • Displays a summary of vulnerabilities and policy compliance • fast overview without printing the full CVE list. | |
docker scout recommendations nginx:latest | • Suggests base image refresh or update • shows benefits like fewer CVEs and smaller image size for each alternative. | |
docker scout sbom nginx:latest | • Generates a Software Bill of Materials • lists every package and version (SPDX or CycloneDX output adds licenses and relationships). | |
docker scout compare nginx:1.25 --to nginx:latest | • Compares vulnerability profiles of two image versions • canonical way to verify a base image bump actually reduced CVEs. | |
docker scout enroll myorg | • Enrolls an organization in Docker Scout • required before policy enforcement, repository integration, and team dashboards work for org images. |
Table 30: Docker Model Runner
Docker Model Runner (DMR) is a Docker Desktop / Docker Engine feature for pulling, running, and serving local AI models with a docker model CLI that mirrors familiar image commands. Models are stored as OCI artifacts separately from container images, run on a host-native inference server (llama.cpp by default), and are reachable over OpenAI-, Anthropic-, and Ollama-compatible HTTP APIs. As of Docker Desktop 4.71, DMR is disabled by default and must be explicitly enabled in Settings.
| Command | Example | Description |
|---|---|---|
docker model pull ai/llama3.2 | • Downloads a model from Docker Hub, an OCI registry, or Hugging Face • stored locally as OCI artifacts in a separate model store (not in docker images). | |
docker model run ai/llama3.2 | • Runs a one-time prompt or starts an interactive chat in the terminal • the model is loaded on demand and unloaded after ~5 min idle. | |
docker model run -d ai/llama3.2 | • Pre-loads the model into memory without an interactive session • the OpenAI-compatible REST API is always served by Model Runner — -d just warms the cache. | |
docker model list | Lists locally pulled models with size, parameters, and quantization (alias: docker model ls). | |
docker model rm ai/llama3.2 | Removes a model from the local model store to reclaim disk space. | |
curl http://model-runner.docker.internal/engines/v1/chat/completions | • Reach the running model via OpenAI-, Anthropic-, or Ollama-compatible endpoints (including /responses for the OpenAI Responses API)• from containers use model-runner.docker.internal; from the host use http://localhost:12434/engines/v1. |
Table 31: Docker Build Cloud
Docker Build Cloud is a paid Docker subscription add-on that runs buildx builds on a managed BuildKit instance in AWS (US East), with a shared persistent build cache and native linux/amd64 + linux/arm64 nodes. Your CLI sends the build context to the remote builder; the resulting image streams back to your local image store or is pushed to a registry. The workflow is a builder swap — same Dockerfile, same docker buildx build.
| Feature | Example | Description |
|---|---|---|
docker buildx create --driver cloud myorg/mybuilder | • Registers a local endpoint for an existing cloud builder (the builder itself is provisioned in the Docker Build Cloud Dashboard) • the local endpoint is named cloud-myorg-mybuilder. | |
docker buildx build --builder cloud-myorg-mybuilder -t myapp . | • Sends the build context to the remote builder • build runs on AWS EC2 with more CPU/RAM than the laptop, then result is loaded back or pushed to a registry. | |
docker buildx use cloud-myorg-mybuilder --global | • Sets the cloud builder as the default for docker buildx build• --global persists the selection across shells; affects docker buildx build only, not the legacy docker build. | |
docker buildx ls | • Lists all builder instances with their driver, endpoint, status, BuildKit version, and supported platforms • the current default is marked with a *. | |
(automatic; see docker buildx du) | • Each cloud builder has a dedicated EBS volume holding a persistent BuildKit cache shared by everyone using that builder • the first teammate's build warms the cache; subsequent local and CI builds reuse it, so cold starts on fresh runners stop paying full rebuild cost. | |
docker buildx build --builder cloud-myorg-mybuilder --platform linux/amd64,linux/arm64 -t myapp --push . | • The cloud builder has native linux/amd64 and linux/arm64 nodes• each platform runs on its real CPU in parallel with no QEMU emulation overhead — typically much faster than emulated cross-builds on a single-arch laptop or CI runner. |
Table 32: Compose Dependency Conditions
The depends_on long syntax accepts a condition that controls when Compose considers a dependency satisfied before starting the dependent service. Picking the right condition is how you turn a fragile "container is up" hint into a real readiness gate — or a one-shot migration step.
| Condition | Example | Description |
|---|---|---|
depends_on: db: condition: service_started | • Default behavior — waits only for the dependency container to be started • does not wait for the app inside to be ready, so first connections can still fail. | |
depends_on: db: condition: service_healthy | • Waits for the dependency's healthcheck to report healthy• requires a HEALTHCHECK in the image or a healthcheck: block; without one, the dependent never starts. | |
depends_on: migrate: condition: service_completed_successfully | • Waits for a one-off dependency to exit with code 0 • canonical "run migrations first" pattern; non-zero exit blocks the dependent. |
Table 33: Distroless and Minimal Images
Choosing a smaller base image shrinks the attack surface, the CVE footprint, and the pull/startup time — but each minimal base trades away something. This table compares the common minimal-base options so you can pick by what your app actually needs at runtime (a shell, a libc, a package manager, none of the above).
| Image | Example | Description |
|---|---|---|
FROM alpine:3.21 | • Lightweight ~5 MB base • uses musl libc (not glibc), so prebuilt Python/Node binary wheels and other glibc-linked binaries may fail or need recompiling. | |
FROM gcr.io/distroless/static-debian12 | • No shell, no package manager — only your app and its runtime deps • static is ~2 MB, ~50% of alpine's size; reduces attack surface and CVE noise. | |
FROM scratch | • Completely empty base — no libc, no shell, no files • works only for statically linked binaries (e.g. Go with CGO_ENABLED=0, Rust with a musl target). | |
FROM gcr.io/distroless/base-debian12:debug | • Adds a busybox shell on top of distroless so you can docker run --entrypoint=sh• intended for local debugging, never production. | |
FROM dhi.io/python:3.13 | • Docker's distroless-based, near-zero-CVE images on alpine or debian foundations • free under Apache 2.0 since Dec 17 2025, ship with SBOM + SLSA provenance attestations, patched on a tight SLA. |
Table 34: Docker AI (Gordon)
Gordon is Docker's AI-powered assistant available from Docker Desktop 4.74+ and the docker ai CLI. It reads your live Docker environment — running containers, logs, images, Compose files — proposes actions, and executes them only after your approval. Gordon on Docker Hub and docs.docker.com is free with no Docker account required; CLI and Docker Desktop usage counts against a usage plan.
| Command | Example | Description |
|---|---|---|
docker ai | • Opens an interactive terminal UI for Gordon • type questions or tasks; Gordon proposes actions and waits for y approval before executing. | |
docker ai "show me logs from my nginx container" | • Runs a one-off prompt without the full TUI • Gordon reads the environment, proposes relevant commands (e.g. docker logs), and runs them on approval. | |
docker ai "review my Dockerfile for best practices" | • Analyzes the Dockerfile in the current directory and suggests optimizations: smaller base, layer order, cache hits, secret handling • Gordon can apply the edits in-place. | |
docker ai "why did my db container crash" | • Reads container logs and inspect output, diagnoses the root cause, and suggests a fix • any proposed docker commands shown before execution. | |
(Docker Desktop sidebar → Gordon) | • Same capabilities as CLI Gordon but with a graphical session sidebar • lets you link a project directory and run queries with richer visual output. |
Table 35: Docker MCP Toolkit
The Docker MCP Toolkit (docker mcp) makes it trivial to install, run, and connect 120+ containerized Model Context Protocol (MCP) servers — GitHub, Playwright, Slack, Grafana, and more — to AI clients such as Claude Desktop, Cursor, VS Code, and Gordon. Each server runs in an isolated container with Docker's security model. Requires Docker Desktop 4.62+.
| Command | Example | Description |
|---|---|---|
docker mcp profile create --name web-dev | • Creates a named profile — a workspace that organizes a set of MCP servers • profiles are the unit of sharing; push/pull via docker mcp profile push/pull <oci-ref>. | |
docker mcp profile server add web-dev --server catalog://mcp/docker-mcp-catalog/github-official | • Adds a server to a profile using a catalog URI ( catalog://), Docker image URI (docker://), local YAML (file://), or HTTPS registry URL• servers requiring OAuth show "Configuration Required" in Docker Desktop. | |
docker mcp gateway run --profile web-dev | • Starts the MCP Gateway over stdio with the given profile's servers• used to connect any AI client manually via its MCP JSON config ( "command": "docker", "args": ["mcp", "gateway", "run", "--profile", "web-dev"]). | |
docker mcp client connect vscode --profile my-project | • Connects a named supported client (claude, cursor, vscode, etc.) to a profile • writes the appropriate client-specific config file (e.g. .vscode/mcp.json). | |
docker mcp catalog server ls mcp/docker-mcp-catalog | • Lists all servers in the Docker MCP Catalog (or a custom catalog) by name and ID • the Server ID is used in catalog://mcp/docker-mcp-catalog/<server-id> URIs. | |
docker mcp profile list | • Lists all local profiles • use docker mcp profile show <id> for servers and config in one profile | |
docker mcp profile export web-dev .docker/mcp-profile.json | • Exports a profile to a JSON file for version-control sharing with teammates • credentials are excluded; recipients configure secrets separately after docker mcp profile import. |
Table 36: Docker DHI CLI
The docker dhi CLI plugin (Docker Desktop 4.65+) manages Docker Hardened Images: browse the catalog, view SBOM/provenance attestations, mirror images into your organization's registry, and create customized variants that add your own packages on top of a DHI base. A standalone dhictl binary is also available for headless CI environments.
| Command | Example | Description |
|---|---|---|
docker dhi catalog list --filter golang | • Lists available DHI images; filter by name, --fips, or --stig• docker dhi catalog get golang shows available tags and CVE counts for a specific image. | |
docker dhi attestation sbom dhi/nginx:1.27 | • Displays the SPDX SBOM attached to a DHI image as an OCI attestation • docker dhi attestation list dhi/nginx:1.27 shows all attestation types including provenance. | |
docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang | • Begins automatically mirroring a DHI image into your Docker Hub organization registry • --dependencies also mirrors base layers; Docker patches the mirror on its SLA. | |
docker dhi mirror list --org my-org | Lists all DHI images currently mirrored to your organization with their status. | |
docker dhi customization prepare golang 1.25 --org my-org --destination my-org/dhi-golang> my-customization.yaml | • Generates a YAML scaffold for creating a custom variant of a DHI image • edit the YAML to add packages or configuration, then docker dhi customization create. | |
docker dhi customization create my-customization.yaml --org my-org | • Submits the customization YAML to Docker to build a custom DHI variant and push it to your org registry • docker dhi customization build logs <id> <build-id> streams the build output. | |
docker dhi auth apk | • Generates enterprise package repository credentials for installing Docker-patched packages in your own images • apk for Alpine-based images, deb for Debian-based images. |