Session 03 · 2h

Running containers well

Configuration, storage and networking — everything between "the image builds" and "the app actually runs".

Configuration & signals Storage Networking Limits & health Lab 03

Session 03

What we'll cover today

1 · Configuration & process

ENV, -e, --env-file, ARG vs ENV, CMD vs ENTRYPOINT, exec vs shell form, PID 1 and SIGTERM.

2 · Storage

Why the writable layer disappears; volumes vs bind mounts vs tmpfs; the --mount syntax; volume lifecycle and backups.

3 · Networking, limits, health

User-defined bridges and DNS by container name, port publishing, --memory/--cpus, restart policies, HEALTHCHECK.

4 · Lab 03

Wire the whole Pinboard stack together by hand on pinboard-net with the pinboard-data volume — no Compose yet.

Configuration & the container process

One image, many environments — and one process that has to start and stop cleanly.

12-factor

Configuration comes from the environment

One pinboard-api:1.0 image everywhere; only the environment changes.

ENV in the Dockerfile = the default
-e KEY=value overrides it per container
--env-file for a whole set — no quoting, no shell expansion
Never bake secrets into the image

DB=postgres://pinboard:pinboard-secret@db:5432/pinboard
docker run -d --name api \
  -e DATABASE_URL="$DB" -e APP_THEME=amber \
  pinboard-api:1.0

# or the same set from a file
docker run -d --name api --env-file ./api.env pinboard-api:1.0

docker inspect api --format '{{json .Config.Env}}'

Stress the rule: config in the environment, code in the image. A secret baked into the image stays in the image history forever, which is why it never belongs in a Dockerfile. Show that APP_THEME changes the header colour of the web UI — that is how they will see a rolling update in session 06. Warn about --env-file: it is not a shell script, so KEY="value" keeps the quotes as part of the value. Mention that docker inspect shows every environment variable in clear text, which is exactly why passwords in -e are a stopgap, not a solution.

Don't confuse them

ARG vs ENV

ARG	ENV
Build time only	Build time and run time
Gone from the final image	Baked into the image config
`--build-arg`	`-e` / `environment:`

An ARG value is visible in docker history. Never pass a password that way — use --mount=type=secret.

ARG APP_VERSION=dev

ENV PORT=8080 \
    APP_VERSION=${APP_VERSION}

ENTRYPOINT ["/pinboard-api"]

docker build -t pinboard-api:1.1 \
  --build-arg APP_VERSION=1.1 ./pinboard-api

This is the exact pattern from the Pinboard API Dockerfile they built in Lab 02: the version arrives as a build argument and is promoted to an environment variable so the running process can report it on /api/info. Point out the promotion line — students often expect ARG alone to be readable at run time and it is not.

What runs when the container starts

CMD vs ENTRYPOINT

ENTRYPOINT — the executable. Makes the image behave like a command.
CMD — the default arguments, easy to replace.
Arguments after the image name replace CMD, never ENTRYPOINT.
--entrypoint overrides the executable itself.

ENTRYPOINT ["/pinboard-api"]
CMD ["--log-format=text"]

# runs: /pinboard-api --log-format=text
docker run pinboard-api:1.0

# runs: /pinboard-api --log-format=json
docker run pinboard-api:1.0 --log-format=json

# debug a distroless image? you can't shell in:
docker run --entrypoint /bin/sh alpine -c 'echo hi'

Give the rule of thumb: if the image is a tool, use ENTRYPOINT plus a CMD of defaults; if the image is a base others extend, CMD alone is friendlier. Remind them that the Pinboard API is distroless — there is no shell inside, so --entrypoint /bin/sh fails, and that is a feature, not a bug. In Kubernetes these two become command: and args: — say it now, it saves confusion in session 05.

The form matters

Exec form vs shell form

# shell form → /bin/sh -c "/pinboard-api"
CMD /pinboard-api

# exec form → the binary itself
CMD ["/pinboard-api"]

Always use the JSON array (exec) form for CMD and ENTRYPOINT.

Shell form

sh is PID 1. Your process is a child. sh does not forward signals, and variables like $PORT are expanded.

Exec form

Your process is PID 1 and receives signals directly. No shell, no expansion — and one less process in the image.

Show docker top api for both forms so they see the extra /bin/sh in the shell-form case. The trade-off is real: exec form means no variable expansion, so if you genuinely need $PORT in the command line, write CMD ["sh","-c","exec /pinboard-api --port=$PORT"] — note the exec, which replaces the shell and gives PID 1 back to the binary.

Shutdown

PID 1, SIGTERM and graceful stop

docker stop

You (or the orchestrator) ask the container to stop

→

SIGTERM to PID 1

Only PID 1 gets it — nobody else

→

Grace period

