Skip to content
Hands-on IT IT Drills

Day 0: The Training Ground

Goal: Check Docker and Compose, set up the companion code and base images, build the demo application notes and wire it up completely by hand once – so you know what Compose takes off your plate from tomorrow on. · Duration: approx. 60 min · Prerequisite: none

Briefing

  • Docker runs in a small Linux VM managed by Colima. docker and docker compose on the Mac talk to the daemon in the VM over a socket.
  • Compose is a plugin of the Docker CLI. It reads a YAML file and does what you type by hand today: networks, volumes, containers, order.
  • The demo application notes has three services with finished Dockerfiles from “Dockerfiles hands-on”. New: notes-api can store data in Postgres.
  • There is no compose.yaml yet today. You write it on Day 1.
 Mac                                   Colima VM (Linux, arm64)
 ┌───────────────────────────┐         ┌──────────────────────────────────────┐
 │ ~/compose-lab/            │         │ network notes-net                    │
 │   setup/ env.sh           │  socket │   notes-web ─► notes-api ─► notes-db │
 │   notes/ api worker web   │────────►│    :3000       :8080 ▲        │      │
 │   code/  companion code   │  :8080  │                      │        │      │
 │   tagNN/ your work        │  :3000  │           notes-worker        │      │
 │ docker, docker compose    │◄───────►│   volume notes-pgdata ◄───────┘      │
 └───────────────────────────┘         └──────────────────────────────────────┘

Drill 1: Check your tools

docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
docker compose version
docker buildx version
colima version | head -1
jq --version
curl --version | head -1

Expected (shortened, may differ depending on version):

Client 29.9.0 / Server 29.5.2
Docker Compose version 5.6.0
github.com/docker/buildx v0.38.0 Homebrew
colima version 0.10.3
jq-1.8.2
curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) …

If something is missing: brew install colima docker docker-compose docker-buildx jq. Since version 2, Compose is no longer a separate program docker-compose, but the subcommand docker compose (with a space). On Linux, Docker Engine with the plugins for Compose and buildx is enough; Docker Desktop works as well.

Warning: If docker version reports failed to connect to the docker API for the server, the VM is not running. Use colima status and docker context ls to check whether the context colima is active (docker context use colima).

Save your progress? Sign up for free

Drill 2: Colima, shares and disk space

colima status
docker info --format 'Arch {{.Architecture}} · CPUs {{.NCPU}} · Storage {{.Driver}}'
df -h ~ | tail -1
docker system df

Expected (shortened, values differ on your machine):

INFO[0000] colima is running using macOS Virtualization.Framework
INFO[0000] arch: aarch64
INFO[0000] runtime: docker
INFO[0000] mountType: virtiofs
Arch aarch64 · CPUs 4 · Storage overlayfs
/dev/disk3s5   228Gi   150Gi    11Gi    94%    1.9M  111M    2%   /System/Volumes/Data
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          3         1         5.667GB   506MB (8%)
Containers      1         1         24.58kB   0B (0%)
Local Volumes   18        1         2.926GB   2.853GB (97%)
Build Cache     156       0         5.184GB   5.184GB

Remember three things:

  • Shares: By default, Colima only shares your home directory with the VM. A bind mount from /tmp or /Volumes/… shows up in the container as an empty folder, without an error message. That’s why the lab lives under ~/compose-lab.
  • Storage overlayfs means: the containerd image store. Images you build show up immediately in docker image ls and are usable by Compose.
  • Free space: Images, build cache and volumes live on Colima’s VM disk. Keep at least 5 GB free and clean up selectively after each day (Drill 9).

Warning: docker system prune and docker volume prune also delete the data of other projects, for example their database volumes. In this book you only remove lab traces, selectively via the label lab=compose-lab (Drill 9).

Save your progress? Sign up for free

Drill 3: Working directory and companion code

You fetch the companion code from GitHub once into ~/compose-lab/code. The setup file and the demo application get their own copies so you can change them without losing the original:

mkdir -p ~/compose-lab/tag00 && cd ~/compose-lab
git clone https://github.com/thomaszachmann/docker-compose-zum-anfassen.git \
  ~/compose-lab/code
cp -R ~/compose-lab/code/setup ~/compose-lab/setup
cp -R ~/compose-lab/code/notes ~/compose-lab/notes
ls ~/compose-lab ~/compose-lab/setup

Expected:

Cloning into '/Users/du/compose-lab/code'...
/Users/du/compose-lab:
code    notes   setup   tag00

/Users/du/compose-lab/setup:
env.sh

