Essential Docker Commands: The Complete Cheat Sheet

It was 2 AM on a Saturday. The checkout service returned 500s. kubectl logs showed no space left on device. The culprit? Overlay2 storage had accumulated 47GB of dangling layers from months of CI/CD builds. Nobody had run docker system prune. The fix took 30 seconds. Finding it took 90 minutes.

Pick the Right Command for the Symptom

Most "I forgot the docker command for X" lookups boil down to a small decision tree. Route by symptom, not by concept:

graph TD
    Start[What do I need?] --> Type{Container,<br/>image, volume,<br/>or network?}
    Type -->|Container| Cstate{Running or<br/>stopped?}
    Cstate -->|Running| Crun[ps · exec · logs · stats]
    Cstate -->|Stopped| Cstop[ps -a · start · rm]
    Type -->|Image| Iaction{Build, list,<br/>or clean?}
    Iaction -->|Build| Ibuild[build · tag · push]
    Iaction -->|List| Ilist[images · history · inspect]
    Iaction -->|Clean| Iclean[image prune · system prune]
    Type -->|Volume| Vol[volume ls · volume inspect · volume rm]
    Type -->|Network| Net[network ls · network inspect · network connect]
    style Crun fill:#dfd
    style Ibuild fill:#dfd
    style Vol fill:#dfd
    style Net fill:#dfd

The diagram is the cheat-sheet within the cheat-sheet — every command in the rest of this file lives at a leaf of that tree.

The Quick Start

Images and Builds

## Build from Dockerfile
docker build -t myapp:v1.0 .
 
## Build with build args
docker build --build-arg NODE_ENV=production -t myapp:prod .
 
## Pull specific version (always use tags, never :latest)
docker pull postgres:16-alpine
 
## Tag and push to registry
docker tag myapp:v1.0 registry.company.com/myapp:v1.0
docker push registry.company.com/myapp:v1.0
 
## Check image disk usage
docker system df
 
## Remove dangling images
docker image prune -f
 
## Remove all unused images
docker image prune -a -f

Registry login: docker login (Docker Hub), aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com (ECR), or gcloud auth configure-docker (GCP).

Dockerfile Basics

## Multi-stage build: fast rebuilds, tiny final image
FROM golang:1.23-bookworm AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /server ./cmd/server
 
FROM scratch
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Layer caching rule: Put rarely-changing instructions (RUN apt-get install) first, frequently-changing ones (COPY . .) last. Docker reuses cached layers if nothing changed in that layer or before it.

The image lifecycle in one picture — build → push → pull → run → exit:

graph LR
    DF[Dockerfile + source] -->|docker build| Img[Image<br/>layered SHA256<br/>local cache]
    Img -->|docker push| Reg[(Registry<br/>ECR / GCR / Hub)]
    Reg -->|docker pull| Node[Node-local cache<br/>per-host image store]
    Node -->|docker run<br/>or kubelet| Cont[Container<br/>writable top layer<br/>+ ephemeral fs]
    Cont -->|docker exec| Shell[Interactive shell<br/>or one-shot command]
    Cont -->|exit / SIGKILL| Stopped[Stopped container<br/>filesystem preserved]
    Stopped -->|docker rm| Gone[Gone — top layer deleted]
    Stopped -->|docker start| Cont
    Cont -.->|docker commit<br/>rare, manual| Img
    Cont -.->|volume mount| Vol[(Named volume<br/>survives container)]
    style Cont fill:#dfd
    style Reg fill:#ffd
    style Vol fill:#ffd

The diagram captures every command's place in the lifecycle: build produces an Image, run instantiates a Container, exec enters a running container, rm deletes the writable layer (the volume survives).

## Inspect layer history
docker image history myapp:v1.0
 
## Get full metadata
docker image inspect myapp:v1.0

Volumes and Storage

## Create named volume
docker volume create myapp-data
 
## List and inspect
docker volume ls
docker volume inspect myapp-data
 
## Clean up unused volumes
docker volume prune -f
 
## Backup a volume
docker run --rm -v myapp-data:/source:ro -v $(pwd):/backup alpine \
  tar czf /backup/backup.tar.gz -C /source .

Networking

## Create custom bridge network
docker network create myapp-network
 
## Containers on same network resolve by name
docker run -d --name api --network myapp-network myapp:v1.0
docker run -d --name db --network myapp-network postgres:16
## Inside api: ping db → resolves to postgres IP
 
## Port mapping variants
docker run -p 8080:80 nginx                   # host:container
docker run -p 127.0.0.1:8080:80 nginx         # localhost only
docker run -p 8080:80/udp nginx               # UDP port

Debugging and Logs

## View logs with timestamps
docker logs --details --timestamps myapp
 
## Follow logs (like tail -f)
docker logs -f --tail=100 myapp
 
## Inspect container state and config
docker inspect myapp | jq '.[0] | {State, Config: {Env}, HostConfig: {Memory}}'
 
## Shell into container
docker exec -it myapp /bin/bash
 
