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,
scratchscheidet aus. Das Muster bleibt: Werkzeuge imbuild-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 nachdist/; das Laufzeit-Image bekommtdist/,server.jsund 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
EOFEin 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
EOFErwartet (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-workerErwartet (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/nullErwartet (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-workerErwartet (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-workerErwartet (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-webErwartet (gekürzt, kann je nach Version abweichen):
sha256:e27c…
Drei Entscheidungen stecken darin:
- Zwei
npm ci. Derbuild-Stage braucht esbuild (devDependency), das Laufzeit-Image nicht.npm ci --omit=devinstalliert exakt nachpackage-lock.json, nur ohne Dev-Pakete..npmrcsteht schon in der.dockerignore; an Tag 13 kommt sie als Build-Secret zurück. package.jsongehört ins Laufzeit-Image. notes-web ist ein ES-Modul ("type": "module"). Node 24 erkenntimportzwar auch ohne diese Angabe per Syntax-Erkennung, parst die Datei dann aber doppelt; mit einerpackage.jsonohnetypewarnt es zusätzlich mitMODULE_TYPELESS_PACKAGE_JSON. Eindeutig ist nur das Feldtype.USER node. Die offiziellen Node-Images bringen den Usernode(UID 1000) mit. Die Dateien gehören root und sind fürnodenur 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-workerErwartet (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-netErwartet (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/pythonwie im Build-Image; die.venvzeigt 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/DockerfileErwartet:
1
.venv bleibt außerhalb des Kontexts:
grep -x '.venv' notes-worker/.dockerignoreErwartet:
.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:tag06Erwartet:
65532:65532
node
Kein esbuild im Web-Image:
docker run --rm --entrypoint ls notes-web:tag06 node_modules | grep -c esbuildErwartet:
0
Das Netzwerk vom Tag ist wieder weg:
docker network ls -q --filter name=notes-net | wc -lErwartet:
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 --forceErwartet (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 --lockedundnpm cisind 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-fromteilt (Tag 4).