env.sh only sets variables that all drills use:

grep -v '^#' ~/compose-lab/setup/env.sh

Expected:

export LAB="${LAB:-$HOME/compose-lab}"
export NOTES="$LAB/notes"
export LAB_LABEL="${LAB_LABEL:-compose-lab}"   # Label lab=… für docker run im Buch
export PROJECT="${COMPOSE_PROJECT_NAME:-notes}" # Compose-Projekt (name: notes)
export LAB_IMAGES="postgres:18.6-alpine golang:1.27-alpine python:3.15-slim \
node:26-alpine ghcr.io/astral-sh/uv:0.13.6"

LAB_IMAGES are the book’s base images: Postgres as a ready-made service, the others as the foundation of the three Dockerfiles. From now on every day starts with the same line:

source ~/compose-lab/setup/env.sh

Save your progress? Sign up for free

Drill 4: Pull the base images

You pull the base images once up front; then the days build quickly and without rate-limit surprises. docker pull skips what is already there:

for img in $LAB_IMAGES; do docker pull -q "$img"; done
docker image ls --format '{{.Repository}}:{{.Tag}}  {{.Size}}' \
  | grep -E '^(postgres|golang|python|node|ghcr.io/astral-sh/uv):'
df -h ~ | tail -1

Expected (shortened, sizes differ):

docker.io/library/postgres:18.6-alpine
docker.io/library/golang:1.27-alpine
docker.io/library/python:3.15-slim
docker.io/library/node:26-alpine
ghcr.io/astral-sh/uv:0.13.6
node:26-alpine  252MB
python:3.15-slim  184MB
ghcr.io/astral-sh/uv:0.13.6  64.3MB
golang:1.27-alpine  382MB
postgres:18.6-alpine  433MB
/dev/disk3s1s1   228Gi    17Gi    11Gi    62%    426k  112M    0%   /

The fourth column of df shows at least 5 GB.

Tip: Tested with golang:1.27-alpine (Go 1.27.3), python:3.15-slim (3.15.2), node:26-alpine (26.13.0) and postgres:18.6-alpine. golang:1.25 from the first book has not received updates since August 2026; that’s why the Dockerfiles use Go 1.27.

Save your progress? Sign up for free

Drill 5: Get to know the demo application

cd ~/compose-lab/notes
ls -A . notes-api notes-worker notes-web

Expected:

.:
.dockerignore   .env.example    .hadolint.yaml  notes-web       README.md
.env            .gitignore      notes-api       notes-worker

notes-api:
.dockerignore   go.mod          main_test.go    metrics.go
Dockerfile      go.sum          main.go         store.go

notes-worker:
.dockerignore   Dockerfile      pyproject.toml  src             uv.lock

notes-web:
.dockerignore           package-lock.json       public                  src
Dockerfile              package.json            server.js
Service Language Port Role in the book
notes-api Go 1.27 8080 Lead role: Postgres, healthcheck, metrics
notes-worker Python 3.15, uv – regularly reads all notes through the API
notes-web Node 26, Express 5 3000 frontend, forwards /api/notes to notes-api
db Postgres 18.6 5432 ready-made image, no Dockerfile of its own

The Dockerfiles are the final state from “Dockerfiles hands-on”: multi-stage, notes-api in scratch as user 65532 with a built-in HEALTHCHECK. The database is new. Where notes-api gets its settings from is defined in the code:

grep -n 'readSecret("NOTES' notes-api/main.go

Expected:

55: key, source, err = readSecret("NOTES_API_KEY")
64: return readSecret("NOTES_DB_URL")

readSecret first reads the file from <NAME>_FILE, otherwise the variable <NAME>. For the API key this is mandatory. The database is optional:

  • without NOTES_DB_URL, notes-api stores data in memory – as in the first book,
  • with NOTES_DB_URL, in Postgres. At startup it checks the connection exactly once; if that fails, it exits with exit code 1.
  • Only the subcommand notes-api migrate creates the table. It is idempotent; you can run it as often as you like.

The values for the lab are in .env, the template without values in .env.example:

cat .env.example

Expected:

# Vorlage: nach .env kopieren und Werte eintragen. Diese Datei darf ins Repository.
NOTES_API_KEY=
POSTGRES_PASSWORD=

Security: .env contains lab-api-key-123 and lab-db-pw-123, pure lab values. .gitignore and .dockerignore already exclude .env, as you learned in the first book. On Day 4 you’ll see that Compose reads this file anyway, and on Day 10 the secrets disappear from it.

Save your progress? Sign up for free

Drill 6: Build three images