## Run command without interactive shell
docker exec myapp curl http://localhost:8080/health
 
## Monitor CPU/memory usage
docker stats --no-stream
 
## Watch events in real time
docker events --filter type=container

Production Cleanup

## Check disk usage (images, containers, volumes, build cache)
docker system df -v
 
## The lifesaver: remove dangling layers, old containers, unused images
docker system prune -a --volumes --filter "until=24h"
## Run as daily cron job on build servers to prevent disk exhaustion

When to use what

Gotchas that bite in production

1. docker system prune -a removes ALL unused images, including base layers you'll rebuild

   • You run it Friday evening: docker system prune -a --volumes. Monday morning, every build is 5 minutes slower because it's rebuilding base layers from scratch.
   • Fix: Use docker image prune (no -a) to remove dangling images only. Run docker system prune -a --filter "until=72h" on build servers during off-peak to preserve recent layers.

2. docker run -d app with no healthcheck dies silently, deployments continue

   • Container crashes immediately (OOM, permission denied, missing binary). Docker marks it as exited. Orchestration thinks it's fine because no restart policy is set. Your service serves 503s for hours.
   • Fix: Always set --health-cmd or define HEALTHCHECK in Dockerfile. Pair with --restart=on-failure:3 in docker-compose to catch startup failures immediately.

3. COPY . . before RUN npm install invalidates layer cache on every code change

   • You edit one line of code. Build restarts from "RUN npm install" (cache miss) and rebuilds 500MB of node_modules. Takes 3 minutes instead of 5 seconds.
   • Fix: Separate dependency layer from code layer:

     COPY package.json package-lock.json ./
     RUN npm ci
     COPY . .
     RUN npm run build

4. docker exec on a stopped container silently does nothing

   • You're debugging a crashed container, think you ran a command to check logs, but the container was stopped. You start troubleshooting the wrong thing.
   • Fix: Always check container state first: docker inspect myapp | grep State. Use docker logs myapp --previous for crash dumps instead.

5. Image pulls timeout in production during peak traffic

   • New deployment triggers and pulls a 2GB image. Registry is slow, pull times out after 2 minutes. Replica stays pending. Load moves to remaining pods, they get OOMKilled. Cascading failure.
   • Fix: Always docker pull image to all nodes before deployment (warming the cache). Use multi-registry (Quay + ECR fallback) for redundancy. Set pull_policy: always in your compose file to ensure fresh images on deploy.

Common Gotchas

1. Always specify image versions — never :latest in production. docker pull postgres:latest gets a different image next month.

2. Build args are not secrets — ARG GITHUB_TOKEN=... is visible in docker image history. Use BuildKit secret mounts instead: RUN --mount=type=secret,id=token npm ci.

3. --privileged is root access — never use in production. It gives the container full access to the host's devices. Debug locally only.

4. docker rm doesn't remove images — use docker rmi myapp:v1.0. Removing images doesn't clean the build cache.

5. Dangling layers kill disk space — docker system prune -a --volumes removes untagged images and build cache. Set up as daily cron job on build servers.

6. Port mapping to localhost doesn't broadcast — docker run -p 127.0.0.1:8080:80 nginx listens on localhost only. docker run -p 8080:80 nginx listens on 0.0.0.0 (externally accessible).

Docker image security: the SBOM workflow

Audits and supply-chain attacks have made image provenance non-negotiable. The standard pipeline is build → SBOM → scan → sign → verify, and each step has a one-line tool. An SBOM (Software Bill of Materials) inventories every package, version, and license inside the image; a vulnerability scanner cross-references it against CVE databases; a signature proves the image came from your build pipeline and has not been swapped at the registry.

Generate an SBOM with Syft, scan it with Grype, then sign with cosign and a keyless OIDC identity provided by Sigstore. The same workflow runs in CI (block the push on critical CVEs) and at admission time in Kubernetes (reject unsigned images via Kyverno or Connaisseur).

## 1. Generate SBOM in CycloneDX format (also supports SPDX, syft-json)
syft myapp:v1.0 -o cyclonedx-json=sbom.json
 
## 2. Scan the SBOM, fail the build on Critical / High CVEs
grype sbom:sbom.json --fail-on high --only-fixed
 
## 3. Sign the image keyless via Sigstore (uses GitHub OIDC token in CI)
cosign sign --yes registry.company.com/myapp:v1.0
 
## 4. Attach the SBOM as an attestation to the image
cosign attest --yes --predicate sbom.json \
  --type cyclonedx registry.company.com/myapp:v1.0
 
## 5. At deploy time, verify signature + SBOM attestation
cosign verify \
  --certificate-identity-regexp "https://github.com/company/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  registry.company.com/myapp:v1.0

The keyless flow eliminates the long-lived signing key that previously had to live in a vault. The OIDC token from GitHub Actions (or any compliant CI) is exchanged for a short-lived certificate at Sigstore's Fulcio, the signature is recorded in Rekor's transparency log, and verifiers check both. If an attacker pushes a malicious image without the matching OIDC identity, cosign verify fails and the deployment is rejected.

