Skip to content
Hands-on IT IT Drills

Day 1: Your First compose.yaml

Goal: Describe the stack from Day 0 (still without a database) as one compose.yaml, start it with one command, observe it and tear it down again. · Duration: approx. 60 min · Prerequisite: Day 0

Briefing

  • A compose.yaml describes services. Compose turns them into containers, a network and, with build:, the images.
  • build: builds from a folder with a Dockerfile, image: uses a finished image.
  • Everything belongs to a project. Its name is part of every container, network and image name: notes-api-1, notes_default, notes-api.
  • Today notes-api runs in in-memory mode. Postgres arrives on Day 3.
 Mac 127.0.0.1                    project notes, network notes_default
 ┌────────────┐  :3000  ┌──────────────┐  http://api:8080  ┌──────────────┐
 │ curl       │────────►│ notes-web-1  │──────────────────►│ notes-api-1  │
 │            │  :8080  └──────────────┘                   │  (memory)    │
 │            │───────────────────────────────────────────►│              │
 └────────────┘                         ┌──────────────┐   └──────▲───────┘
                                        │notes-worker-1│──────────┘
                                        └──────────────┘

Drill 1: The first file, one service

Start the day as always, today with just the demo application as the starting point:

source ~/compose-lab/setup/env.sh
mkdir -p ~/compose-lab/tag01 && cd ~/compose-lab/tag01
cp -R "$LAB/code/notes/." .

First, notes-api only:

cat > compose.yaml <<'EOF'
# compose.yaml – first attempt: api only
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
EOF
docker compose up -d
docker compose ps
curl -s localhost:8080/healthz; echo

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

 Image notes-api Built
 Network notes_default Created
 Container notes-api-1 Started
NAME          IMAGE       COMMAND        SERVICE   CREATED        STATUS     …   PORTS
notes-api-1   notes-api   "/notes-api"   api       1 second ago   Up Less than a second
  (health: starting)   127.0.0.1:8080->8080/tcp
ok
  • build: notes-api is the short form for the build context; the Dockerfile in it is used. Day 8 shows the long form.
  • ${NOTES_API_KEY} comes from .env in the project folder; Compose reads it automatically.
  • "127.0.0.1:${API_PORT:-8080}:8080": host address, host port, container port. ${API_PORT:-8080} means “API_PORT, otherwise 8080”. The address 127.0.0.1 keeps the port off the network (Day 4 explains the variables in detail).

In the terminal, Compose shows the steps as a progress display with check marks; the result is the same.

Save your progress? Sign up for free

Drill 2: Three services in one file

Now the whole stack from Day 0, without a database:

cat > compose.yaml <<'EOF'
# compose.yaml – state at the end of Day 1
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"

  worker:
    build: notes-worker
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    depends_on:
      - api

  web:
    build: notes-web
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${WEB_PORT:-3000}:3000"
    depends_on:
      - api
EOF
docker compose up -d

Expected (shortened):

 Image notes-worker Built
 Image notes-web Built
 Container notes-api-1 Running
 Container notes-worker-1 Created
 Container notes-web-1 Created
 Container notes-worker-1 Started
 Container notes-web-1 Started

api was already running and matches the file, so Compose leaves it alone (Running). Only the new services are built and started. depends_on makes sure api starts before worker and web – started, not ready (Day 5).

docker compose ps --format 'table {{.Service}}\t{{.Name}}\t{{.Status}}\t{{.Ports}}'
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 1 mit Compose"}'; echo
curl -s localhost:8080/notes; echo

Expected (shortened):

SERVICE   NAME             STATUS                    PORTS
api       notes-api-1      Up 14 seconds (healthy)   127.0.0.1:8080->8080/tcp
web       notes-web-1      Up 7 seconds              127.0.0.1:3000->3000/tcp
worker    notes-worker-1   Up 7 seconds
{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}
[{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}]

Compared with Day 0: no docker network create, no --network-alias. worker and web reach http://api:8080 because Compose attaches every service to the network under its name (Day 2).

Save your progress? Sign up for free

Drill 3: Logs of all services

docker compose logs --tail 3

Expected (shortened):

