The Docker handbook

$ docker run hello-world              # pulls an image, runs it, prints, exits

$ docker run -it --rm alpine sh       # a whole Linux userland, in about a second
/ # cat /etc/os-release
NAME="Alpine Linux"                   # ...even if your host is Ubuntu or macOS
/ # ps
PID   USER     COMMAND
    1 root     sh                     # your shell is PID 1. it sees nothing else.
/ # exit                              # --rm means the container is deleted on exit

$ docker run -d -p 8080:80 --name web nginx
$ curl localhost:8080                 # a web server, no install, no config

# SLOW — re-installs every dependency on any source change
FROM node:20-alpine
WORKDIR /app
COPY . .                  # ← changes whenever ANY file changes...
RUN npm ci                # ← ...so this 90-second step never hits cache
CMD ["node", "server.js"]

# FAST — dependencies only reinstall when the lockfile changes
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./   # ← rarely changes
RUN npm ci                                # ← cached until the lockfile does
COPY . .                                  # ← cheap layer, changes constantly
CMD ["node", "server.js"]

$ docker history myapp:1.0
IMAGE          CREATED         CREATED BY                       SIZE
a1b2c3d4       2 minutes ago   CMD ["node" "server.js"]         0B
<missing>      2 minutes ago   COPY . . # buildkit              12MB
<missing>      5 minutes ago   RUN npm ci # buildkit            180MB    ← the big one
<missing>      5 minutes ago   COPY package*.json ./            4.1kB
<missing>      3 weeks ago     /bin/sh -c #(nop) CMD ["node"]   0B

$ docker image inspect myapp:1.0 --format '{{.RootFS.Layers}}'   # the content hashes

$ docker run -d --name web nginx     # create + start
$ docker ps                          # RUNNING containers only
$ docker stop web                    # SIGTERM, then SIGKILL after 10s
$ docker ps                          # empty — but the container still exists
$ docker ps -a                       # -a = ALL, including exited. here it is.
CONTAINER ID   IMAGE   STATUS                     NAMES
9f2c8ad1c41d   nginx   Exited (0) 12 seconds ago  web

$ docker start web                   # same container, same files, back up
$ docker rm -f web                   # -f stops it first. NOW it's gone.

$ docker container prune             # delete every stopped container
$ docker system df                   # what Docker is using your disk for

docker run [FLAGS] IMAGE [COMMAND] [ARGS...]
           └─ for docker    └─ what to run instead of the image's CMD

$ docker run -d --name api -p 3000:3000 -e NODE_ENV=production myapp:1.0
$ docker run --rm -it node:20-alpine node --version   # override the CMD

$ docker inspect api --format '{{.State.Status}} {{.State.ExitCode}}'
exited 137                                       # OOM killed

$ docker inspect api --format '{{json .Mounts}}' | jq        # where is data going?
$ docker inspect api --format '{{.NetworkSettings.IPAddress}}'
$ docker inspect api --format '{{range .Config.Env}}{{println .}}{{end}}'
$ docker inspect api --format '{{.State.Health.Status}}'     # if a HEALTHCHECK exists

# which host port did Docker pick?
$ docker port api
3000/tcp -> 127.0.0.1:3000

# 1. It exited. What did it say on the way out?
$ docker logs api

# 2. Nothing useful? Start it with a shell INSTEAD of its normal command.
$ docker run --rm -it --entrypoint sh myapp:1.0
/app # ls -la              # are the files where you think?
/app # cat package.json
/app # node server.js      # run it by hand and watch it fail properly

# 3. Image has no shell (distroless/scratch)? Attach one.
$ docker run --rm -it --pid=container:api --network=container:api \
      nicolaka/netshoot

# 4. Copy a file out of a dead container to look at it
$ docker cp api:/app/config.json ./config.json

# 5. What changed in the container's filesystem since it started?
$ docker diff api
C /app
A /app/tmp/upload-9f2c.tmp

ghcr.io/acme/myapp:1.4.2
└──┬──┘ └─┬─┘ └─┬─┘ └─┬─┘
   │      │     │     └── tag — a movable pointer, NOT a version guarantee
   │      │     └──────── image name
   │      └────────────── namespace / user / org
   └───────────────────── registry. omitted = docker.io (Docker Hub)

nginx                    →  docker.io/library/nginx:latest
acme/myapp:1.0           →  docker.io/acme/myapp:1.0
ghcr.io/acme/myapp:1.0   →  GitHub Container Registry
myapp@sha256:9f2c8a...   →  a digest. immutable. the only truly reproducible form.

$ docker build -t myapp:1.0 .          # -t tags it; "." is the BUILD CONTEXT
$ docker build -t myapp:1.0 -f docker/Dockerfile.prod .
$ docker images                         # what's local
$ docker pull postgres:16-alpine        # fetch without running