Pin the base image by digest, not tag: FROM gcr.io/distroless/base@sha256:abcd... instead of FROM gcr.io/distroless/base:latest. Tags are mutable; digests are not. Combined with cosign verification, this closes the registry-poisoning attack vector entirely.

Production Dockerfile patterns

Three patterns separate hobbyist Dockerfiles from production ones: distroless final stages, BuildKit cache mounts, and --mount=type=secret for build-time credentials. Each cuts image size, build time, or attack surface — and they compose.

## syntax=docker/dockerfile:1.7
## Rust example: cache mount keeps cargo registry warm across builds
FROM rust:1.83-bookworm AS builder
WORKDIR /app
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    --mount=type=cache,target=/app/target \
    cargo build --release --locked && \
    cp target/release/server /server
 
## Distroless final stage — no shell, no package manager, no CVE surface
FROM gcr.io/distroless/cc-debian12:nonroot
COPY --from=builder /server /server
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/server"]

The cache mount survives across builds without bloating the image (it lives in BuildKit's cache, not in any layer). For a Rust monorepo, this turns five-minute compiles into thirty-second incremental builds.

For Java services, the analogous pattern uses Maven's repository cache plus a JLink-trimmed JRE in the runtime stage:

## syntax=docker/dockerfile:1.7
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /app
COPY pom.xml ./
RUN --mount=type=cache,target=/root/.m2 mvn -B dependency:go-offline
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 \
    mvn -B -DskipTests package && \
    jlink --add-modules java.base,java.logging,java.sql,java.naming \
          --strip-debug --no-header-files --no-man-pages \
          --output /jre
 
FROM gcr.io/distroless/java-base-debian12:nonroot
COPY --from=builder /jre /jre
COPY --from=builder /app/target/app.jar /app.jar
USER nonroot:nonroot
ENTRYPOINT ["/jre/bin/java", "-jar", "/app.jar"]

Build-time secrets: never ARG GITHUB_TOKEN — it lands in image history. Use --mount=type=secret:

DOCKER_BUILDKIT=1 docker build \
  --secret id=npmrc,src=$HOME/.npmrc \
  -t myapp:v1.0 .

Inside the Dockerfile: RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci. The secret is mounted only for that RUN step and never written to a layer.

Container debugging in production

When a container misbehaves in production, the diagnostic flow is roughly: check liveness, then resource pressure, then in-process state, then kernel-level signals. Each step has one or two commands and rules out a class of failure before you escalate.

## 1. Is the container actually alive? Did it OOM-kill recently?
docker inspect --format \
  '{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} pid={{.State.Pid}}' \
  myapp
 
## 2. Resource pressure — CPU throttling and memory headroom
docker stats --no-stream --format \
  "table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}\t{{.MemUsage}}\t{{.NetIO}}"
 
## 3. What is the container actually doing? PID + threads inside namespace
docker top myapp -o pid,ppid,pcpu,pmem,etime,stat,wchan,cmd
 
## 4. Real-time event stream — restarts, OOMs, health-check transitions
docker events --filter container=myapp \
  --filter event=die --filter event=oom --filter event=health_status
 
## 5. When exec fails because the container has no shell (distroless)
docker run -it --rm --pid=container:myapp --net=container:myapp \
  --cap-add=SYS_PTRACE nicolaka/netshoot

The last command is the workhorse for distroless images: it joins the target container's PID and network namespaces using a debug image that has tcpdump, strace, dig, curl, nc, and lsof. From inside it, strace -p 1 attaches to the application's PID 1 to see what syscalls it is blocked on, and ss -tnlp lists every listening socket without modifying the production image.

One concrete diagnostic flow for "service returns 503 intermittently": run docker stats to rule out CPU throttling, run docker top to confirm the worker count matches expectations, run docker exec myapp curl -s localhost:8080/metrics | grep http_requests to read in-process counters, and finally docker events --since 10m to spot whether the orchestrator killed and restarted a replica during the window. Most production debugging never needs to leave these four commands — the discipline is running them in order rather than guessing.

Frequently Asked Questions

Production Checklist

• Images tagged with specific versions, never :latest
• docker system prune -a --volumes --filter "until=24h" runs daily on build servers
• Containers run as non-root USER in Dockerfile
• Health checks configured in compose files or run commands
• Memory limits set: docker run --memory="512m" myapp
• Volumes for persistent data (database, logs, caches)
• Private registry configured for sensitive images
• .dockerignore excludes .git, node_modules, *.md, .env files
• Multi-stage Dockerfile with build stage and minimal final stage
• Build process scanned for CVEs before pushing: docker scout cves myapp:v1.0 --exit-code

Keep Reading

• Essential Kubernetes Commands Cheat Sheet — The kubectl commands for deploying, debugging, and managing the containers Docker builds
• Essential Linux Commands Cheat Sheet — Process management, networking, and disk commands you will use when debugging inside containers
• Graceful Shutdown in Production Go Services — Handling SIGTERM correctly so docker stop drains in-flight requests instead of dropping them