cd ~/compose-lab/notes
for s in api worker web; do
  docker build -q -t "notes-${s}:tag00" "notes-${s}"
done
docker image ls --filter reference='notes-*' \
  --format '{{.Repository}}:{{.Tag}}  {{.Size}}'

Expected (shortened, sizes and IDs differ on your machine):

sha256:df008224d81e…
sha256:eaa0ee28903b…
sha256:4f43fbfce3d6…
notes-web:tag00  266MB
notes-worker:tag00  214MB
notes-api:tag00  15.4MB

The first run takes a few minutes because Go modules, Python and Node packages are downloaded. -q only shows the image ID. A quick test without a database:

docker run --rm notes-api:tag00 migrate; echo "Exit: $?"

Expected (shortened, times differ):

… level=ERROR msg="migration failed" err="NOTES_DB_URL oder NOTES_DB_URL_FILE fehlt"
Exit: 1

A clean error with a non-zero exit code (“NOTES_DB_URL or NOTES_DB_URL_FILE missing”). Compose will rely on exactly that on Day 5.

Save your progress? Sign up for free

Drill 7: Wired by hand – network, Postgres, migration

This is how you start the stack without Compose. Count how many options you type.

docker network create --label lab=compose-lab notes-net
docker volume create --label lab=compose-lab notes-pgdata
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-pgdata:/var/lib/postgresql postgres:18.6-alpine
until docker exec notes-db pg_isready -U notes -d notes; do sleep 1; done

Expected (shortened, IDs differ):

0fdc0fb607f8…
notes-pgdata
88f2aa90c557…
/var/run/postgresql:5432 - no response
/var/run/postgresql:5432 - accepting connections
  • --network-alias db gives the container the DNS name db in the network notes-net. Compose later does this automatically with the service name.
  • The volume is mounted at /var/lib/postgresql. Since Postgres 18 the data lives below it in 18/docker; older guides mount …/data and lose their data on an upgrade or on docker rm (Day 3).

Now create the table. migrate runs as a one-off container and removes itself with --rm:

DB_URL='postgres://notes:lab-db-pw-123@db:5432/notes'
docker run --rm --label lab=compose-lab --network notes-net \
  -e NOTES_DB_URL="$DB_URL" notes-api:tag00 migrate

Expected (shortened, times differ):

time=… level=INFO msg="migration complete" table=notes

Save your progress? Sign up for free

Drill 8: Add api, worker and web

docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00
docker run -d --name notes-worker --label lab=compose-lab --network notes-net \
  -e NOTES_API_URL=http://api:8080 -e NOTES_API_KEY=lab-api-key-123 notes-worker:tag00
docker run -d --name notes-web --label lab=compose-lab \
  --network notes-net -p 127.0.0.1:3000:3000 \
  -e NOTES_API_URL=http://api:8080 -e NOTES_API_KEY=lab-api-key-123 notes-web:tag00
sleep 3
docker ps --filter label=lab=compose-lab --format '{{.Names}}\t{{.Status}}'

Expected (shortened, IDs and times differ):

2ff53a5c0586…
12c2c75ca425…
03449f811de0…
notes-web   Up 3 seconds
notes-worker    Up 3 seconds
notes-api   Up 3 seconds (healthy)
notes-db    Up 4 seconds

(healthy) comes from the HEALTHCHECK in the notes-api image; right after the start it briefly shows (health: starting), hence the sleep 3. Now write a note through the frontend – notes-web adds the key itself – and read it directly from the API:

curl -s localhost:8080/healthz
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 0 von Hand verdrahtet"}'; echo
curl -s localhost:8080/notes; echo
sleep 10
docker logs notes-api
docker logs notes-worker

Expected (shortened, IDs and times differ):

ok
{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}
[{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}]
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=postgres
time=… level=INFO msg=listening addr=:8080 version=dev pid=1
worker started, api=http://api:8080, interval=10s
summary: 0 notes, 0 words
summary: 1 notes, 5 words

store=postgres: notes-api writes to the database. The DB URL with the password does not show up in the log, only the source of the key.

Save your progress? Sign up for free

Drill 9: Data survives the container

Containers are disposable, the volume is not. Delete the database and the API and start both again – with the same volume:

docker rm -f notes-api notes-db
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-pgdata:/var/lib/postgresql postgres:18.6-alpine >/dev/null
until docker exec notes-db pg_isready -U notes -d notes >/dev/null; do sleep 1; done
docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00 >/dev/null
sleep 2
curl -s localhost:8080/notes; echo
docker exec notes-db psql -U notes -d notes -c 'SELECT text, created_at FROM notes'

