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.yamldescribes services. Compose turns them into containers, a network and, withbuild:, 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; echoExpected (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-apiis the short form for the build context; the Dockerfile in it is used. Day 8 shows the long form.${NOTES_API_KEY}comes from.envin 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 address127.0.0.1keeps 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 -dExpected (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; echoExpected (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 3Expected (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 workerExpected (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 lsExpected (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.yamlExpected:
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:
configshows 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-portsis for); otherwise it would collide with the running container. --no-depsdoes not start dependencies.migratefails 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; echoExpected (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 -4Expected (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 -dExpected:
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 webExpected (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.yamlExpected:
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/healthzExpected:
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 -1Expected (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 localExpected (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 downSave your progress? Sign up for free
Enterprise Note
- The
compose.yamlbelongs in the repository next to the code;.envdoes not (only.env.example). That way everyone on the team starts the same stack with their own values. - Unique project names (
-porCOMPOSE_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 configas 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
restartneeds a volume (Day 3).