Default 10 s (--stop-timeout) to drain

→

SIGKILL

Unconditional. Exit code 137

Shell form ⇒ sh ignores SIGTERM ⇒ every stop takes the full 10 s and ends in a kill
PID 1 has no default signal handlers and never reaps orphans — --init inserts a tiny init for that
Pinboard API handles SIGTERM and drains for SHUTDOWN_GRACE (default 10s)

This is the slide that pays off in session 06: a Pod that ignores SIGTERM turns every rolling update into dropped connections. Time a docker stop against both forms live — shell form takes ten seconds, exec form is instant. Mention docker stop --timeout 30 and its Kubernetes twin terminationGracePeriodSeconds.

Follow demos/session03/instructions.md Demo 1. The distroless pinboard-api image has no shell, so the shell-form half uses busybox: build Dockerfile.shell (CMD sleep 300) and Dockerfile.exec (CMD ["sleep","300"]), run both, docker top each — shell form shows sh -c as PID 1 with sleep underneath. time docker stop takes ~10 s for both (sleep ignores SIGTERM as PID 1) — the form decides who gets the signal; --init makes it instant (exit 143). Then docker run -d --name api pinboard-api:1.0, time docker stop api returns in under a second with exit code 0, and docker logs api shows "shutting down gracefully".

Storage

Containers are disposable. Your data must not be — the writable layer dies with the container.

Why we need mounts

The writable layer is ephemeral

Image layers

Read-only, shared by every container from that image

Writable layer

Copy-on-write, created per container

→

docker stop / start

Layer survives — data is still there

→

docker rm

Layer deleted — data gone forever

Writes go through an overlay driver: slower than a real filesystem, and unusable for a database's fsync patterns
Anything you want to keep — or share between containers — must be mounted from outside

"The container restarted and my data is gone" is almost always docker rm plus no volume.

Draw the distinction explicitly between stop/start (layer kept) and rm (layer destroyed). Mention docker diff db as a quick way to see what a container has written to its own layer. In Kubernetes this gets worse, not better: a Pod is recreated on any node, so the writable layer is gone every single time.

Three ways to mount

Volumes vs bind mounts vs tmpfs

Volume	Bind mount	tmpfs
Docker owns it (`/var/lib/docker/volumes`)	Any path on the host, you own it	Host RAM only, never on disk
Named, portable, backed by plugins/NFS	Path must exist as you expect on every host	Dies with the container
Best for data: databases, uploads	Best for dev: source and config live-editing	Best for secrets and scratch files
`pinboard-data` for Postgres	`./pinboard-web/html` while styling	`/tmp`, session caches

Default to volumes. Reach for a bind mount when you specifically want the host's files.

The rule of thumb: volumes for state you cannot lose, bind mounts for the inner development loop, tmpfs when the data must never touch a disk. Warn about bind mounts and UIDs — the Pinboard API runs as UID 65532 and nginx as the nginx user, so a bind-mounted host folder owned by root is read-only in practice. All three have Kubernetes counterparts: PersistentVolumeClaim, hostPath (which we will tell them not to use), and emptyDir with medium: Memory.

Syntax

Learn `--mount`, not `-v`

docker volume create pinboard-data

docker run -d --name db --network pinboard-net \
  --mount type=volume,src=pinboard-data,dst=/var/lib/postgresql/data \
  -e POSTGRES_USER=pinboard -e POSTGRES_PASSWORD=pinboard-secret \
  -e POSTGRES_DB=pinboard postgres:17-alpine

docker run --rm -p 8081:8080 --name web-dev \
  --mount type=bind,src="$PWD/pinboard-web/html",dst=/usr/share/nginx/html,ro \
  pinboard-web:1.0

docker run --rm --mount type=tmpfs,dst=/tmp,tmpfs-size=64m alpine df -h /tmp

-v host:container still works, but it creates missing host paths silently and hides the mount type. --mount is explicit and fails loudly.

Read the three lines out loud as "type, source, destination". Point out ro on the bind mount — the web container has no business writing to your source folder. Note that a volume mounted into an empty directory of an image is pre-populated from the image on first use, which is exactly how Postgres initialises PGDATA; a bind mount never does that.

Housekeeping

Volume lifecycle

Volumes outlive containers — that is the whole point
docker rm keeps them; docker rm -v only removes anonymous ones
Anonymous volumes (no src=) pile up invisibly — always name them
docker volume prune deletes everything unused: read the prompt

docker volume ls
docker volume inspect pinboard-data
docker volume rm pinboard-data      # fails while in use

docker ps -a --filter volume=pinboard-data
docker system df -v                 # what is eating the disk
docker volume prune                 # unused volumes only