# tag = add another name to the SAME image. it doesn't copy anything.
$ docker tag myapp:1.0 ghcr.io/acme/myapp:1.0
$ docker login ghcr.io
$ docker push ghcr.io/acme/myapp:1.0

$ docker rmi myapp:1.0                  # remove one image
$ docker save myapp:1.0 | gzip > myapp.tgz     # move an image without a registry
$ gunzip -c myapp.tgz | docker load

# syntax=docker/dockerfile:1          # opt into the latest BuildKit features

FROM node:20-alpine                    # the base. every Dockerfile starts here.

WORKDIR /app                           # cd, and mkdir -p if it doesn't exist.
                                       # use this, never "RUN cd /app" — cd doesn't persist

RUN apk add --no-cache tini            # system packages. one RUN = one layer.

COPY package.json package-lock.json ./ # dependency manifests FIRST — see section 02
RUN npm ci --omit=dev

COPY . .                               # source last: the layer that always changes

ENV NODE_ENV=production \              # available at build AND run time
    PORT=3000

EXPOSE 3000                            # DOCUMENTATION ONLY. does not publish a port.

USER node                              # drop root. everything after runs as `node`.

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1

ENTRYPOINT ["/sbin/tini", "--", "node"]  # the executable
CMD ["server.js"]                        # its default argument, overridable

ENTRYPOINT ["node"]        CMD ["server.js"]
$ docker run myapp                    →  node server.js
$ docker run myapp --inspect          →  node --inspect        # CMD replaced
$ docker run --entrypoint sh myapp    →  sh                    # ENTRYPOINT overridden

# CMD alone — simplest, fully overridable. fine for most apps.
CMD ["node", "server.js"]
$ docker run myapp bash               →  bash

# ENTRYPOINT alone — the image IS the tool.
ENTRYPOINT ["curl"]
$ docker run mycurl https://example.com   →  curl https://example.com

ARG NODE_VERSION=20            # BUILD time only. gone at runtime.
FROM node:${NODE_VERSION}-alpine

ARG BUILD_ID                   # must be re-declared after FROM to be usable
ENV APP_VERSION=${BUILD_ID}    # promote it into the image if the app needs it

ENV LOG_LEVEL=info             # BUILD and RUN time. overridable with -e.

# $ docker build --build-arg BUILD_ID=abc123 -t myapp .
# $ docker run -e LOG_LEVEL=debug myapp        ← ENV can be overridden, ARG cannot

COPY src/ /app/src/                  # trailing slash = directory
COPY --chown=node:node . /app        # set ownership as you copy — saves a RUN chown layer
COPY --from=builder /app/dist ./dist # from another BUILD STAGE — see section 08
COPY --from=nginx:alpine /etc/nginx/nginx.conf ./   # or straight out of another image

# syntax=docker/dockerfile:1

# ---------- stage 1: install + build ----------
FROM node:20 AS builder
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci                              # ALL deps, including dev — we need them to build

COPY . .
RUN npm run build                       # produces /app/dist
RUN npm prune --omit=dev                # strip devDependencies from node_modules

# ---------- stage 2: the image that ships ----------
FROM node:20-alpine AS final
WORKDIR /app
ENV NODE_ENV=production

COPY --from=builder --chown=node:node /app/node_modules ./node_modules
COPY --from=builder --chown=node:node /app/dist ./dist
COPY --from=builder --chown=node:node /app/package.json ./

USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

FROM golang:1.23 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /bin/app ./cmd/server
     #  ↑ static binary, no libc needed at all

FROM scratch                            # literally empty
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /bin/app /app
USER 65534:65534                        # nobody
ENTRYPOINT ["/app"]
# final image: ~8 MB, containing one binary and a CA bundle. Nothing to exploit.

# named volume — Docker manages the location. the default choice for data.
$ docker volume create pgdata
$ docker run -d --name db -v pgdata:/var/lib/postgresql/data \
      -e POSTGRES_PASSWORD=secret postgres:16-alpine

$ docker rm -f db                     # container gone
$ docker run -d --name db -v pgdata:/var/lib/postgresql/data ... postgres:16-alpine
                                      # ...and every row is still there

# bind mount — live editing. no rebuild between saves.
$ docker run -d --name web \
      -v "$(pwd)/src:/app/src" \      # absolute path required
      -v "$(pwd)/nginx.conf:/etc/nginx/nginx.conf:ro" \   # :ro = read-only
      -p 3000:3000 myapp:dev

# tmpfs — in RAM, never written to disk
$ docker run --tmpfs /tmp:rw,size=64m myapp

# managing volumes
$ docker volume ls
$ docker volume inspect pgdata        # where is it really?
$ docker volume rm pgdata             # refuses if a container uses it
$ docker volume prune                 # delete every unused volume. DESTROYS DATA.

$ docker network create appnet

$ docker run -d --name db --network appnet \
      -e POSTGRES_PASSWORD=secret postgres:16-alpine
      # NOTE: no -p. nothing outside the network can reach it.

