Tag 8: Bauen mit Compose
Ziel: Images mit Compose gezielt bauen – lange
build:-Syntax, Versionen perTAG, Build-Secrets, Tags und Labels, Cache und Bake – und die Go-Tests als eigenen Dienst laufen lassen. · Dauer: ca. 75 min · Voraussetzung: Tag 7
Briefing
build:hat eine kurze Form (nur der Kontext) und eine lange mitcontext,dockerfile,target,args,secrets,tags,labels,cache_from,cache_to,platforms.- Mit
image:nebenbuild:bestimmst du den Namen des gebauten Images. Mit${TAG:-dev}darin hat jede Version ihr eigenes Image – Rollback ohne Neubau. - Compose 5.6 übergibt das Bauen an Bake
(
docker buildx bake). Bake kanncompose.yamlauch direkt lesen. - Die Stage
testaus dem Dockerfile von notes-api wird zum Dienstapi-test: Bauen heißt testen.
Drill 1: Was Compose heute baut
source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag08 && cd ~/compose-lab/tag08
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag07/notes/." .
docker compose build 2>&1 | grep -E 'Image|bake definitions'
docker image ls --filter reference='notes-*' \
--format '{{.Repository}}:{{.Tag}} {{.ID}} {{.Size}}'Erwartet (gekürzt, IDs und Größen weichen bei dir ab):
Image notes-api Building
Image notes-migrate Building
Image notes-worker Building
Image notes-web Building
#1 [internal] load local bake definitions
…
notes-web:latest ba2cc994ad80 266MB
notes-worker:latest 42a7bb19aa42 214MB
notes-api:latest 818f9c0d8946 15.4MB
notes-migrate:latest edf453ae4415 15.4MB
Zwei Befunde: load local bake definitions zeigt, dass
Compose den Build an Bake übergibt (Standard in Compose 5.6, live
geprüft). Und notes-api und notes-migrate sind
dasselbe Programm in zwei Images mit verschiedenen IDs – Platz und
Verwirrung für nichts. Alle heißen latest, eine Version ist
nicht erkennbar.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Lange build-Syntax, Anker und image
Ändere in compose.yaml den Kopf und die vier gebauten
Dienste (der Rest bleibt; die vollständige Datei liegt in
code/tag08/notes/):
# compose.yaml – Stand Ende Tag 8
name: notes
include:
- compose.tools.yaml
x-api-build: &api-build
context: notes-api
target: final
args:
VERSION: ${TAG:-dev}
services:
api:
build: *api-build
image: ${COMPOSE_PROJECT_NAME}-api:${TAG:-dev}
# … environment, ports usw. unverändert
migrate:
build: *api-build
image: ${COMPOSE_PROJECT_NAME}-api:${TAG:-dev}
# …
worker:
build: notes-worker
image: ${COMPOSE_PROJECT_NAME}-worker:${TAG:-dev}
# …
web:
build: notes-web
image: ${COMPOSE_PROJECT_NAME}-web:${TAG:-dev}
# …- Felder mit
x-am Anfang ignoriert Compose. Sie sind der Ablageplatz für YAML-Anker:&api-buildlegt die Build-Definition einmal fest,*api-buildsetzt sie ein. Anker gelten nur innerhalb einer Datei. target: finalbaut die letzte Stage ausdrücklich,args.VERSIONlandet per-ldflagsim Programm und im Labelorg.opencontainers.image.version.${COMPOSE_PROJECT_NAME}stellt Compose selbst bereit (hiernotes). So bleiben Images verschiedener Projekte getrennt.
docker compose config --format json \
| jq -c '[.services[] | select(.build) | {image, target: .build.target}]'
docker compose build 2>&1 | grep -E '^ *Image'
docker image rm notes-api notes-migrate notes-worker notes-web >/dev/null
docker image ls --filter reference='notes-*' \
--format '{{.Repository}}:{{.Tag}} {{.ID}}'Erwartet (gekürzt):
[{"image":"notes-api:dev","target":"final"},{"image":"notes-api:dev","target":"final"},
{"image":"notes-web:dev","target":null},{"image":"notes-worker:dev","target":null}]
Image notes-worker:dev Building
Image notes-web:dev Building
Image notes-api:dev Building
Image notes-api:dev Building
Image notes-api:dev Built
Image notes-web:dev Built
Image notes-worker:dev Built
Image notes-api:dev Built
notes-web:dev d8291ada1665
notes-worker:dev e99653334bc1
notes-api:dev f6d772fad16d
Compose baut notes-api:dev zweimal, einmal für jeden
Dienst; der zweite Durchlauf kommt vollständig aus dem Cache. Am Ende
gibt es ein Image, das api und migrate teilen. Die alten
latest-Images sind weg.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Versionen mit TAG
docker compose up -d --wait >/dev/null 2>&1
curl -s localhost:8080/version
TAG=1.0 docker compose up -d --build --wait 2>&1 | grep -E 'Image .* Built'
curl -s localhost:8080/version
docker image inspect notes-api:1.0 \
-f '{{index .Config.Labels "org.opencontainers.image.version"}}'
docker compose ps --format '{{.Service}}\t{{.Image}}'Erwartet (gekürzt):
dev
Image notes-api:1.0 Built
Image notes-web:1.0 Built
Image notes-worker:1.0 Built
1.0
1.0
api notes-api:1.0
db postgres:18.6-alpine
web notes-web:1.0
worker notes-worker:1.0
Und zurück, ohne zu bauen – das alte Image ist ja noch da:
docker compose up -d --wait 2>&1 | grep -cE 'Building'
curl -s localhost:8080/versionErwartet:
0
dev
Das ist das Muster für Update und Rollback auf dem Server (Tag 14):
Jede Version hat ein eigenes Image, umgeschaltet wird über
TAG. TAG muss bei up genauso
gesetzt sein wie bei build, sonst startet Compose die
Version, die gerade in der Variable steht – am sichersten als Zeile
TAG=1.0 in .env.
Tipp: Die Falle aus Tag 7 (Dev-Stage im selben Image wie Produktion) entschärfst du jetzt mit einem eigenen Tag für die Entwicklung:
TAG=watch docker compose -f compose.yaml -f compose.dev.yaml watchbautnotes-web:watchstattnotes-web:dev.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Build-Secret für npm
Das Dockerfile von notes-web bindet beim npm ci optional
ein .npmrc als Build-Secret ein
(--mount=type=secret,id=npmrc, aus „Dockerfiles zum
Anfassen”). Compose liefert es so:
mkdir -p secrets
cat > secrets/npmrc <<'EOF'
@notes-lab:registry=https://npm.lab.invalid/
//npm.lab.invalid/:_authToken=lab-npm-token-123
EOFIn compose.yaml bekommt web die lange Form, und am Ende
der Datei kommt ein Top-Level-Block secrets: dazu:
web:
build:
context: notes-web
secrets: [npmrc]
image: ${COMPOSE_PROJECT_NAME}-web:${TAG:-dev}
# …
secrets:
npmrc:
file: ./secrets/npmrcdocker compose build web 2>&1 | grep -E '^ *Image'
docker run --rm --user root --entrypoint sh notes-web:dev \
-c 'test -e /root/.npmrc || echo "keine /root/.npmrc"'
docker image history --no-trunc notes-web:dev | grep -c lab-npm-tokenErwartet:
Image notes-web:dev Building
Image notes-web:dev Built
keine /root/.npmrc
0
Das Token stand nur während der beiden RUN npm ci als
Datei bereit, weder in einer Schicht noch in der History. Die Secret-ID
im Dockerfile ist der Name unter secrets:.
secrets/ steht seit Tag 0 in .gitignore. Fehlt
die Datei, merkt das erst der Build:
mv secrets/npmrc secrets/npmrc.bak
docker compose config -q; echo "Exit: $?"
docker compose build web 2>&1 | tail -1
mv secrets/npmrc.bak secrets/npmrcErwartet (gekürzt):
Exit: 0
failed to stat /Users/du/compose-lab/tag08/secrets/npmrc: stat …: no such file or
directory
Sicherheit: Ein Token als
args:zu übergeben wäre der klassische Fehler: Build- Argumente stehen in der Image-History. Für alles Geheime beim Bauen gibt es nurbuild.secrets(undsshfür Git-Zugriffe).
Fortschritt speichern? Kostenlos registrieren
Drill 5: Zusätzliche Tags und Labels
Für ein Release soll api zusätzlich latest heißen und
ein Label mit dem Git-Stand tragen. Das gehört nicht in die Basisdatei,
also eine Zusatzdatei wie an Tag 7:
cat > compose.release.yaml <<'EOF'
# compose.release.yaml – nur für Tag 8, Drill 5
services:
api:
build:
tags:
- "${COMPOSE_PROJECT_NAME}-api:latest"
labels:
org.opencontainers.image.revision: ${REVISION:-unknown}
com.example.team: platform
EOF
REVISION=abc1234 docker compose -f compose.yaml -f compose.release.yaml build api \
2>&1 | grep -E '^ *Image'
docker image ls --filter reference='notes-api' \
--format '{{.Repository}}:{{.Tag}} {{.ID}}'
docker image inspect notes-api:latest --format '{{json .Config.Labels}}' \
| jq -c '{rev: .["org.opencontainers.image.revision"],
team: .["com.example.team"], version: .["org.opencontainers.image.version"]}'Erwartet (gekürzt):
Image notes-api:dev Building
Image notes-api:dev Built
notes-api:1.0 f00d7c9ee575
notes-api:dev 806b9630cfe3
notes-api:latest 806b9630cfe3
{"rev":"abc1234","team":"platform","version":"dev"}
build.tags hängt weitere Namen an dasselbe Image,
build.labels setzt Labels und gewinnt dabei gegen ein
LABEL im Dockerfile (revision war dort
unknown).
platforms: [linux/amd64, linux/arm64] würde mehrere
Architekturen bauen; das braucht einen Builder, der
Multi-Plattform-Images ablegen kann, und fürs Ausführen fremder
Architekturen eine Emulation – im Labor lassen wir es weg.
rm compose.release.yaml
docker image rm notes-api:latestFortschritt speichern? Kostenlos registrieren
Drill 6: Schalter für den Build
docker compose build --check 2>&1 | grep -E '^(api|migrate|web|worker)$|Check'
docker compose build worker 2>&1 | grep -E 'Image .* Building'
docker compose build --with-dependencies worker 2>&1 | grep -E 'Image .* Building'Erwartet (gekürzt):
api
Check complete, no warnings found.
migrate
Check complete, no warnings found.
web
Check complete, no warnings found.
worker
Check complete, no warnings found.
Image notes-worker:dev Building
Image notes-worker:dev Building
Image notes-api:dev Building
Image notes-api:dev Building
--checkprüft die Dockerfiles mit den Build-Checks von BuildKit, ohne zu bauen.--with-dependenciesbaut auch, wovon der Dienst perdepends_onabhängt: worker braucht api, api braucht migrate.
time docker compose build --pull -q api
time docker compose build --no-cache api 2>&1 | grep -E '^ *Image'Erwartet (gekürzt, Zeiten weichen bei dir ab):
Image notes-api:dev Building
Image notes-api:dev Built
… 0.742 total
Image notes-api:dev Building
Image notes-api:dev Built
… 19.23 total
--pull fragt die Registry nach neueren Basis-Images
(hier keine, daher schnell). --no-cache baut alle Schritte
neu; die Cache-Mounts für Go-Module bleiben dabei erhalten. Benutze es
gezielt für einen Dienst – über alle Images kostet es Minuten.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Tests als Dienst
Das Dockerfile von notes-api hat eine Stage test mit
go vet und go test. Ein eigener Dienst macht
sie aufrufbar. Ergänze in compose.yaml unter
services::
api-test:
profiles: [test]
build:
context: notes-api
target: test
image: ${COMPOSE_PROJECT_NAME}-api:testdocker compose config --services | tr '\n' ' '; echo
time docker compose --profile test build api-test 2>&1 \
| grep -E 'go test|ok |Image'
docker image ls --filter reference='notes-api' \
--format '{{.Repository}}:{{.Tag}} {{.Size}}'Erwartet (gekürzt, Zeiten weichen bei dir ab):
db migrate api worker web
Image notes-api:test Building
#13 [test 1/1] RUN … go vet ./... && go test ./...
#13 10.37 ok example.com/notes-api 0.003s
Image notes-api:test Built
… 12.00 total
notes-api:test 373MB
notes-api:dev 15.4MB
notes-api:1.0 15.4MB
Das Profil test hält den Dienst aus up und
aus docker compose build heraus. Laufen lassen musst du ihn
nie: Der Build ist der Testlauf. Ein absichtlich kaputter Test zeigt
das:
sed -i.bak 's/http.StatusUnauthorized, map/http.StatusForbidden, map/' notes-api/main.go
docker compose --profile test build api-test > test.log 2>&1; echo "Exit: $?"
grep -E -- '--- FAIL|main_test' test.log
docker compose build api 2>&1 | grep -E 'Image .* Built'
mv notes-api/main.go.bak notes-api/main.go && rm test.logErwartet (gekürzt):
Exit: 1
#13 0.507 --- FAIL: TestPostNotesRequiresKey (0.00s)
#13 0.507 main_test.go:75: key "": status 403, want 401
#13 0.507 main_test.go:75: key "falsch": status 403, want 401
Image notes-api:dev Built
Der Testlauf scheitert mit Exit 1, der normale Build läuft trotzdem
durch: Die Stage final hängt nicht von test
ab. Deshalb gehört build api-test vor jeden Release-Build
(Challenge, Tag 13). Zum Schluss baust du api wieder aus dem
korrigierten Code: docker compose build api.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Bake und Build-Cache
Was Compose an Bake übergibt, zeigt --print:
docker compose build --print 2>/dev/null | jq '.target.api'Erwartet (gekürzt):
{
"context": "/Users/du/compose-lab/tag08/notes-api",
"dockerfile": "/Users/du/compose-lab/tag08/notes-api/Dockerfile",
"args": {
"VERSION": "dev"
},
"labels": {
"com.docker.compose.project": "notes",
"com.docker.compose.service": "api",
"com.docker.compose.version": "5.6.0"
},
"tags": [
"notes-api:dev"
],
"target": "final",
"output": [
"type=docker"
]
}
Bake liest compose.yaml auch ohne Compose:
docker buildx bake -f compose.yaml --print 2>/dev/null \
| jq -c '{targets: .group.default.targets, tags: [.target[].tags[0]]}'Erwartet:
{"targets":["api","api-test","migrate","web","worker"],"tags":["notes-api:dev",
"notes-api:test","notes-api:dev","notes-web:dev","notes-worker:dev"]}
Zwei Unterschiede zu Compose, beide live geprüft: Bake ignoriert
Profile (api-test ist dabei), und den Projektnamen für
${COMPOSE_PROJECT_NAME} nimmt es aus name: –
eine Umgebungsvariable COMPOSE_PROJECT_NAME änderte daran
nichts.
Jetzt der Cache. cache_to exportiert den Build-Cache,
cache_from liest ihn wieder ein – in CI der Unterschied
zwischen Minuten und Sekunden. Der Standard-Builder (Treiber
docker) kann den Typ local nur mit dem
containerd-Image-Store, den Colima benutzt (Tag 0).
cat > compose.cache.yaml <<'EOF'
# compose.cache.yaml – nur für Tag 8, Drill 8
services:
api:
build:
cache_from: ["type=local,src=.buildcache/api"]
cache_to: ["type=local,dest=.buildcache/api,mode=max"]
EOF
docker compose -f compose.yaml -f compose.cache.yaml build api 2>&1 \
| grep -E 'exporting cache|sending cache export'
du -sh .buildcacheErwartet (gekürzt, Größen weichen bei dir ab):
#16 exporting cache to client directory
#16 sending cache export
#16 sending cache export 1.1s done
77M .buildcache
Ein frischer Builder hat keinen eigenen Cache, ideal zum Prüfen. Der
Treiber docker-container startet BuildKit in einem eigenen
Container (Image moby/buildkit, rund 360 MB):
docker buildx create --name notes-builder --driver docker-container
docker compose -f compose.yaml -f compose.cache.yaml build --builder notes-builder api \
> build.log 2>&1
grep -E 'importing cache' build.log; grep -c CACHED build.logErwartet (gekürzt):
notes-builder
#8 importing cache manifest from local:17197388493963414838
6
Alle sechs Build-Schritte kommen aus .buildcache, obwohl
der Builder neu ist; das Image landet trotzdem in
docker image ls. Mit mode=max exportiert
BuildKit auch die Zwischen-Stages, nicht nur die letzte. Aufräumen:
docker buildx rm notes-builder
rm -rf .buildcache compose.cache.yaml build.logErwartet:
notes-builder removed
docker buildx rm entfernt Builder und Cache, das Image
moby/buildkit bleibt. Den gemeinsamen Cache des
Standard-Builders räumst du nie mit docker builder prune
auf – der gehört auch anderen Projekten.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
api und migrate teilen sich notes-api:dev (die Liste hat
eine Zeile pro Dienst):
cd ~/compose-lab/tag08
docker compose config --imagesErwartet:
notes-web:dev
postgres:18.6-alpine
notes-api:dev
notes-worker:dev
notes-api:dev
Die Images sind gebaut:
docker image ls --filter reference='notes-*:dev'Erwartet (gekürzt, IDs und Größen weichen ab):
IMAGE ID DISK USAGE CONTENT SIZE EXTRA
notes-api:dev 36cb0dbf3581 16.4MB 4.5MB U
notes-web:dev 01834e24f2ec 260MB 64.2MB U
notes-worker:dev 32cf2748123c 188MB 45.5MB U
/version liefert dev:
curl -s localhost:8080/version; echoErwartet:
dev
Kein npm-Token im Image:
docker image history --no-trunc notes-web:dev | grep -c lab-npm-tokenErwartet:
0
Die Tests sind grün:
docker compose --profile test build -q api-test; echo "Exit: $?"Erwartet:
Exit: 0
Challenge
Bau das Release 1.1 ohne
docker compose build: erst die Tests, dann die drei Images,
beides mit docker buildx bake direkt aus
compose.yaml. Starte den Stack anschließend ohne Build und
prüf /version. Pack alles in ein Skript
release.sh, das bei rotem Test abbricht.
Hinweis: docker buildx bake nimmt
Target-Namen wie Compose Dienstnamen, und up --no-build
verweigert das Bauen.
Lösung
cat > release.sh <<'EOF'
#!/usr/bin/env bash
# release.sh – Challenge Tag 8: Release mit Bake testen und bauen, ohne Build starten
# Aufruf: TAG=1.1 ./release.sh [projektordner]
set -euo pipefail
cd "${1:-$HOME/compose-lab/tag08}"
export TAG="${TAG:-1.1}"
docker buildx bake -f compose.yaml api-test # Testlauf, bricht bei Rot ab
docker buildx bake -f compose.yaml api worker web # Release-Images notes-*:$TAG
docker compose up -d --no-build --wait
echo "Version: $(curl -s "localhost:${API_PORT:-8080}/version")"
EOF
chmod +x release.sh
TAG=1.1 ./release.sh 2>&1 | grep -E 'naming to|Healthy|Version'
docker compose ps --format '{{.Service}}\t{{.Image}}'Erwartet (gekürzt):
#14 naming to docker.io/library/notes-api:test done
#22 naming to docker.io/library/notes-web:1.1 done
#43 naming to docker.io/library/notes-worker:1.1 done
#45 naming to docker.io/library/notes-api:1.1 done
Container notes-api-1 Healthy
Container notes-db-1 Healthy
Container notes-web-1 Healthy
Version: 1.1
api notes-api:1.1
db postgres:18.6-alpine
web notes-web:1.1
worker notes-worker:1.1
set -e beendet das Skript, sobald der Test-Bake
scheitert; ohne grüne Tests entsteht kein Release-Image. Weil Bake den
Projektnamen aus name: notes nimmt, heißen die Images genau
so, wie Compose sie bei up erwartet. Das Skript liegt im
Begleitcode unter code/tag08/challenge/release.sh. Zum
Schluss zurück auf dev und die Release-Images entfernen
(das Test-Image ist mit 373 MB das größte):
docker compose up -d --wait >/dev/null 2>&1 && curl -s localhost:8080/version
docker image rm notes-api:1.0 notes-worker:1.0 notes-web:1.0 \
notes-api:1.1 notes-worker:1.1 notes-web:1.1 notes-api:test >/dev/null
docker compose downErwartet:
dev
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- In CI hat jeder Lauf einen leeren Builder. Ein Registry-Cache
(
cache_from/cache_tomittype=registry,ref=…,mode=max) oder der Cache der CI-Plattform (type=gha) bringt die Laufzeit zurück auf Sekunden. - Release-Tags kommen aus der Pipeline (Git-Tag oder Commit-SHA), nie
von Hand;
latestist kein Deploy-Ziel. Produktion referenziert Images per Digest. - Multi-Plattform-Images (
platforms:) baut man mit einemdocker-container- oder Remote-Builder, besser noch nativ auf Runnern pro Architektur statt per Emulation. docker compose build --sbomund--provenancehängen SBOM und Herkunftsnachweis an; zusammen mit einer Signatur (cosign, Notation) sind sie in regulierten Umgebungen oft Pflicht.- Tokens für private Registries (npm, PyPI, Go-Proxy) nur als
Build-Secret, in CI aus dem Secret-Store der Pipeline, nie als
args:oder im Build-Kontext.