Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: Multi-Stage für Python und Node

Ziel: notes-worker mit uv und notes-web mit npm zweistufig bauen, sodass im Laufzeit-Image nur Interpreter, Prod-Abhängigkeiten und App liegen. · Dauer: ca. 75 min · Voraussetzung: Tag 5

Briefing

  • Python und Node brauchen zur Laufzeit ihren Interpreter, scratch scheidet aus. Das Muster bleibt: Werkzeuge im build-Stage, nur das Ergebnis ins Laufzeit-Image.
  • Python: uv baut eine .venv; kopiert wird nur sie. uv selbst, sein Cache und der Quellcode bleiben zurück.
  • Node: esbuild bündelt im build-Stage nach dist/; das Laufzeit-Image bekommt dist/, server.js und nur die Prod-node_modules.
  • Build- und Laufzeit-Stage müssen zusammenpassen: gleiches Base-Image, gleicher Interpreter-Pfad.
 notes-worker                               notes-web
 build: python:3.13-slim + uv               build: node:24-alpine
   uv sync --no-install-project  (Deps)       npm ci            (alle Deps)
   uv sync --no-editable         (Projekt)    npm run build     → dist/app.js
        │ COPY --from=build /app/.venv              │ COPY --from=build /app/dist
        ▼                                           ▼
 python:3.13-slim  .venv, USER 65532        node:24-alpine  npm ci --omit=dev,
                                            server.js, public/, dist/, USER node

Drill 1: Der naive Python-Build

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

Die zweite Kopie legt den Stand vom Ende von Tag 5 darüber – auch wenn du ihn übersprungen hast. Zum Vergleich baust du den Worker erst so, wie man es oft sieht: ein Stage, alles hinein. Das Dockerfile kommt per Heredoc über stdin:

docker build -q -t notes-worker:naiv -f- notes-worker <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/
WORKDIR /app
COPY . .
RUN uv sync --locked
CMD ["uv", "run", "notes-worker"]
EOF
docker run --rm notes-worker:naiv \
  sh -c 'du -sh /bin/uv /root/.cache/uv /app/.venv; ls /app'

Erwartet (gekürzt, kann je nach Version abweichen):

sha256:5e81…
43.6M   /bin/uv
11.2M   /root/.cache/uv
4.6M    /app/.venv
pyproject.toml
src
uv.lock

COPY --from=ghcr.io/astral-sh/uv:0.13.6 holt das uv-Binary direkt aus dem offiziellen uv-Image, ohne pip install uv; das Muster vertieft Tag 7. Im Laufzeit-Image liegen damit uv, sein Download-Cache und der Quellcode – nichts davon braucht der Worker. Größen in diesem Kapitel stammen aus einer Beispielumgebung und weichen bei dir ab.

Fortschritt speichern? Kostenlos registrieren

Drill 2: .dockerignore für den Worker

Eine lokale .venv ist an dein Betriebssystem gebunden und darf nie in den Kontext. Die uv-Doku nennt das ausdrücklich als Best Practice.

