Deployment-Artefakte aus Docker Builds erzeugen

1. Docker als Build-Umgebung: das Grundprinzip

Das Kernversprechen von Docker als Build-Umgebung lautet: Wenn der Build in einem Container läuft, ist das Ergebnis auf jedem Rechner identisch – unabhängig davon, welche Version von PHP, Node, Go oder Rust auf dem CI-Server oder dem Entwicklungsrechner installiert ist. Deployment-Artefakte aus Docker Builds zu erzeugen bedeutet, das Dockerfile nicht nur als Rezept für ein Runtime-Image zu verstehen, sondern als vollständige, versionierte Build-Umgebung, die Input nimmt (Quellcode) und Output produziert (kompilierte Binaries, Archive, statische Assets).

Dieser Ansatz löst das klassische Problem des "bei mir funktioniert's": Wer Deployment-Artefakte aus Docker Builds erzeugt, bekommt dieselbe Toolchain-Version in Entwicklung, CI und Produktion. Die Build-Umgebung ist im Dockerfile deklariert, versioniert und reproduzierbar. Ein Go-Binary, das in einem golang:1.22-Container kompiliert wird, ist bit-identisch, egal ob der Build auf dem Laptop des Entwicklers, im GitHub-Actions-Runner oder auf einem Kubernetes-Node-Knoten läuft.

2. Multi-Stage Dockerfiles für saubere Artefakt-Trennung

Multi-Stage Builds sind der sauberste Weg, um Deployment-Artefakte aus Docker Builds zu erzeugen und gleichzeitig das finale Image klein zu halten. Jedes FROM-Statement startet eine neue Build-Stage. Mit COPY --from=build-stage /app/dist ./dist werden nur die fertigen Artefakte in die nächste Stage kopiert – der gesamte Build-Kontext mit Compiler, Test-Dependencies und temporären Dateien bleibt im Zwischen-Layer und gelangt nicht ins finale Image. Das ist nicht nur für die Image-Größe relevant, sondern auch für die Sicherheit: Entwicklungsdependencies mit bekannten CVEs sind nicht im Produktions-Image enthalten.

Eine wichtige Technik beim Erzeugen von Deployment-Artefakten aus Docker Builds ist das gezielte Targeting einzelner Stages mit docker build --target artefact-stage. So kann ein Build mehrere Artefakt-Stages haben – eine für das kompilierte Binary, eine für statische Assets, eine für die Test-Ergebnisse – und die CI-Pipeline ruft gezielt die gewünschte Stage auf. Mit BuildKit laufen unabhängige Stages parallel, was die Build-Zeit in Multi-Stage-Szenarien deutlich reduziert.

# syntax=docker/dockerfile:1.7
# Multi-stage Dockerfile: build PHP app + compile Node assets + export artifacts

# --- Stage 1: PHP dependency build ---
FROM composer:2.7 AS php-deps
WORKDIR /app
COPY composer.json composer.lock ./
# Cache mount: Composer cache survives across builds
RUN --mount=type=cache,target=/root/.composer \
    composer install --no-dev --optimize-autoloader --no-interaction

# --- Stage 2: Node asset build ---
FROM node:22-alpine AS node-assets
WORKDIR /build
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --prefer-offline
COPY web/tailwind/ ./web/tailwind/
RUN npm run build

# --- Stage 3: Artifact collector (lightweight) ---
FROM scratch AS artifacts
COPY --from=php-deps /app/vendor ./vendor/
COPY --from=node-assets /build/web/css ./web/css/
COPY --from=node-assets /build/web/js  ./web/js/

# --- Stage 4: Final runtime image ---
FROM php:8.4-fpm-alpine AS runtime
COPY --from=php-deps /app/vendor /app/vendor
COPY --from=node-assets /build/web /app/web
COPY src/ /app/src/

3. Artefakte mit docker cp aus dem Container extrahieren

Die klassische Methode, Deployment-Artefakte aus Docker Builds zu extrahieren, ist eine Kombination aus docker build, docker create und docker cp. Nach dem Build wird mit docker create ein Container aus dem Image erstellt, ohne ihn zu starten – das setzt den Container-Layer bereit und ermöglicht Dateizugriff. Dann kopiert docker cp die gewünschten Artefakte auf das Host-Dateisystem. Schließlich löscht docker rm den temporären Container. Diese Methode funktioniert mit jedem Docker-Client ohne BuildKit und ist daher in älteren CI-Umgebungen noch weit verbreitet.

Der Nachteil dieser Methode: Sie benötigt drei separate Befehle und hinterlässt bei Fehler einen hängenden Container, wenn das Cleanup-Skript nicht sauber abgesichert ist. Das Muster trap "docker rm -f $CONTAINER_ID" EXIT in einem Shell-Skript stellt sicher, dass der temporäre Container auch bei Fehlern aufgeräumt wird. Für Deployment-Artefakte aus Docker Builds in modernen Umgebungen mit BuildKit ist die --output-Methode eleganter.

#!/usr/bin/env bash
# extract-artifacts.sh — build and extract deployment artifacts from Docker
set -euo pipefail