$ docker run -d --name api --network appnet -p 8080:3000 \
      -e DATABASE_URL=postgres://postgres:secret@db:5432/app \
      myapp:1.0                        #                        ↑ the container NAME

$ docker exec api ping -c1 db          # resolves. this is the payoff.

# inspect and manage
$ docker network ls
$ docker network inspect appnet        # which containers, which IPs
$ docker network connect appnet other  # attach a running container to a second network

# No "version:" key — it's obsolete in Compose v2 and prints a warning.
name: myapp

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: final          # which multi-stage target
    image: myapp:1.0          # name the built image
    ports:
      - "8080:3000"            # quote it — 8080:3000 can parse as a sexagesimal number
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
      NODE_ENV: production
    env_file: [.env]         # everything else
    depends_on:
      db:
        condition: service_healthy   # wait for READY, not just started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 10
    # no ports: — reachable only from inside the stack

  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redisdata:/data

volumes:                    # named volumes must be declared here
  pgdata:
  redisdata:

$ docker compose up -d              # build if needed, create network, start everything
$ docker compose up --build          # force a rebuild
$ docker compose ps                  # status of the stack
$ docker compose logs -f api         # one service; omit the name for all
$ docker compose exec api sh         # shell into a running service
$ docker compose run --rm api npm test   # one-off task in a NEW container
$ docker compose restart api
$ docker compose down                # stop + remove containers and the network
$ docker compose down -v             # ...and the volumes. DELETES DATA.
$ docker compose config              # the fully resolved file — great for debugging

# note: `docker compose` (v2 plugin, current) not `docker-compose` (v1, python, EOL)

FROM node:20-alpine

# many official images already ship a non-root user. node's is `node`.
# if yours doesn't, make one:
RUN addgroup -S app && adduser -S -G app app

WORKDIR /app
COPY --chown=app:app . .
RUN npm ci --omit=dev

USER app                    # everything after this — including CMD — runs as app

CMD ["node", "server.js"]

# verify it took:
# $ docker run --rm myapp id
# uid=101(app) gid=102(app)

$ docker run -d \
    --user 1000:1000 \              # override the image's user
    --read-only \                   # filesystem is immutable...
    --tmpfs /tmp:rw,size=64m \      # ...except where the app genuinely writes
    --cap-drop ALL \                # drop every Linux capability
    --cap-add NET_BIND_SERVICE \    # add back only what's needed (port < 1024)
    --security-opt no-new-privileges \   # block setuid escalation
    --memory 512m --pids-limit 200 \     # blast radius
    myapp:1.0

# NEVER do these unless you know exactly why:
#   --privileged                      disables essentially all isolation
#   -v /var/run/docker.sock:/var/...  container can control the daemon = root on host
#   -v /:/host                        the entire host filesystem

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./

# the secret is mounted for THIS COMMAND ONLY and never enters a layer
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci --omit=dev

# $ docker build --secret id=npmrc,src=$HOME/.npmrc -t myapp .
# prove it: `docker history myapp` and `docker run --rm myapp cat /root/.npmrc`
# both come up empty.

HEALTHCHECK --interval=30s \      # how often
            --timeout=3s \        # fail if the check itself hangs
            --start-period=20s \  # grace while booting; failures here don't count
            --retries=3 \         # consecutive failures before "unhealthy"
  CMD wget -qO- http://localhost:3000/health || exit 1

# exit 0 = healthy, exit 1 = unhealthy. that's the whole contract.

$ docker ps
CONTAINER ID   IMAGE      STATUS                    PORTS
9f2c8ad1c41d   myapp:1.0  Up 2 minutes (healthy)    0.0.0.0:8080->3000/tcp

$ docker inspect api --format '{{json .State.Health}}' | jq
$ docker stats --no-stream
NAME   CPU %   MEM USAGE / LIMIT   MEM %   NET I/O
api    0.51%   142MiB / 512MiB     27.7%   1.2MB / 840kB

# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./

# the npm cache persists across builds but is NOT part of the image
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev

# same idea elsewhere:
#   pip  → --mount=type=cache,target=/root/.cache/pip
#   go   → --mount=type=cache,target=/root/.cache/go-build
#   apt  → --mount=type=cache,target=/var/cache/apt

# push the build cache to the registry so the next CI run starts warm
$ docker buildx build \
    --cache-from type=registry,ref=ghcr.io/acme/myapp:buildcache \
    --cache-to   type=registry,ref=ghcr.io/acme/myapp:buildcache,mode=max \
    -t ghcr.io/acme/myapp:1.0 --push .

# one image that runs on both Apple Silicon and x86 servers
$ docker buildx create --use
$ docker buildx build --platform linux/amd64,linux/arm64 \
    -t ghcr.io/acme/myapp:1.0 --push .

# what did the cache actually do?
$ docker build --progress=plain .      # "CACHED" on each reused step
$ docker build --no-cache .            # prove a cold build still works