Docker Build-Args in Compose

Was dieser Artikel über Compose-Build-Args behandelt

• Unterschied zwischen args und environment.
• Build-Argumente an Dockerfiles übergeben.
• Verwendung in Multi-Stage-Builds.
• Tipps für sensible Werte.
• Häufige Fehler vermeiden.

Einleitung: Docker Build-Args in Compose

Wer eigene Images mit Docker Compose baut, muss oft während des Builds Informationen an das Dockerfile übergeben. Das können Versionen, Architekturen, Repository-URLs oder Flags sein. In Docker Compose geschieht das mit build.args. Laufzeitumgebungsvariablen hingegen werden mit environment gesetzt. Verwechselt man beides, kann das Build fehlschlagen oder sensible Daten im Image landen.

Dieser Artikel zeigt, wie Build-Args in Compose richtig eingesetzt werden.

Wichtige Begriffe

• Build-Arg: Variable während des Image-Builds.
• ENV: Variable im laufenden Container.
• ARG: Dockerfile-Anweisung für Build-Argumente.
• .env: Datei für Compose-Variablen.
• Multi-Stage: Mehrstufiger Build.
• Cache: Build-Layer-Zwischenspeicher.
• Secret: Geheimer Wert, nicht im Image.

args vs. environment

services:
  app:
    build:
      context: .
      args:
        APP_VERSION: "1.2.3"
    environment:
      NODE_ENV: production

APP_VERSION ist während des Builds verfügbar. NODE_ENV nur zur Laufzeit.

Dockerfile mit ARG

ARG APP_VERSION=1.0.0
FROM node:20

ENV APP_VERSION=${APP_VERSION}

RUN echo "Baue Version ${APP_VERSION}"

WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

.env-Datei nutzen

.env:

APP_VERSION=1.2.3
BUILD_TARGET=production

services:
  app:
    build:
      context: .
      args:
        APP_VERSION: ${APP_VERSION}
        BUILD_TARGET: ${BUILD_TARGET}

In Compose-Datei

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - APP_VERSION
        - BUILD_TARGET=production

Wenn nur der Name angegeben wird, nimmt Compose den Wert aus der Umgebung.

Build-Args und Cache

Build-Args sind Teil des Cache-Schlüssels. Ändert sich ein ARG, wird der entsprechende Layer neu gebaut:

ARG APP_VERSION
FROM base

Setze APP_VERSION möglichst spät, damit frühe Layer gecacht bleiben.

Multi-Stage mit ARG

ARG BUILD_TARGET=production

FROM node:20 AS builder
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
RUN npm run build

FROM node:20-alpine
COPY --from=builder /app/dist /app
CMD ["node", "/app/index.js"]

services:
  app:
    build:
      context: .
      args:
        BUILD_TARGET: production

Sensible Daten

Build-Args erscheinen nicht im laufenden Container, können aber im Image-Layer sichtbar sein:

docker history mein-image

Für Geheimnisse docker buildx build --secret oder BuildKit-Secrets in Compose nutzen:

services:
  app:
    build:
      context: .
      secrets:
        - npm_token

secrets:
  npm_token:
    file: ./npm_token.txt

Tipps

• ARG nur für Build-Zeit, ENV für Laufzeit.
• Sensible Werte nicht als ARG übergeben.
• ARGs spät im Dockerfile setzen, um Cache zu schonen.
• Werte in .env zentralisieren.
• Standardwerte im Dockerfile definieren.
• Doku führen, welche Args ein Image braucht.

Typische Stolpersteine

• ARG wird in Container nicht gefunden: Nur ENV oder andere Weitergabe ist sichtbar.
• Werte im Image: ARGs können in History sichtbar sein.
• Falsche Reihenfolge: Änderung von ARG invalidiert Cache.
• .env nicht geladen: Datei liegt im falschen Verzeichnis.
• Komposition fehlt: Nur args im Compose-Build nutzen.
• Sensible Daten in Build-Args: Sicherheitsproblem.

Weiterführende Links und Infos

• BotServ.de Docker Compose
• BotServ.de Docker Multi-Stage Builds
• BotServ.de Docker Image-Optimierung
• BotServ.de Docker Secrets

FAQ: Docker Build-Args in Compose

Was ist der Unterschied zwischen args und environment? args für den Build, environment für die Laufzeit.

Sind Build-Args im Container sichtbar? Nicht direkt, es sei denn, sie werden in ENV übernommen.

Kann ich Build-Args aus .env laden? Ja, über ${VARIABLE} in docker-compose.yml.

Sollte ich Secrets als Build-Args setzen? Nein, besser BuildKit-Secrets nutzen.

Was passiert, wenn ein ARG fehlt? Falls im Dockerfile ein Defaultwert steht, wird dieser genutzt.

Quellen und weiterführende Literatur

• Dockerfile ARG: https://docs.docker.com/engine/reference/builder/#arg
• Compose Build: https://docs.docker.com/compose/compose-file/build/
• BuildKit Secrets: https://docs.docker.com/build/building/secrets/

Zusammenfassung: Docker Build-Args in Compose

Build-Args erlauben es, Informationen an das Dockerfile zu übergeben, ohne sie im laufenden Container zu belassen. In Docker Compose werden sie über build.args gesetzt, im Dockerfile mit ARG empfangen. Umgebungsvariablen hingegen dienen der Laufzeit. Für Cache-Effizienz und Sicherheit sollten Build-Args spät gesetzt, sensible Werte als BuildKit-Secrets behandelt und Standardwerte im Dockerfile hinterlegt werden. Wer args und environment sauber trennt, vermeidet verbreitete Build- und Sicherheitsfehler.