IMAGE_TAG="my-app-build:$(git rev-parse --short HEAD)"
ARTIFACT_DIR="./dist"

# Build the image targeting the artifact stage
docker build \
  --target artifacts \
  --tag "$IMAGE_TAG" \
  --build-arg BUILD_ENV=production \
  .

# Create a temporary container (not started) to access the filesystem
CONTAINER_ID=$(docker create "$IMAGE_TAG")
trap "docker rm -f '$CONTAINER_ID' >/dev/null 2>&1" EXIT

mkdir -p "$ARTIFACT_DIR"

# Copy artifacts from container to host
docker cp "${CONTAINER_ID}:/vendor"  "${ARTIFACT_DIR}/vendor"
docker cp "${CONTAINER_ID}:/web/css" "${ARTIFACT_DIR}/web/css"
docker cp "${CONTAINER_ID}:/web/js"  "${ARTIFACT_DIR}/web/js"

echo "Artifacts extracted to ${ARTIFACT_DIR}"
ls -lh "${ARTIFACT_DIR}"

# Remove intermediate image to free disk space
docker rmi "$IMAGE_TAG"

4. BuildKit --output: direkt ins Host-Dateisystem schreiben

BuildKit bietet mit dem --output-Flag eine direktere Alternative zum docker cp-Workflow. Mit docker buildx build --output type=local,dest=./dist . werden Dateien aus dem Build-Kontext direkt ins angegebene Host-Verzeichnis exportiert – ohne Zwischenschritt über einen Container. Das ist besonders elegant für Deployment-Artefakte aus Docker Builds, die direkt in einem Artifact-Store wie GitHub Artifacts, S3 oder Nexus landen sollen. Kombiniert mit einer FROM scratch AS artifacts-Stage enthält das exportierte Verzeichnis exakt die Dateien, die die Stage enthält.

Der Output-Typ tar exportiert statt eines Verzeichnisses ein TAR-Archiv: --output type=tar,dest=./app.tar. Das ist ideal für Deployment-Artefakte aus Docker Builds, die als versionierte Archive gespeichert oder übertragen werden sollen. Mit dem Typ image und push=true wird das Image direkt in eine Registry gepusht, ohne es lokal zu laden – spart Disk-I/O und ist ideal für CI-Umgebungen mit wenig lokalem Speicher.

5. BuildKit Cache-Mounts für schnelle Builds

BuildKit Cache-Mounts (RUN --mount=type=cache,target=/root/.composer) sind das wichtigste Performance-Feature für Deployment-Artefakte aus Docker Builds in CI/CD-Pipelines. Sie persistieren den Download-Cache von Paketmanagern – Composer, NPM, pip, Go-Module-Cache, apt-Pakete – zwischen Builds, ohne ihn in den Image-Layer zu schreiben. Das bedeutet: bei einem zweiten Build mit denselben Dependencies werden keine Pakete erneut heruntergeladen, obwohl der Layer-Cache aufgrund von Source-Code-Änderungen ungültig ist.

Der Unterschied zu normalen Layer-Caches: Ein Layer-Cache wird ungültig, sobald sich irgendein Input ändert. Ein Cache-Mount bleibt unabhängig davon erhalten. Wenn sich nur eine einzelne PHP-Klasse ändert, ist der Composer-Layer-Cache ungültig, aber der Cache-Mount enthält noch alle heruntergeladenen Pakete und composer install läuft in Sekunden statt Minuten. Für Deployment-Artefakte aus Docker Builds in GitHub Actions oder GitLab CI können Cache-Mounts mit docker buildx build --cache-from type=gha --cache-to type=gha über den GitHub Actions Cache persistiert werden.

6. PHP-Composer und Node-Assets als Artefakte erzeugen

Für PHP-Projekte auf Basis von Magento oder Symfony sind zwei Arten von Deployment-Artefakten aus Docker Builds besonders relevant: der optimierte Composer-Vendor-Ordner und die kompilierten Frontend-Assets. Den Vendor-Ordner mit composer install --no-dev --optimize-autoloader in einem Composer-Container zu erzeugen und als Artefakt zu extrahieren, bedeutet, dass der Deployment-Prozess auf dem Zielserver keinen Composer-Aufruf mehr braucht. Das eliminiert eine Abhängigkeit auf dem Produktionsserver und macht das Deployment deterministischer.

Node-Assets – Tailwind CSS, JavaScript-Bundles – werden typischerweise in einer Node-Stage mit dem entsprechenden Builder kompiliert. Das Ergebnis ist ein dist/- oder pub/static/-Verzeichnis, das als Deployment-Artefakt aus Docker Builds auf den Produktionsserver kopiert oder in eine CDN hochgeladen wird. Indem man den Build in Docker kapselt, kann man sicherstellen, dass exakt dieselbe Node-Version und dieselben Paketversionen für jeden Build verwendet werden – ein häufiger Fehlerquell bei manuellen Asset-Builds entfällt.