cat > notes-worker/.dockerignore <<'EOF'
# notes-worker/.dockerignore (Tag 6)
Dockerfile*
.dockerignore
.git
.env*
.venv
**/__pycache__
**/*.pyc
EOF

Ein lokales uv sync legt als Köder eine .venv an (ohne uv auf dem Mac lässt du die erste Zeile weg). Ein Wegwerf-Build listet dann, was wirklich im Kontext ankommt:

(cd notes-worker && uv sync -q)
docker build --no-cache --progress=plain -f- notes-worker <<'EOF' 2>&1 \
  | grep -E '^#[0-9]+ [0-9.]+ /ctx'
# syntax=docker/dockerfile:1
FROM python:3.13-slim
COPY . /ctx
RUN find /ctx -maxdepth 1
EOF

Erwartet (gekürzt, kann je nach Version abweichen):

#7 0.162 /ctx
#7 0.162 /ctx/pyproject.toml
#7 0.162 /ctx/src
#7 0.162 /ctx/uv.lock

Keine .venv, keine .dockerignore (die Reihenfolge kann abweichen). Der Build erzeugt kein Image mit Namen, nur Cache.

Fortschritt speichern? Kostenlos registrieren

Drill 3: uv in zwei Stages

Das Muster folgt der offiziellen uv-Docker-Doku (docs.astral.sh/uv/guides/integration/docker/):

cat > notes-worker/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
# notes-worker, Stand Tag 6: uv im build-Stage, nur die .venv im Laufzeit-Image
ARG PYTHON_VERSION=3.13

# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM python:${PYTHON_VERSION}-slim AS build
COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/
ENV UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy \
    UV_NO_DEV=1 \
    UV_PYTHON_DOWNLOADS=0
WORKDIR /app
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-editable
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable --reinstall-package notes-worker

FROM python:${PYTHON_VERSION}-slim
LABEL org.opencontainers.image.title="notes-worker" \
      org.opencontainers.image.description="Fasst die Notizen aus notes-api zusammen" \
      org.opencontainers.image.source="https://example.com/docker-lab/notes"
COPY --from=build /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"
WORKDIR /app
USER 65532:65532
STOPSIGNAL SIGTERM
ENTRYPOINT ["notes-worker"]
EOF
Einstellung Wirkung
UV_COMPILE_BYTECODE=1 .pyc schon beim Build; als User 65532 kann Python sie später nicht schreiben
UV_LINK_MODE=copy Cache-Mount und .venv liegen auf verschiedenen Dateisystemen: kopieren statt verlinken
UV_NO_DEV=1 keine Dev-Abhängigkeiten
UV_PYTHON_DOWNLOADS=0 den Python des Base-Images nutzen, keinen eigenen laden
--locked Abbruch, wenn uv.lock nicht zu pyproject.toml passt
--no-install-project erst nur die Abhängigkeiten – eigener, stabiler Layer
--no-editable Projekt als Paket in die .venv, nicht als Verweis auf src/
--reinstall-package notes-worker das eigene Projekt immer neu bauen (Drill 4)

UV_PYTHON_DOWNLOADS=0 ist der Schlüssel für den zweiten Stage: Die .venv verweist auf /usr/local/bin/python3 aus python:3.13-slim, und genau dieser Pfad existiert im Laufzeit-Image wieder, weil beide Stages dasselbe ARG PYTHON_VERSION nutzen. Im ersten uv sync sind uv.lock und pyproject.toml nur per Bind-Mount da; der Layer hängt damit nicht vom Quellcode ab.

docker build -t notes-worker:tag06 notes-worker

Erwartet (gekürzt, kann je nach Version abweichen):

[+] Building 14.2s (15/15) FINISHED                              docker:colima
 => [internal] load metadata for ghcr.io/astral-sh/uv:0.13.6               1.1s
 => [internal] load metadata for docker.io/library/python:3.13-slim        0.9s
 => [build 1/6] FROM docker.io/library/python:3.13-slim@sha256:…           4.8s
 => FROM ghcr.io/astral-sh/uv:0.13.6@sha256:…                              2.3s
 => [build 2/6] COPY --from=ghcr.io/astral-sh/uv:0.13.6 /uv /uvx /bin/     0.2s
 => [build 3/6] WORKDIR /app                                               0.0s
 => [build 4/6] RUN --mount=type=cache,target=/root/.cache/uv     --mount…  2.9s
 => [build 5/6] COPY . .                                                   0.0s
 => [build 6/6] RUN --mount=type=cache,target=/root/.cache/uv     uv sync…  2.4s
 => [stage-1 2/3] COPY --from=build /app/.venv /app/.venv                  0.1s
 => [stage-1 3/3] WORKDIR /app                                             0.0s
 => exporting to image                                                     0.4s

Im letzten uv sync baut uv ein Wheel von notes-worker. Dafür lädt es das Build-Backend aus [build-system] (hatchling) in eine isolierte Umgebung; das steht nicht in uv.lock. Hatchling findet das Paket im src/-Layout selbst: Der Projektname notes-worker passt zu src/notes_worker/.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Was im Image steckt – und was nicht

docker run --rm --entrypoint sh notes-worker:tag06 -c '
  command -v uv || echo "kein uv"
  ls -A /app
  id -u
  ls /app/.venv/lib/python3.13/site-packages | grep notes
  find /app/.venv -name "*.pyc" | wc -l'
docker image ls notes-worker --format '{{.Tag}}\t{{.Size}}'

Erwartet (gekürzt, kann je nach Version abweichen):

kein uv
.venv
65532
notes_worker
notes_worker-0.1.0.dist-info
128
tag06   127MB
naiv    186MB

Kein uv, kein src/, keine uv.lock; das Paket liegt als echtes Paket in site-packages. Mit Editable-Install stünde dort nur eine .pth-Datei, die auf /app/src zeigt – und die gibt es im Laufzeit-Image nicht. Der größte Brocken sind die rund 120 MB von python:3.13-slim selbst; Tag 8 vergleicht kleinere Base-Images.

Jetzt der Cache. Ändere den Code und baue einmal ohne --reinstall-package (per sed über stdin) und einmal mit der echten Datei:

echo '# Tag 6' >> notes-worker/src/notes_worker/__init__.py
sed 's/ --reinstall-package notes-worker//' notes-worker/Dockerfile \
  | docker build -q -f- -t notes-worker:stale notes-worker
docker build --progress=plain -t notes-worker:tag06 notes-worker 2>&1 \
  | grep -E '^#[0-9]+ (\[build [456]/6\]|CACHED)|Built|Installed'
init=/app/.venv/lib/python3.13/site-packages/notes_worker/__init__.py
for t in stale tag06; do
  docker run --rm --entrypoint tail notes-worker:$t -n 1 "$init"
done
docker rmi -f notes-worker:stale >/dev/null

Erwartet (gekürzt, kann je nach Version abweichen):

sha256:2a7f…
#6 CACHED
#7 CACHED
#8 [build 4/6] RUN --mount=type=cache,target=/root/.cache/uv     --mount=type=bind,s…
#8 CACHED
#10 [build 5/6] COPY . .
#11 [build 6/6] RUN --mount=type=cache,target=/root/.cache/uv     uv sync --locked …
#11 0.981       Built notes-worker @ file:///app
#11 1.204 Installed 1 package in 2ms
    print("worker stopped", flush=True)
# Tag 6

Der Abhängigkeits-Layer kommt in beiden Fällen aus dem Cache, nur notes-worker wird neu installiert. Aber notes-worker:stale enthält den alten Code: uv baut lokale Projekte laut Doku nur neu, wenn sich pyproject.toml, setup.py oder setup.cfg ändern oder ein src-Ordner hinzukommt bzw. wegfällt. Im Cache-Mount lag noch das Wheel aus Drill 3. --reinstall-package notes-worker erzwingt den Neubau; die Alternative ist [tool.uv] cache-keys in der pyproject.toml.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Worker gegen notes-api

Der Worker spricht http://notes-api:8080 an. Ein eigenes Netzwerk liefert die Namensauflösung über den Containernamen.

docker build -q -t notes-api:tag06 notes-api
docker network create notes-net
docker run -d --name notes-api --network notes-net -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 notes-api:tag06
docker run -d --name notes-worker --network notes-net -e INTERVAL=3 \
  -e NOTES_API_KEY=lab-api-key-123 notes-worker:tag06
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -d '{"text":"uv in zwei Stages"}'
sleep 4; docker logs notes-worker

Erwartet (gekürzt, IDs weichen ab):

sha256:8c1e…
7f3a2c…
4d9b0e…
1b6f8a…
{"id":"c0d2…","text":"uv in zwei Stages"}
worker started, api=http://notes-api:8080, interval=3s
summary: 1 notes, 4 words

Die drei Hex-Zeilen sind die IDs von Netzwerk und Containern. Stoppen geht sofort, weil notes-worker per Exec-Form als PID 1 läuft und SIGTERM selbst behandelt:

time docker stop notes-worker
docker logs --tail 2 notes-worker

Erwartet (gekürzt, Zeiten weichen ab):

notes-worker
docker stop notes-worker  0.01s user 0.01s system 4% cpu 0.341 total
signal 15 received, stopping
worker stopped

Container und Netzwerk bleiben für Drill 7 stehen.

Fortschritt speichern? Kostenlos registrieren

Drill 6: notes-web mit npm in zwei Stages

cat > notes-web/.dockerignore <<'EOF'
# notes-web/.dockerignore (Tag 6)
Dockerfile*
.dockerignore
.git
.env*
.npmrc
node_modules
dist
EOF
cat > notes-web/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
# notes-web, Stand Tag 6: bündeln im build-Stage, zur Laufzeit nur Prod-Abhängigkeiten
ARG NODE_VERSION=24

# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM node:${NODE_VERSION}-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

FROM node:${NODE_VERSION}-alpine
LABEL org.opencontainers.image.title="notes-web" \
      org.opencontainers.image.description="Oberfläche und Proxy für notes-api" \
      org.opencontainers.image.source="https://example.com/docker-lab/notes"
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev
COPY server.js ./
COPY public ./public
COPY --from=build /app/dist ./dist
EXPOSE 3000
USER node
STOPSIGNAL SIGTERM
ENTRYPOINT ["node", "server.js"]
EOF
docker build -q -t notes-web:tag06 notes-web

Erwartet (gekürzt, kann je nach Version abweichen):

sha256:e27c…

Drei Entscheidungen stecken darin:

  • Zwei npm ci. Der build-Stage braucht esbuild (devDependency), das Laufzeit-Image nicht. npm ci --omit=dev installiert exakt nach package-lock.json, nur ohne Dev-Pakete. .npmrc steht schon in der .dockerignore; an Tag 13 kommt sie als Build-Secret zurück.
  • package.json gehört ins Laufzeit-Image. notes-web ist ein ES-Modul ("type": "module"). Node 24 erkennt import zwar auch ohne diese Angabe per Syntax-Erkennung, parst die Datei dann aber doppelt; mit einer package.json ohne type warnt es zusätzlich mit MODULE_TYPELESS_PACKAGE_JSON. Eindeutig ist nur das Feld type.
  • USER node. Die offiziellen Node-Images bringen den User node (UID 1000) mit. Die Dateien gehören root und sind für node nur lesbar – genau richtig.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Die ganze Kette

docker start notes-worker
docker run -d --name notes-web --network notes-net -p 127.0.0.1:3000:3000 \
  -e NOTES_API_KEY=lab-api-key-123 notes-web:tag06
sleep 2
curl -s localhost:3000/healthz; echo
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"über notes-web"}'; echo
curl -s localhost:3000/api/notes; echo
sleep 3; docker logs --tail 1 notes-worker

Erwartet (gekürzt, IDs weichen ab):

notes-worker
5a07e1…
ok
{"id":"e91f…","text":"über notes-web"}
[{"id":"c0d2…","text":"uv in zwei Stages"},{"id":"e91f…","text":"über notes-web"}]
summary: 2 notes, 6 words

Der Browser schickt keinen Key, notes-web hängt ihn serverseitig an. Öffne http://localhost:3000 und leg eine Notiz über die Oberfläche an. Was steckt im Image?

docker run --rm --entrypoint sh notes-web:tag06 -c '
  ls node_modules | wc -l
  ls -d node_modules/esbuild src 2>&1
  ls dist
  id -un'

Erwartet (gekürzt, kann je nach Version abweichen):

65
ls: node_modules/esbuild: No such file or directory
ls: src: No such file or directory
app.js
node

Kein esbuild, kein src/, nur das Bundle. Im build-Stage waren es 67 Einträge unter node_modules; der Unterschied sind esbuild und sein Plattform-Binary unter @esbuild/.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Vergleich und sauberes Herunterfahren

docker image ls --format '{{.Repository}}:{{.Tag}}\t{{.Size}}' \
  | grep -E '^notes-(api|worker|web):' | sort
docker stop notes-web notes-worker notes-api
docker logs --tail 1 notes-web
docker logs --tail 1 notes-api
docker rm notes-web notes-worker notes-api
docker network rm notes-net

Erwartet (gekürzt, kann je nach Version abweichen):

notes-api:tag06       6.31MB
notes-web:tag06       168MB
notes-worker:naiv     186MB
notes-worker:tag06    127MB
notes-web
notes-worker
notes-api
SIGTERM received, shutting down
time=… level=INFO msg="shutdown complete"
notes-web
notes-worker
notes-api
notes-net

Das Aufräumen am Tagesende entfernt Container und Images, aber keine Netzwerke – deshalb das docker network rm am Ende. Alle drei Dienste fahren auf SIGTERM sauber herunter.

Tipp: Es gibt auch distroless-Images für Python und Node (gcr.io/distroless/python3-debian13, gcr.io/distroless/nodejs24-debian13). Bei Python liegt der Interpreter dort unter /usr/bin/python, nicht unter /usr/local/bin/python wie im Build-Image; die .venv zeigt dann ins Leere, wenn du die Pfade nicht angleichst. Für Node probierst du es in der Challenge.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Die Abhängigkeiten des Workers haben einen eigenen Layer:

cd ~/docker-lab/tag06
grep -c -- '--no-install-project' notes-worker/Dockerfile

Erwartet:

1

.venv bleibt außerhalb des Kontexts:

grep -x '.venv' notes-worker/.dockerignore

Erwartet:

.venv

Kein uv im Worker-Image (127 heißt „Befehl nicht gefunden“):

docker run --rm --entrypoint sh notes-worker:tag06 -c 'command -v uv; echo "Exit: $?"'

Erwartet:

Exit: 127

Beide Images laufen nicht als root:

docker image inspect --format '{{.Config.User}}' notes-worker:tag06 notes-web:tag06

Erwartet:

65532:65532
node

Kein esbuild im Web-Image:

docker run --rm --entrypoint ls notes-web:tag06 node_modules | grep -c esbuild

Erwartet:

0

Das Netzwerk vom Tag ist wieder weg:

docker network ls -q --filter name=notes-net | wc -l

Erwartet:

0

Challenge

Bau notes-web zusätzlich als notes-web:tag06-distroless auf gcr.io/distroless/nodejs24-debian13:nonroot, mit derselben Funktion wie notes-web:tag06. Vergleiche die Größe und zeig, dass weder Shell noch npm im Image sind.

Hinweis: distroless hat kein npm, also brauchst du eine dritte Stage für die Prod-Abhängigkeiten; der Entrypoint des Images ist schon node.

Lösung

Die Datei liegt auch unter ~/docker-lab/code/tag06/Dockerfile.web-distroless.

# syntax=docker/dockerfile:1
# Lösung Challenge Tag 6: notes-web auf distroless/nodejs (ohne Shell, ohne npm)
ARG NODE_VERSION=24

# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM node:${NODE_VERSION}-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

FROM node:${NODE_VERSION}-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev

# Entrypoint des Images ist bereits "node"; CMD nennt nur das Skript
FROM gcr.io/distroless/nodejs24-debian13:nonroot
ENV NODE_ENV=production
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY package.json server.js ./
COPY public ./public
COPY --from=build /app/dist ./dist
EXPOSE 3000
USER 65532:65532
CMD ["server.js"]

build und deps hängen nicht voneinander ab; BuildKit baut sie parallel (Tag 7). node_modules aus einem Alpine-Stage funktioniert hier nur, weil Express reines JavaScript ist. Pakete mit nativen Addons müssen in einem glibc-Stage wie node:24-slim gebaut werden, passend zur Debian-Basis von distroless.

cd ~/docker-lab/tag06
docker build -q -f ~/docker-lab/code/tag06/Dockerfile.web-distroless \
  -t notes-web:tag06-distroless notes-web
docker run -d --name notes-web -p 127.0.0.1:3000:3000 notes-web:tag06-distroless
sleep 2; curl -s localhost:3000/healthz; echo
docker run --rm --entrypoint sh notes-web:tag06-distroless -c true 2>/dev/null
echo "Exit: $?"
docker run --rm --entrypoint npm notes-web:tag06-distroless --version 2>/dev/null
echo "Exit: $?"
docker image ls notes-web --format '{{.Tag}}\t{{.Size}}'

Erwartet (gekürzt, kann je nach Version abweichen):

sha256:91d4…
3c5e…
ok
Exit: 127
Exit: 127
tag06-distroless   171MB
tag06              168MB

Kleiner wird es kaum: distroless/nodejs steht auf Debian mit glibc, node:24-alpine auf musl. Der Gewinn ist die Angriffsfläche – keine Shell, kein npm, kein Paketmanager. Ohne NOTES_API_URL-Ziel scheitert hier nur der Proxy; /healthz antwortet trotzdem. Zum Schluss aufräumen:

docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
  | grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --force

Erwartet (gekürzt, Namen, IDs und Größen weichen ab):

notes-web
Untagged: notes-web:tag06
Deleted: sha256:…
…
Total:  …

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In Firmen kommen Pakete aus einem internen PyPI- oder npm-Proxy (Artifactory, Nexus). Dessen Zugangsdaten gehören nie ins Dockerfile, sondern in Build-Secrets (Tag 13).
  • uv sync --locked und npm ci sind in CI Pflicht: Ein Build, der den Lockfile still aktualisiert, ist nicht reproduzierbar und unterläuft das Dependency-Review.
  • Das Build-Backend (hatchling) und das uv-Image stehen in keinem Lockfile. Pinne beide (requires = ["hatchling==…"], uv-Image per Digest, Tag 8) oder spiegle sie intern.
  • Native Abhängigkeiten (z. B. cryptography, sharp) brauchen passende Wheels oder Compiler: musl- und glibc-Stages nie mischen, Build- und Laufzeit-Base gleich wählen.
  • Cache-Mounts für uv und npm wirken in CI nur, wenn der Builder seinen Cache behält oder ihn per --cache-to/--cache-from teilt (Tag 4).