Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 8: Bauen mit Compose

Ziel: Images mit Compose gezielt bauen – lange build:-Syntax, Versionen per TAG, 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 mit context, dockerfile, target, args, secrets, tags, labels, cache_from, cache_to, platforms.
  • Mit image: neben build: 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 kann compose.yaml auch direkt lesen.
  • Die Stage test aus dem Dockerfile von notes-api wird zum Dienst api-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-build legt die Build-Definition einmal fest, *api-build setzt sie ein. Anker gelten nur innerhalb einer Datei.
  • target: final baut die letzte Stage ausdrücklich, args.VERSION landet per -ldflags im Programm und im Label org.opencontainers.image.version.
  • ${COMPOSE_PROJECT_NAME} stellt Compose selbst bereit (hier notes). 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/version

Erwartet:

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 watch baut notes-web:watch statt notes-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
EOF

In 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/npmrc
docker 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-token

Erwartet:

 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/npmrc

Erwartet (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 nur build.secrets (und ssh fü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:latest

Fortschritt 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
  • --check prüft die Dockerfiles mit den Build-Checks von BuildKit, ohne zu bauen.
  • --with-dependencies baut auch, wovon der Dienst per depends_on abhä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:test
docker 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.log

Erwartet (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 .buildcache

Erwartet (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.log

Erwartet (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.log

Erwartet:

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 --images

Erwartet:

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; echo

Erwartet:

dev

Kein npm-Token im Image:

docker image history --no-trunc notes-web:dev | grep -c lab-npm-token

Erwartet:

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 down

Erwartet:

dev

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In CI hat jeder Lauf einen leeren Builder. Ein Registry-Cache (cache_from/cache_to mit type=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; latest ist kein Deploy-Ziel. Produktion referenziert Images per Digest.
  • Multi-Plattform-Images (platforms:) baut man mit einem docker-container- oder Remote-Builder, besser noch nativ auf Runnern pro Architektur statt per Emulation.
  • docker compose build --sbom und --provenance hä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.