Docker Compose: build oder image auf dem VPS
Erfahren Sie, wann Compose ein Image nutzt oder baut, warum Änderungen am Dockerfile bei compose up scheinbar ignoriert werden und wie Sie das korrekt beheben.
Docker Compose: build oder image – die Kurzantwort
In einer Docker-Compose-Datei legt image: das zu verwendende Image fest. Dabei kann es sich um ein lokales Image, ein Tag oder eine Digest-Referenz handeln. build: legt fest, wie Compose ein Image aus dem Quellcode erstellt. Wenn Sie nur image: setzen, verwendet Compose das Image gemäß pull_policy oder lädt es herunter. Wenn Sie nur build: setzen, erstellt Compose das Image mit dem konfigurierten Builder. Dabei erhält es einen Namen, der sich aus dem Projektnamen und dem Dienstnamen ergibt. Wenn Sie beide Optionen setzen, steuert pull_policy, ob Compose das Image herunterlädt oder erstellt. Beim Erstellen versieht Compose das Ergebnis mit dem Namen aus image:. So erstellen Sie ein Image und veröffentlichen es unter einem von Ihnen gewählten Namen. Der Builder kann lokal oder auf einem entfernten Docker-Host ausgeführt werden.
Das ist der gesamte Unterschied. Im Folgenden geht es darum, was dies im Betrieb auf einem Server bedeutet. Dieses Beispiel setzt voraus, dass Docker Engine und das Compose-Plugin bereits installiert sind. Docker auf einem VPS ausführen behandelt diesen Teil.
Die drei Formen vollständig
Verwenden Sie ein veröffentlichtes Tag. Falls es fehlt, wird es gemäß der standardmäßigen Pull-Richtlinie abgerufen. Ein Dockerfile ist dabei zu keinem Zeitpunkt beteiligt.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Erstellen Sie das Image aus einem Dockerfile im Projektverzeichnis. Der Build kann außerdem Images abrufen und die vom Dockerfile benötigten Abhängigkeiten herunterladen.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Erstellen und taggen Sie das Ergebnis mit docker compose build. Ohne eine explizite Pull-Richtlinie versucht up, dieses Image vor dem Build abzurufen. docker compose push kann dieses exakte Tag anschließend an eine Registry übertragen.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context ist das Verzeichnis, das an den Builder gesendet wird. dockerfile wird relativ zu diesem Kontext aufgelöst. Daher ist context: . mit dockerfile: docker/prod.Dockerfile normal und korrekt. Führen Sie docker compose images aus, um den Imagenamen und die Image-ID hinter jedem Service-Container anzuzeigen. Prüfen Sie die Compose-Datei, um zu bestätigen, ob der Service image:, build: oder beides verwendet.
Warum erstellt docker compose up kein neues Image, nachdem Sie die Dockerfile geändert haben?
Der normale up verwendet ein vorhandenes Image erneut, sofern Sie keinen Build anfordern oder eine Richtlinie konfigurieren, die einen Build voraussetzt.
Wenn Compose einen Dienst startet, der nur einen Abschnitt build: enthält, verwendet es das vorhandene Image, sofern eines verfügbar ist. Compose liest Ihre Dockerfile nicht ein, vergleicht Ihre Quelldateien nicht und prüft auch keine Zeitstempel. Wenn sowohl image: als auch build: vorhanden sind und kein explizites pull_policy angegeben ist, versucht Compose zuerst, das Image abzurufen, und erstellt es, wenn es in der Registry oder im Plattform-Cache nicht verfügbar ist. Ein vorhandenes Image gilt als ausreichend.
Sie bearbeiten also app.py, führen docker compose up -d aus, sehen, dass Compose den Container als laufend meldet, und stellen den alten Code bereit. Es ist kein Fehler aufgetreten, daher wurde auch keine Warnung ausgegeben. Ein Hinweis ist das Statuswort, das Compose neben dem Containernamen ausgibt: Ein von Compose ersetzter Container wird als recreated oder started gemeldet. Einen Container, den Compose unverändert lässt, meldet es als running.
Zwei Prüfungen schaffen Klarheit. docker compose images gibt die Image-ID aus, die jeder Container verwendet. Notieren Sie sie daher vor dem Deployment und vergleichen Sie sie danach. docker image ls enthält eine Spalte CREATED. Zwischengespeicherte Builds und reproduzierbare Zeitstempel bedeuten jedoch, dass dieses Datum allein nicht belegt, ob Ihr aktueller Quellcode erstellt wurde.
Welche Flags erzwingen einen Neuaufbau
docker compose up -d --buildführt zuerst den Build aus und erstellt anschließend alle Container neu, deren Image geändert wurde. Dieses Flag ist in den meisten Fällen gemeint.docker compose build weberstellt ein einzelnes Service-Image und startet keinen Container. Verwenden Sie anschließenddocker compose up --no-deps -d web, um nur diesen Container zu ersetzen, während der restliche Stack weiterläuft.docker compose build --no-cache webignoriert zwischengespeicherte Layer und erstellt das Service-Image neu.docker compose build --pullversucht, inFROMeine neuere Version des Basis-Images abzurufen. Dadurch verwendet ein veränderliches Tag wienode:22den aktuellen Inhalt statt der Kopie, die Sie im März heruntergeladen haben.docker compose up -d --force-recreateerzwingt die Neuerstellung von Containern, auch wenn sich Konfiguration und Image nicht geändert haben. Das Flag selbst fordert keinen Build an.upkann jedoch trotzdem einen Build ausführen, wenn ein Image fehlt oder die Pull-Richtlinie dies erfordert. Wenn Sie dieses Flag verwenden, obwohl Sie--buildbenötigen, führt das häufig in eine Sackgasse.
Sie können diese Entscheidung auch in die Datei verlagern. Laut Compose-Spezifikation bedeutet pull_policy: build, dass Compose das Image erstellt und erneut erstellt, wenn es bereits vorhanden ist. Jeder up verursacht dann einen Build. Das ist auf einem Laptop sinnvoll, auf einem Server aber selten.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildEine weitere Wechselwirkung sollten Sie kennen. docker compose pull versucht auch, Images für Services abzurufen, die zusätzlich einen Abschnitt build besitzen. Wenn dieser Pull fehlschlägt, weist der Befehl darauf hin, dass das Image stattdessen erstellt werden muss. Übergeben Sie --ignore-buildable, um diese Services still zu überspringen.
Wie der Build-Cache die Dauer Ihres Deployments bestimmt
Der Builder prüft für jede Dockerfile-Anweisung, ob ein wiederverwendbares Ergebnis aus dem Cache verfügbar ist, wenn diese Anweisung und ihre Eingaben unverändert sind. Bei COPY gehören dazu die Dateiinhalte und Metadaten, jedoch nicht die Änderungszeiten. Sobald eine Ebene den Cache verfehlt, werden die nachfolgenden Schritte, die von ihr abhängen, neu erstellt.
Diese eine Regel entscheidet, ob Ihr Deployment Sekunden oder Minuten dauert. Ordnen Sie das Dockerfile von selten geänderten zu regelmäßig geänderten Inhalten.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci steht über COPY . .. Wenn Sie eine Quelldatei bearbeiten, bleibt die Installationsschicht daher im Cache, und der Build wird beim Kopierschritt fortgesetzt. Vertauschen Sie diese beiden Zeilen, installiert bereits eine Änderung an einem Zeichen jede Abhängigkeit neu, weil COPY . . die Schicht ungültig macht, auf der npm ci aufbaut. Dasselbe Muster gilt für pip install -r requirements.txt und go mod download.
--no-cache ist das richtige Werkzeug, wenn Sie vermuten, dass eine veraltete Schicht Ihre Änderung verdeckt. Als Standard ist es jedoch ungeeignet, weil es die Wiederverwendung verwirft, die durch die Reihenfolge im Dockerfile erreicht werden soll.
Eine Einstellung kann sowohl das Image als auch Compose festlegen oder überschreiben: Das CMD des Dockerfiles bestimmt, was das Image standardmäßig ausführt. Ein Schlüssel command: im Dienst ersetzt diese Einstellung. Wie command und entrypoint zusammenwirken ist hier relevant, weil eine Compose-Überschreibung ein neu erstelltes Image genau wie das alte verhalten lassen kann.
Build-Kontext und .dockerignore
context: . stellt das Projektverzeichnis dem Builder zur Verfügung. Ohne Ausschlüsse umfasst er auch .git und jedes Datenverzeichnis, das Sie möglicherweise neben Ihrem Quellcode aufbewahren. BuildKit überspringt jedoch nicht verwendete Dateien und überträgt Änderungen inkrementell. Wenn ein Build beim Schritt zur Übertragung des Kontexts eines ansonsten unveränderten Projekts pausiert, ist der Kontext zu groß.
Eine Datei .dockerignore im Stammverzeichnis des Kontexts schließt Pfade von dieser Übertragung aus. Die Syntax ähnelt .gitignore.
.git
node_modules
*.log
data/
.envDas bringt zwei Vorteile. Die Übertragung wird kleiner, sodass weniger Zeit für das Senden dieser Dateien benötigt wird. Außerdem kann COPY . . .env nicht mehr in das Image kopieren. Jeder, der dieses Image abruft, kann die Datei sonst wieder auslesen.
Ein Fall, bei dem sich ein Build mit der Zeit verlangsamt, ist ein Bind-Mount. Ein benanntes Volume liegt außerhalb Ihres Projektverzeichnisses. Ein Bind-Mount wie ./data:/var/lib/postgresql/data liegt dagegen innerhalb des Build-Kontexts. Dadurch werden Ihre Builds jede Woche langsamer, während die Datenbank wächst. Eine Zeile in .dockerignore behebt das Problem. Bind-Mounts gegenüber benannten Volumes behandelt den allgemeinen Kompromiss.
Build-Argumente bergen ein kleineres Risiko derselben Art. Werte, die über args: übergeben werden, können in der Image-Historie oder in Provenance-Metadaten erhalten bleiben. Hinterlegen Sie dort daher eine Versionsnummer und niemals ein Token. Vordefinierte Proxy-Argumente werden standardmäßig aus dem Build-Cache und docker history ausgeschlossen, sofern sie nicht ausdrücklich im Dockerfile referenziert werden. Env-Dateien und Secrets in Compose erläutert stattdessen, wo Zugangsdaten hinterlegt werden.
Sollten Sie auf dem VPS bauen oder den Build an anderer Stelle ausführen und das Image anschließend abrufen?
Das Bauen auf dem Server, der Ihren Netzwerkverkehr bedient, ist der Standard, weil dies der kürzeste Weg ist: git pull, dann docker compose up -d --build. Auf einem kleinen Server, von dem noch niemand abhängig ist, ist das unproblematisch. Aus zwei messbaren Gründen und einem weiteren, der sich erst an einem schlechten Tag zeigt, ist es das später nicht mehr.
Arbeitsspeicher. Ein Build führt Compiler und Bundler neben Ihrer laufenden Anwendung aus. Diese benötigen in den meisten Stacks besonders viel Arbeitsspeicher. Ein JavaScript-Bundler oder ein Rust-Compile-Vorgang kann den verfügbaren Arbeitsspeicher eines VPS mit 1 GB erschöpfen. Bei erschöpftem Arbeitsspeicher wählt der Kernel anhand eines Bewertungswerts für Speicherverbrauch, Allokationskontext und oom_score_adj einen OOM-Prozess aus. Er beendet nicht einfach den größten Prozess. Der Build kann mit Killed und dem Exit-Status 137 abbrechen. Alternativ wird Ihre Datenbank beendet, und die Website kann während eines Deployments ausfallen. dmesg -T | grep -i oom durchsucht das Kernel-Log nach OOM-Meldungen. Für den Zugriff benötigen Sie die Berechtigung, dieses Log zu lesen.
Datenträger. Builds hinterlassen Image-Layer und Build-Cache. docker system df zeigt deren Speicherverbrauch. Die regelmäßige Garbage Collection von BuildKit gibt Cache gemäß den konfigurierten Richtlinien frei. Verwenden Sie docker image prune für verwaiste Images und docker builder prune für gecachte Layer. Ein voller Datenträger bringt nicht nur den Build zum Stillstand. Auch die Datenbank kann nicht mehr schreiben. Dieser Ausfall verursacht deutlich höhere Kosten als ein langsames Deployment.
Reproduzierbarkeit. Wenn Sie ein auf dem Server erstelltes Image nicht pushen oder exportieren, existiert es nur auf diesem Server. Ist das alte Image nicht mehr verfügbar, bedeutet ein Rollback, den alten Commit auszuchecken und erneut zu bauen. Es ist nicht garantiert, dass dieser Build dasselbe Ergebnis erzeugt. Der Base-Tag kann sich geändert haben, und auch die Paket-Mirrors können inzwischen andere Inhalte liefern. Wenn Sie an anderer Stelle bauen und einen Tag pushen, wird ein Rollback zu einer Änderung: Setzen Sie image: auf den vorherigen Tag und führen Sie docker compose up -d aus.
Eine robuste Anordnung ist einfach. Ihre Continuous Integration führt den Build aus und pusht registry.example.com/acme/web:<git-sha>. Die Compose-Datei auf dem VPS enthält image: und überhaupt keinen Schlüssel build:. Das Deployment besteht dann aus zwei Befehlen, die nahezu keinen Arbeitsspeicher benötigen.
docker compose pull
docker compose up -dFühren Sie auf dem Server docker login registry.example.com aus, um Anmeldedaten für das Abrufen privater Tags zu speichern.
Behalten Sie den Build-Abschnitt für die Entwicklung bei, statt ihn zu löschen, und verwenden Sie dafür eine Datei mit einem eigenen Namen.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildNennen Sie diese Datei compose.dev.yaml und nicht compose.override.yaml. Compose lädt automatisch eine Override-Datei, sobald sie vorhanden ist. Eine versehentlich auf den Server kopierte Override-Datei würde daher unbemerkt wieder Builds auf dem Server aktivieren. Mehrere Compose-Dateien schichten erklärt, wie der Merge jeden Schlüssel auflöst.
Die Architektur-Falle beim Bauen auf einem anderen System
Ein einzelnes Plattform-Image enthält die CPU-Architektur, für die es erstellt wurde. Wenn Sie ein ARM-Image auf einem Apple-Silicon-Laptop erstellen, es pushen und anschließend auf einem x86_64-VPS verwenden, warnt Docker beim Erstellen des Containers, wenn es ein inkompatibles zwischengespeichertes Image ohne explizite Plattform verwendet. Ohne Emulation schlägt der Prozess mit exec format error fehl. Das sieht wie eine beschädigte Binärdatei aus, ist aber keine. Erstellen Sie das Image ausdrücklich für das Zielsystem:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .Dieselbe Inkompatibilität tritt umgekehrt auf, wenn Ihr Laptop x86 verwendet und Sie statt eines x86-VPS einen ARM-VPS betreiben. Wenn die CI auf der Architektur baut, auf der Sie deployen, entfällt diese Unsicherheit. Ein Multi-Plattform-Image löst das Problem ebenfalls: Docker wählt beim Abrufen die passende Variante aus.
Was Sie nach einem Deployment prüfen sollten
docker compose imagesgibt das Image und den Tag hinter jedem laufenden Container aus. Eine geänderte Image-ID belegt, dass der neue Build aktiv ist.docker compose configgibt die zusammengeführte Datei nach der Variablensubstitution aus. So können Sie den endgültigen Imagenamen lesen, den Compose verwendet, bevor Sie etwas ausführen.docker compose logs -f webfür die erste halbe Minute nach dem Austausch. Ein Container, der wiederholt startet und beendet wird, wird nur dann neu gestartet, wenn seine Restart-Richtlinie dies vorsieht. Prüfen Sie die Logs auf die Ursache.docker image lszeigt eine Spalte CREATED an. Prüfen Sie zusätzlich die Build-Ausgabe und die Image-ID des Deployments, da der Erstellungszeitpunkt allein nicht belegt, ob ein Rebuild ausgeführt wurde.
Wenn Sie die Datei, gegen die diese Prüfungen ausgeführt werden, noch zusammenstellen, behandelt der grundlegende Aufbau einer Compose-Datei auf einem VPS die zugehörigen Schlüssel. Das Spickblatt für Compose-Befehle führt die übrigen Subcommands auf.
FAQ
Kann ich build und image im selben Dienst verwenden?
Ja. Das ist die übliche Konfiguration für ein Projekt, das Sie selbst bauen. Wenn Compose aus dem Abschnitt build: baut, versieht es das Ergebnis mit dem Wert von image:. Ohne explizites pull_policy versucht up zuerst, das Image zu laden. Dieser Tag wird von docker compose push an eine Registry übertragen und von einem anderen Rechner abgerufen. Ohne einen image:-Schlüssel baut Compose weiterhin, benennt das Image jedoch nach dem Projekt und dem Dienst. Außerdem wird gewarnt, dass das fehlende Attribut verhindert, dass das Image übertragen wird.
Warum übernimmt docker compose up meine Änderung an der Dockerfile nicht?
Weil normales up ein vorhandenes Image wiederverwendet, sofern Sie keinen Build anfordern oder keine Richtlinie konfigurieren, die einen Build erfordert. Der Befehl vergleicht das Image nicht mit Ihrer Dockerfile oder Ihren Quelldateien, um zu entscheiden, ob ein erneuter Build erforderlich ist. Führen Sie docker compose up -d --build aus. Alternativ können Sie docker compose build web und anschließend docker compose up --no-deps -d web ausführen, um einen einzelnen Dienst zu ersetzen. Wenn Sie beim Dienst pull_policy: build festlegen, wird bei jedem up ein erneuter Build ausgeführt. Das eignet sich für einen Entwicklungsrechner.
Was ist der Unterschied zwischen --build und --force-recreate?
--build erstellt das Image erneut und erstellt anschließend die Container neu, deren Image geändert wurde. --force-recreate erzwingt die Neuerstellung der Container, auch wenn sich Konfiguration und Image nicht geändert haben. Der Befehl fordert selbst keinen Build an. Wenn Ihre Änderung den Quellcode oder die Dockerfile betrifft, ist --build das richtige Flag. --force-recreate dient zum Zurücksetzen des Containers selbst, beispielsweise um seine beschreibbare Schicht zu löschen und dabei dasselbe Image beizubehalten.
Sollte ich meine Docker-Images auf dem VPS oder an einem anderen Ort bauen?
Bauen Sie an einem anderen Ort und rufen Sie einen Tag ab, sobald der Rechner auch Netzwerkverkehr für Ihre Anwendung verarbeitet. Ein Build konkurriert mit Ihrer Anwendung um Arbeitsspeicher. Bei Speichermangel wählt der Kernel anhand eines anpassbaren OOM-Scores einen Prozess aus. Dabei kann es den Build oder Ihre Datenbank treffen. Builds hinterlassen außerdem Cache auf der Festplatte. BuildKit räumt diesen Cache jedoch automatisch gemäß seinen Richtlinien für die Garbage Collection auf. Das Bauen auf dem Server ist für ein kleines Projekt ohne Benutzer weiterhin unproblematisch. Ein späterer Umzug verursacht wenig Aufwand, wenn Sie den Abschnitt build: in einer Compose-Datei nur für die Entwicklung beibehalten.
Wie verhindere ich, dass der Docker-Build-Cache meine Festplatte füllt?
Führen Sie docker system df aus, um zu sehen, wie viel Speicher Ihre Images und Ihr Build-Cache jeweils belegen. docker builder prune entfernt zwischengespeicherte Schichten. docker image prune entfernt die verwaisten Images, die von früheren Builds zurückgeblieben sind. Das Hinzufügen von -a entfernt jeweils den gesamten ungenutzten Build-Cache oder alle Images, die von keinem Container referenziert werden. Dadurch wird nicht garantiert, dass der nächste Build vollständig ohne Cache ausgeführt wird. Planen Sie docker system prune -af --volumes nicht auf einem Server ein. Der Befehl entfernt beendete Container und ungenutzte anonyme Volumes. Dadurch sind Datenbanken in einem anonymen Volume während der Wartung gefährdet.