api-1     | time=… level=INFO msg="api key loaded" source=env
api-1     | time=… level=INFO msg="store ready" store=memory
worker-1  | worker started, api=http://api:8080, interval=10s
worker-1  | summary: 0 notes, 0 words
worker-1  | summary: 1 notes, 4 words
api-1     | time=… level=INFO msg=listening addr=:8080 version=dev pid=1
web-1     | notes-web listening on :3000

--tail 3 applies per service, the lines are interleaved by time, and the prefix names the service and number. store=memory: without NOTES_DB_URL, notes-api stores data in memory. To follow one service live, end with Ctrl+C:

docker compose logs -f worker

Expected (shortened):

worker-1  | summary: 1 notes, 4 words
worker-1  | summary: 1 notes, 4 words
^C

Save your progress? Sign up for free

Drill 4: What Compose created

docker network ls --filter label=com.docker.compose.project=notes \
  --format '{{.Name}}  {{.Driver}}'
docker image ls --filter reference='notes-*' \
  --format '{{.Repository}}:{{.Tag}}  {{.Size}}'
docker ps --filter label=com.docker.compose.project=notes --format \
  '{{.Names}}  service={{.Label "com.docker.compose.service"}}'
docker compose ls

Expected (shortened):

notes_default  bridge
notes-web:latest  266MB
notes-worker:latest  214MB
notes-api:latest  15.4MB
notes-web-1  service=web
notes-worker-1  service=worker
notes-api-1  service=api
NAME     STATUS       CONFIG FILES
notes    running(3)   /Users/du/compose-lab/tag01/compose.yaml
Object Pattern Example
Container <project>-<service>-<number> notes-api-1
Network <project>_<network> notes_default
Image (build:, no image:) <project>-<service>:latest notes-api:latest

Compose finds “its” objects via labels like com.docker.compose.project – you can filter on them yourself, too (--filter label=com.docker.compose.project=notes). That’s why this book never uses container_name:: a fixed name prevents second instances and scaling.

Where does notes come from? According to the docs, in order of precedence: -p, then COMPOSE_PROJECT_NAME, then name: in the file, otherwise the name of the project folder. With --dry-run, Compose shows what it would do without creating anything:

docker compose --dry-run up -d 2>&1 | grep -m1 Network
docker compose -p demo --dry-run up -d 2>&1 | grep -m1 Network
COMPOSE_PROJECT_NAME=demo2 docker compose --dry-run up -d 2>&1 | grep -m1 Network
sed '/^name: /d' compose.yaml > ohne-name.yaml
docker compose -f ohne-name.yaml --dry-run up -d 2>&1 | grep -m1 Network
rm ohne-name.yaml

Expected:

 Network notes_default Creating
 Network demo_default Creating
 Network demo2_default Creating
 Network tag01_default Creating

Without name:, the project would be named after the folder tag01 – and every day would be a separate project. name: notes makes the name independent of the folder.

Save your progress? Sign up for free

Drill 5: config – the file as Compose sees it

docker compose config reads all files, substitutes variables, adds default values and prints the result – or an error, before anything starts:

docker compose config
API_PORT=8081 docker compose config | grep -A4 'ports:' | head -5
docker compose config -q; echo "Exit: $?"

What you see: the first command prints the complete file, with substituted values and added defaults such as the project name name: notes and the network default. The second shows the port entry in long form, with 8081 as the published port. The third only reports Exit: 0: -q prints nothing and checks solely via the exit code.

Security: config shows the substituted values, including the API key from .env. The output does not belong in tickets or CI logs (Day 4).

Save your progress? Sign up for free

Drill 6: exec and run --rm

exec runs a command in a running container of a service:

docker compose exec web wget -qO- http://api:8080/healthz; echo
docker compose exec web id
docker compose exec api sh; echo "Exit: $?"
docker compose exec api /notes-api healthcheck; echo "Exit: $?"

Expected:

ok
uid=1000(node) gid=1000(node) groups=1000(node)
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh":
executable file not found in $PATH
Exit: 127
Exit: 0

notes-api runs in scratch: no shell, only its own program. web, based on node:26-alpine, ships BusyBox, ideal for network tests. run --rm, on the other hand, starts a new one-off container with the service’s configuration:

docker compose run --rm api migrate; echo "Exit: $?"
docker compose run --rm --no-deps web \
  node -e 'console.log(process.version, process.env.NOTES_API_URL)'
docker compose ps -a --format '{{.Name}}  {{.Status}}'

Expected (shortened):

 Container notes-api-run-edc4062ed3d1 Created
time=… level=ERROR msg="migration failed" err="NOTES_DB_URL oder NOTES_DB_URL_FILE …"
Exit: 1
 Container notes-web-run-03da83ceab73 Created
v26.13.0 http://api:8080
notes-api-1  Up 40 seconds (healthy)
notes-web-1  Up 33 seconds
notes-worker-1  Up 33 seconds
  • The one-off container is named <project>-<service>-run-<id> and is gone after --rm.
  • It gets the service’s environment and network, but no ports: (that’s what --service-ports is for); otherwise it would collide with the running container.
  • --no-deps does not start dependencies. migrate fails cleanly today – on Day 3 exactly this command creates the table.

Save your progress? Sign up for free

Drill 7: Lifecycle – stop, start, restart, down

curl -s localhost:8080/notes; echo
docker compose stop
docker compose ps -a --format '{{.Name}}  {{.Status}}'
docker compose start
sleep 2; curl -s localhost:8080/notes; echo

Expected (shortened):

[{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}]
 Container notes-worker-1 Stopped
 Container notes-web-1 Stopped
 Container notes-api-1 Stopped
notes-api-1  Exited (0) Less than a second ago
notes-web-1  Exited (0) Less than a second ago
notes-worker-1  Exited (0) Less than a second ago
 Container notes-api-1 Started
 Container notes-worker-1 Started
 Container notes-web-1 Started
[]

stop stops in reverse dependency order (first worker and web, then api), start starts api first. The containers are kept – the note is not: it lived in the process’s memory. The same happens with restart:

docker compose restart api
docker compose logs api --no-log-prefix | tail -4

Expected (shortened):

 Container notes-api-1 Restarting
 Container notes-api-1 Started
time=… level=INFO msg="shutdown complete"
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=dev pid=1

down, on the other hand, removes containers and network; the images stay:

docker compose down
docker compose ps -a
docker image ls --filter reference='notes-*' --format '{{.Repository}}'

Expected (shortened):

 Container notes-web-1 Removed
 Container notes-worker-1 Removed
 Container notes-api-1 Removed
 Network notes_default Removed
NAME      IMAGE     COMMAND   SERVICE   CREATED   STATUS    PORTS
notes-web
notes-worker
notes-api
Command Containers Network Images
stop / start / restart kept kept kept
down removed removed kept
down --rmi local removed removed built ones removed

Save your progress? Sign up for free

Drill 8: Applying changes

up -d compares the file and variables with the running containers and replaces only what has changed:

docker compose up -d >/dev/null 2>&1
API_PORT=8081 docker compose up -d
docker compose ps --format '{{.Service}}  {{.Ports}}'
curl -s localhost:8081/healthz; echo
docker compose up -d

Expected:

 Container notes-worker-1 Running
 Container notes-web-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
 Container notes-api-1 Started
api  127.0.0.1:8081->8080/tcp
web  127.0.0.1:3000->3000/tcp
worker
ok
 Container notes-web-1 Running
 Container notes-worker-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
 Container notes-api-1 Started

Code changes, however, are invisible to up -d, because the image already exists:

sed -i '' 's|<h1>notes</h1>|<h1>notes – Tag 1</h1>|' notes-web/public/index.html
docker compose up -d
curl -s localhost:3000/ | grep '<h1>'
docker compose up -d --build
sleep 2; curl -s localhost:3000/ | grep '<h1>'

Expected (shortened):

 Container notes-worker-1 Running
 Container notes-web-1 Running
 Container notes-api-1 Running
  <h1>notes</h1>
 Image notes-api Built
 Image notes-web Built
 Image notes-worker Built
 Container notes-api-1 Running
 Container notes-web-1 Recreated
 Container notes-worker-1 Recreated
  <h1>notes – Tag 1</h1>