# BuildKit --output: write artifacts directly to host filesystem (no docker cp needed)
docker buildx build \
  --target artifacts \
  --output type=local,dest=./dist \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --build-arg GIT_SHA="$(git rev-parse --short HEAD)" \
  .

# Export as TAR archive for versioned storage
docker buildx build \
  --target artifacts \
  --output "type=tar,dest=./releases/app-$(git rev-parse --short HEAD).tar" \
  .

# Build and push image directly to registry without local storage
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --output type=image,push=true \
  --tag registry.example.com/my-app:$(git rev-parse --short HEAD) \
  .

# Use GitHub Actions cache backend for persistent cache across CI runs
docker buildx build \
  --cache-from type=gha \
  --cache-to type=gha,mode=max \
  --output type=local,dest=./dist \
  .

7. SBOM und Provenance aus Docker Builds exportieren

Software Bill of Materials (SBOM) und Build-Provenance sind zunehmend relevante Deployment-Artefakte aus Docker Builds, die Compliance- und Sicherheitsanforderungen adressieren. Docker BuildKit 0.11+ kann automatisch eine SBOM als Image-Attestation erzeugen: docker buildx build --sbom=true --provenance=true. Die SBOM listet alle Pakete und Dependencies im Image auf und wird als signierbares OCI-Attestierungs-Manifest zusammen mit dem Image in die Registry gepusht. Mit docker buildx imagetools inspect image:tag lässt sich die Attestation anzeigen.

Für Deployment-Artefakte aus Docker Builds in regulierten Umgebungen ist die Kombination aus SBOM und Provenance besonders wertvoll: Die Provenance dokumentiert, welcher Quellcode-Commit, welcher CI-Job und welche BuildKit-Version das Artefakt erzeugt haben. Das macht den kompletten Build-Pfad nachvollziehbar – eine Anforderung, die in der EU-Cybersecurity-Regulierung (CRA) und in Supply-Chain-Sicherheitsframeworks wie SLSA zunehmend gefordert wird.

8. Artefakt-Builds in GitHub Actions und GitLab CI integrieren

In GitHub Actions und GitLab CI werden Deployment-Artefakte aus Docker Builds typischerweise in zwei Schritten erzeugt und gespeichert: Build und Upload. GitHub Actions bietet den actions/upload-artifact-Action, der beliebige Dateien als Build-Artefakte speichert und per Download oder zwischen Jobs übergibt. Kombiniert mit docker buildx build --output type=local,dest=./dist landen die Dateien nach dem Build im dist/-Verzeichnis und können direkt hochgeladen werden. Die Artefakte sind dann im GitHub Actions UI downloadbar und stehen nachfolgenden Jobs über actions/download-artifact zur Verfügung.

GitLab CI nutzt das Konzept der Artifacts-Direktive in .gitlab-ci.yml. Mit artifacts: paths: [dist/] und expire_in: 7 days werden die erzeugten Deployment-Artefakte aus Docker Builds nach dem Job-Lauf gespeichert und an nachfolgende Jobs in der Pipeline übergeben. Das ermöglicht den typischen CI/CD-Ablauf: Build-Job erzeugt Artefakte, Test-Job prüft sie, Deploy-Job überträgt sie auf den Produktionsserver – ohne, dass jeder Job den vollständigen Build wiederholen muss.

9. Artefakt-Extraktionsmethoden im Vergleich

Die verschiedenen Methoden, Deployment-Artefakte aus Docker Builds zu extrahieren, haben unterschiedliche Vor- und Nachteile je nach CI-Umgebung und Anforderungen.

Für moderne CI/CD-Pipelines ist BuildKit --output local mit einer nachgelagerten upload-artifact-Action die empfohlene Methode für Deployment-Artefakte aus Docker Builds. Sie kombiniert die Reproduzierbarkeit des Docker-Builds mit der Einfachheit eines direkten Dateiexports und benötigt keine Registry-Infrastruktur. Für Images, die deployed werden, bleibt der Registry-Push der Standard.

10. Zusammenfassung

Deployment-Artefakte aus Docker Builds zu erzeugen ist der sicherste Weg, um reproduzierbare, toolchain-unabhängige Builds in CI/CD-Pipelines sicherzustellen. Multi-Stage Dockerfiles trennen Build- und Runtime-Kontext sauber und halten die finale Image-Größe minimal. BuildKit Cache-Mounts eliminieren redundante Paket-Downloads und beschleunigen iterative Builds erheblich. Die --output-Methode von BuildKit ist der modernste Weg, um Artefakte direkt ins Host-Dateisystem zu schreiben, ohne den Umweg über Container-Erstellung und docker cp.

Für PHP-Projekte bedeutet das konkret: Composer-Vendor in einem Composer-Container erzeugen, Node-Assets in einem Node-Container kompilieren, beide Artefakte extrahieren und auf den Produktionsserver übertragen – ohne lokale PHP- oder Node-Installation. SBOM und Provenance als zusätzliche Deployment-Artefakte aus Docker Builds erfüllen zunehmende Compliance-Anforderungen und machen den gesamten Build-Pfad nachvollziehbar.

11. FAQ: Deployment-Artefakte aus Docker Builds