Show docker volume ls on a machine that has been building all morning — the anonymous hash-named volumes make the point better than any slide. Say that docker volume rm refuses while a container still references the volume, which is a good safety net. Preview session 04: docker compose down keeps named volumes, down -v deletes them.

Operations

Backup with a throwaway container

# tar the volume out to the current host directory
docker run --rm \
  --mount type=volume,src=pinboard-data,dst=/data \
  --mount type=bind,src="$PWD",dst=/backup \
  alpine tar czf /backup/pinboard-data.tgz -C /data .

# restore into a fresh volume
docker volume create pinboard-data-restored
docker run --rm \
  --mount type=volume,src=pinboard-data-restored,dst=/data \
  --mount type=bind,src="$PWD",dst=/backup \
  alpine tar xzf /backup/pinboard-data.tgz -C /data

For a database, prefer the application-aware dump: docker exec db pg_dump -U pinboard pinboard > dump.sql.

The pattern to remember: a volume has no CLI of its own, so you mount it into a disposable container that does have tools. Stop Postgres before taring its data directory — a hot copy of PGDATA is not a backup. This same trick is how you inspect a volume you know nothing about: mount it into alpine and ls.

Run docker run -d --name db1 -e POSTGRES_PASSWORD=x postgres:17-alpine, docker exec -it db1 psql -U postgres -c "create table notes(t text)", then docker rm -f db1, recreate, and show the table is gone. Repeat with --mount type=volume,src=pinboard-data,dst=/var/lib/postgresql/data and the table survives. Then

docker run --rm -p 8081:8080 --mount type=bind,src="$PWD/src/pinboard-web/html",dst=/usr/share/nginx/html,ro pinboard-web:1.0

, edit index.html on the host, refresh the browser.

Networking, limits and health

How containers find each other, how you cap what they can consume, and how Docker knows they are alive.

Block B. Everything here is the last piece before Compose: once containers can resolve each other by name, the whole Pinboard stack can run on one machine. End the block on health checks because depends_on: condition: service_healthy in session 04 depends on them.

Drivers

Network drivers you actually use

bridge (default)

The docker0 network every container joins if you say nothing. Works — but no DNS between containers.

User-defined bridge

You create it. Embedded DNS resolves container names, and only attached containers can reach each other.

host

No network namespace at all: the container uses the host's stack directly. Fast, zero isolation, Linux only.

none

Loopback only. For batch jobs that must not talk to anything.

Note in passing that macvlan and overlay exist too — overlay is multi-host and belongs to Swarm, and in Kubernetes the CNI plugin does that job. The one sentence they must retain: always create a user-defined bridge. The default bridge has no service discovery and the legacy --link flag is deprecated. Mention that a user-defined network is also a security boundary — a container on pinboard-net cannot be reached from containers on other networks.

Service discovery

Containers find each other by name

docker network create pinboard-net

docker run -d --name db --network pinboard-net \
  --mount type=volume,src=pinboard-data,dst=/var/lib/postgresql/data \
  -e POSTGRES_USER=pinboard -e POSTGRES_PASSWORD=pinboard-secret \
  -e POSTGRES_DB=pinboard postgres:17-alpine

docker run -d --name api --network pinboard-net \
  -e DATABASE_URL=postgres://pinboard:pinboard-secret@db:5432/pinboard \
  -e APP_THEME=emerald pinboard-api:1.0

docker run -d --name web --network pinboard-net -p 8080:8080 \
  -e API_URL=http://api:8080 pinboard-web:1.0

db, api and web are DNS names on pinboard-net. No IP addresses anywhere.

This is Lab 03 in one slide — walk it top to bottom and point at the two places a name is used: @db:5432 in the connection string and http://api:8080 for nginx. Prove it live from a debug container: docker run --rm --network pinboard-net alpine nslookup api. Add --network-alias as the way to give one container several names, and say that Kubernetes Services are the same idea with load balancing bolted on.

The door to the outside

Publishing ports

-p HOST:CONTAINER — only the host side is negotiable
Containers on the same network talk on the container port with no -p at all
EXPOSE in a Dockerfile is documentation, not a firewall rule
Bind to 127.0.0.1 to keep a port off the LAN

-p 8080:8080            # all interfaces
-p 127.0.0.1:5432:5432  # localhost only
-p 8080:8080/udp        # protocol
-P                      # every EXPOSE → random port

docker port web
docker ps --format '{{.Names}}\t{{.Ports}}'

The classic mistake: publishing the database port to the world "so I can connect with pgAdmin". Show that api reaches db:5432 without any published port, so only web needs -p. Mention that published ports bypass most host firewall rules because Docker writes its own iptables chains — surprising and worth one sentence.

Guardrails

Resource limits and the OOM killer