--build builds all images and replaces every container whose image then has a new ID. In the test run this also hit worker, even though nothing about it had changed: a new build can produce a new image ID despite the cache. (On Linux it’s sed -i without ''.) Revert the change and rebuild only web:

sed -i '' 's|<h1>notes – Tag 1</h1>|<h1>notes</h1>|' notes-web/public/index.html
docker compose up -d --build web

Expected (shortened):

 Image notes-api Built
 Image notes-web Built
 Container notes-api-1 Running
 Container notes-web-1 Recreated
 Container notes-web-1 Started

With a service name, Compose builds this service and its dependencies (api), but replaces only the web container.

Save your progress? Sign up for free

Checkpoint

The stack is running (docker compose up -d). The project name is in the file:

cd ~/compose-lab/tag01
grep '^name:' compose.yaml

Expected:

name: notes

Three services are running:

docker compose ps --format '{{.Service}} {{.State}}'

Expected:

api running
web running
worker running

The network notes_default and the three images:

docker network ls --filter name=notes_default --format '{{.Name}}'
docker image ls --filter reference='notes-*' --format '{{.Repository}}'

Expected (order may differ):

notes_default
notes-web
notes-worker
notes-api

api answers on 127.0.0.1:8080:

curl -s localhost:8080/healthz

Expected:

ok

Write a note via web, read it via api:

curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Kontrollpunkt Tag 1"}'
curl -s localhost:8080/notes | jq -r '.[].text'

Expected (shortened, ID differs):

{"id":"54a84d46-…","text":"Kontrollpunkt Tag 1"}
Kontrollpunkt Tag 1

worker summarizes:

docker compose logs worker | tail -1

Expected (shortened):

worker-1  | summary: 0 notes, 0 words

The complete file is in code/tag01/notes/compose.yaml.

Challenge

A colleague wants to test the stack in parallel with yours – from the same folder, with the same file, without changing it. Start a second instance notes2 on ports 8081 and 3001, show that both instances have separate data, and then remove notes2 including its images.

Hint: The project name and the ports both come from outside – -p and the variables from Drill 1.

Solution

cd ~/compose-lab/tag01
API_PORT=8081 WEB_PORT=3001 docker compose -p notes2 up -d
docker compose ls
curl -s -X POST localhost:3001/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"nur in notes2"}'; echo
curl -s localhost:8081/notes; echo
curl -s localhost:8080/notes; echo
docker compose -p notes2 down --rmi local

Expected (shortened):

 Container notes2-api-1 Started
 Container notes2-web-1 Started
 Container notes2-worker-1 Started
NAME     STATUS       CONFIG FILES
notes    running(3)   /Users/du/compose-lab/tag01/compose.yaml
notes2   running(3)   /Users/du/compose-lab/tag01/compose.yaml
{"id":"f59f49a4-…","text":"nur in notes2"}
[{"id":"f59f49a4-…","text":"nur in notes2"}]
[{"id":"4531570d-…","text":"Kontrollpunkt Tag 1"}]
 Network notes2_default Removed
 Image notes2-api:latest Removed
 Image notes2-web:latest Removed
 Image notes2-worker:latest Removed

-p beats name: notes, so containers, network and images are named notes2-… and don’t collide. The ports come from the variables; the file stays unchanged. notes2 builds its own images (from the build cache, hence quickly); --rmi local removes them again. Your project notes only knows the note from the checkpoint. The same as a script: code/tag01/challenge/zweite-instanz.sh.

At the end of the day:

docker compose down

Save your progress? Sign up for free

Enterprise Note

  • The compose.yaml belongs in the repository next to the code; .env does not (only .env.example). That way everyone on the team starts the same stack with their own values.
  • Unique project names (-p or COMPOSE_PROJECT_NAME) are mandatory in CI so that parallel pipelines on one runner don’t replace each other’s containers (Day 13).
  • Bind ports only to 127.0.0.1. A "8080:8080" without an address listens on all interfaces – on a server, directly on the network, often bypassing the host firewall.
  • docker compose config as a lint step in every pipeline: catches typos and missing variables before anything starts. But the output contains plaintext values.
  • In-memory mode like today’s is meant for demos only. Whatever has to survive a restart needs a volume (Day 3).