Expected (shortened, IDs and times differ):

notes-api
notes-db
[{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}]
           text            |          created_at
---------------------------+-------------------------------
 Tag 0 von Hand verdrahtet | 2026-10-29 20:23:47.997567+00
(1 row)

The note (“Day 0 wired by hand”) is still there. worker and web didn’t notice the restart: they address api by its DNS name, not by an IP.

Tally: one network, one volume, five docker run, about 25 options, one wait loop, and the order existed only in your head. From Day 1 on, all of that lives in a file. Finally, clean up what you created today: four containers, one network, three images and the volume, each by name:

docker rm -f notes-api notes-worker notes-web notes-db
docker network rm notes-net
docker image rm notes-api:tag00 notes-worker:tag00 notes-web:tag00
docker volume rm notes-pgdata

Expected (shortened, IDs differ):

notes-api
notes-worker
notes-web
notes-db
notes-net
Untagged: notes-api:tag00
Deleted: sha256:462674996c48…
Untagged: notes-worker:tag00
Deleted: sha256:e6c41f02f0d5…
Untagged: notes-web:tag00
Deleted: sha256:90672b2e7e65…
notes-pgdata

From Day 1 on, docker compose down cleans all of this up with one command. The base images stay; you’ll need them again tomorrow.

Save your progress? Sign up for free

Checkpoint

source ~/compose-lab/setup/env.sh && echo "$PROJECT $NOTES"

Expected:

notes /Users/du/compose-lab/notes
ls ~/compose-lab/notes/compose.yaml

Expected (you only write the file on Day 1):

ls: /Users/du/compose-lab/notes/compose.yaml: No such file or directory
docker ps -a --filter label=lab=compose-lab --format '{{.Names}}' | wc -l

Expected:

0
docker volume ls --filter label=lab=compose-lab --format '{{.Name}}' | wc -l

Expected:

0

Challenge

So far you have always waited until Postgres was ready. On a fresh volume notes-race, start the database and immediately afterwards notes-api, without a wait loop. What happens to notes-api, and how do you read the cause and the exit code without restarting the container?

Hint: docker wait blocks until a container ends and prints its exit code; docker inspect knows .State.ExitCode.

Solution

cd ~/compose-lab/notes
docker build -q -t notes-api:tag00 notes-api >/dev/null
docker network create --label lab=compose-lab notes-net >/dev/null
docker volume create --label lab=compose-lab notes-race >/dev/null
DB_URL='postgres://notes:lab-db-pw-123@db:5432/notes'
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-race:/var/lib/postgresql postgres:18.6-alpine >/dev/null
docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00 >/dev/null
docker wait notes-api
docker logs notes-api 2>&1 | tail -1
docker inspect -f '{{.State.Status}} exit={{.State.ExitCode}}' notes-api

Expected (shortened, addresses and times differ):

1
time=… level=ERROR msg="database unreachable" source=env err="failed to connect to
`user=notes database=notes`:\n\t172.20.0.2:5432 (db): dial error: dial tcp
172.20.0.2:5432: connect: connection refused…"
exited exit=1

The name db resolved – the container exists, after all – but Postgres was still initializing and did not accept TCP connections. notes-api deliberately tries only once and exits with exit code 1. Who waits, who restarts and how “ready” is detected is handled by Compose on Day 5 with depends_on and healthchecks. Finally, clean up:

docker rm -f notes-api notes-db
docker network rm notes-net
docker image rm notes-api:tag00
docker volume rm notes-race

Expected (shortened, IDs differ):

notes-api
notes-db
notes-net
Untagged: notes-api:tag00
Deleted: sha256:0eec1d688dc4…
notes-race

Save your progress? Sign up for free

Enterprise Note

  • Compose is a tool for a single Docker host: development, CI, small servers. For multiple hosts, self-healing across nodes and rollouts there is Kubernetes; the concepts (service, volume, secret, healthcheck) carry over.
  • In companies, base images come from a mirror or pull-through cache (Harbor, Artifactory, Nexus), not directly from Docker Hub – rate limits and provenance control.
  • In larger companies Docker Desktop requires a paid license; Colima, Rancher Desktop or a Linux VM are common alternatives. Compose runs on all of them.
  • Postgres in a container is fine for development, tests and small systems. For important data, backup, restore tests and upgrades matter more than the place where the process runs (Day 3).
  • You’ll find hand-wired docker run scripts like today’s in many legacy projects. They are the most common reason to switch to Compose: the file can be versioned, verified and is the same for everyone on the team.