By default a container may use all the host's CPU and RAM
--memory is a hard cap enforced by cgroups: exceed it and the kernel kills the process
An OOM-killed container exits with 137 and OOMKilled=true
--cpus is a quota, not a priority — the process is throttled, not killed

docker run -d --name api \
  --memory=128m --memory-swap=128m \
  --cpus=0.5 pinboard-api:1.0

docker stats --no-stream
docker inspect api \
  --format '{{.State.OOMKilled}} {{.State.ExitCode}}'

Make the demo point: run the API with --memory=16m and it dies on start. Explain why --memory-swap must be set equal to --memory, otherwise the container silently gets the same amount again as swap. Say plainly that this becomes resources.limits in Kubernetes, and that a missing limit there is the single most common cause of a node going down.

Keep it running

Restart policies

Policy	Behaviour	Use it for
`no`	Default. Never restarted.	One-shot jobs, experiments
`on-failure[:3]`	Restart on a non-zero exit, up to N times	Batch work that may flake
`always`	Always restart, including after a daemon restart	Long-running services
`unless-stopped`	Like `always`, but respects a manual `docker stop`	What Pinboard uses

A restart policy reacts to the process exiting. An unhealthy-but-alive container is never restarted by Docker — that is an orchestrator's job.

Add docker run --restart unless-stopped to the API in the demo and kill it with docker kill to show it come back with a growing backoff. The callout is the important half: this is where Docker alone stops being enough, and it is the first bullet of the Kubernetes motivation in session 05.

Is it actually working?

HEALTHCHECK

States: starting → healthy / unhealthy
docker ps shows it in the STATUS column
Define it in the Dockerfile, or override with --health-cmd at run time
Compose can wait on it — session 04

HEALTHCHECK --interval=10s --timeout=2s --retries=3 \
  CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1

docker ps
# STATUS  Up 40 seconds (healthy)

docker inspect web \
  --format '{{.State.Health.Status}}'

That HEALTHCHECK is copied verbatim from src/pinboard-web/Dockerfile. Explain the exit-code contract: 0 healthy, 1 unhealthy, and nothing else. Note that the distroless API image has no shell or wget, so it carries no HEALTHCHECK — that is why compose.yaml sets healthcheck: disable: true for the API and why Kubernetes probes, which the kubelet runs over HTTP from outside the container, are strictly better.

Type: docker run --rm --memory=16m --memory-swap=16m pinboard-api:1.0 — it is killed; show docker inspect reporting OOMKilled true. Then docker run -d --name api --restart unless-stopped --memory=128m ... pinboard-api:1.0, docker kill api, and docker ps a few seconds later to show it back up. Finish with docker stats --no-stream and a docker ps that shows web as (healthy).

Set expectations: this lab is deliberately tedious — nine long docker run flags per service, in the right order, by hand. That tedium is the entire argument for session 04. Tell them to keep the terminal history; next session they will translate exactly these commands into one compose.yaml. Common blockers: forgetting --network on one container, and typing localhost instead of db in DATABASE_URL.

Session 03

Key takeaways

Configure at run time

One image everywhere; -e / --env-file change behaviour. ARG is build time only.

Exec form or you lose signals

Your process must be PID 1 to receive SIGTERM and shut down gracefully.

State lives in volumes

The writable layer dies with the container. Named volumes for data, bind mounts for dev.

Next up

Session 04 — every flag from Lab 03, declared once in compose.yaml.

Close the loop: user-defined bridge for DNS, limits so one container cannot take the host down, health checks so something can tell that "running" is not the same as "working". Ask who had to retype a docker run line more than three times in the lab — that is the bridge to Compose.

Questions?

Up next — Session 04: Docker Compose. Same stack, one file.

Running containers well

What we'll cover today

1 · Configuration & process

2 · Storage

3 · Networking, limits, health

4 · Lab 03

Configuration & the container process

Configuration comes from the environment

ARG vs ENV

CMD vs ENTRYPOINT

Exec form vs shell form

Shell form

Exec form

PID 1, SIGTERM and graceful stop

docker stop

SIGTERM to PID 1

Grace period

SIGKILL

Signals: shell form vs exec form

Storage

The writable layer is ephemeral

Image layers

Writable layer

docker stop / start

docker rm

Volumes vs bind mounts vs tmpfs

Learn --mount, not -v

Volume lifecycle

Backup with a throwaway container

Postgres with and without a volume

Networking, limits and health

Network drivers you actually use

bridge (default)

User-defined bridge

host

none

Containers find each other by name

Publishing ports

Resource limits and the OOM killer

Restart policies

HEALTHCHECK

Limits, restarts and the health column

Wire Pinboard together by hand

Key takeaways

Configure at run time

Exec form or you lose signals

State lives in volumes

Next up

Questions?

Learn `--mount`, not `-v`