SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

Docker Compose exec: Interaktive Shell öffnen

Mit docker compose exec öffnen Sie eine Shell im laufenden Dienst. Ist der Dienst gestoppt, erstellt docker compose run stattdessen einen neuen Container.

Eine interaktive Shell mit docker compose exec öffnen

docker compose exec web bash öffnet eine interaktive Shell in dem Container, in dem der Dienst web bereits läuft. Der Name nach exec ist der Dienstname aus Ihrer compose.yaml, nicht der Containername. Wenn das Image kein bash enthält, verwenden Sie stattdessen sh.

docker compose ps
docker compose exec web bash

Führen Sie zuerst docker compose ps aus. Die Ausgabe sollte web mit dem Status running enthalten. Der zweite Befehl bringt Sie anschließend zu einer Eingabeaufforderung im Container. Mit exit oder Strg-D kehren Sie zum Host zurück. Der Dienst läuft weiter, nachdem Sie die Shell verlassen haben, weil exec einen zweiten Prozess neben dem Hauptprozess gestartet hat. Das Schließen Ihrer Shell wirkt sich nicht auf PID 1 (Prozess-ID 1) aus. Dabei handelt es sich um den Prozess, für dessen Ausführung der Container erstellt wurde.

Das ist eine von zwei Möglichkeiten, in den Container zu gelangen. exec verbindet sich mit einem bereits vorhandenen Container. docker compose run erstellt anhand derselben Dienstdefinition einen neuen Container. Fast alles Weitere in diesem Leitfaden ergibt sich aus diesem einen Unterschied.

Warum -it in Compose optional, bei plain docker jedoch erforderlich ist

Zwei Flags steuern den interaktiven Teil einer Sitzung. -i hält stdin geöffnet, sodass Ihre Eingaben den Prozess erreichen. -t weist ein Pseudoterminal zu, kurz TTY genannt, sodass die Shell eine Eingabeaufforderung ausgibt und Pfeiltasten verarbeitet. Plain docker exec deaktiviert beides standardmäßig. Deshalb schreibt jedes bisher gezeigte Beispiel docker exec -it. docker compose exec aktiviert beides für Sie. Daher bewirken docker compose exec -it web bash und docker compose exec web bash dasselbe. Compose akzeptiert -it weiterhin, damit vertraute Eingabegewohnheiten funktionieren.

Eine fehlende TTY erkennen Sie innerhalb weniger Sekunden. Die Shell läuft, gibt aber keine Eingabeaufforderung aus, und Ctrl-C erreicht den Prozess nicht. Für den umgekehrten Fall, in dem Compose ausdrücklich keine TTY zuweisen soll, gibt es ein eigenes Flag und weiter unten einen eigenen Abschnitt.

Was tun, wenn das Image keine bash enthält

Fordern Sie bei einem Alpine-basierten Image bash an. Der Aufruf von exec schlägt dann wie folgt fehl:

OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknown

Diese Meldung weist nicht auf ein exec-Problem hin. Sie besagt, dass in keinem der Verzeichnisse aus dem PATH des Containers ein bash gefunden wurde. Bei einer Shell bedeutet das fast immer, dass das Image keine Shell enthält. Alpine liefert BusyBox aus. BusyBox stellt ash als /bin/sh bereit, aber keine bash. Fordern Sie daher sh an:

docker compose exec web sh

Debian- und Ubuntu-basierte Images, einschließlich der -slim-Tags, enthalten bash. bash bietet eine Befehlshistorie und eine bessere Vervollständigung. Versuchen Sie daher zuerst bash und verwenden Sie andernfalls sh. sh ist in fast jedem Image für allgemeine Zwecke vorhanden.

Einige Images enthalten überhaupt keine Shell. Distroless-Images und Images, die FROM scratch erstellt wurden, enthalten absichtlich nur das Anwendungsprogramm und seine Bibliotheken. Eine nicht vorhandene Shell kann nicht gegen die Anwendung verwendet werden. Bei diesen Images schlägt sh mit derselben Meldung fehl. Es gibt dann keine weitere Shell, die Sie ausprobieren können. Zwei Vorgehensweisen sind möglich. Die distroless-Images von Google stellen :debug-Tags bereit, die eine BusyBox-Shell hinzufügen. Durch einen vorübergehenden Wechsel zu diesem Tag erhalten Sie Zugriff. Alternativ können Sie einen separaten Container in den Namespaces des Zielcontainers starten:

CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot

Sie verfügen nun über die Werkzeuge von netshoot, die auf das Netzwerk der Anwendung zeigen. curl localhost:8080 und ss -lntp verhalten sich dadurch so, als würden Sie sie innerhalb des Zielcontainers ausführen. Das angezeigte Dateisystem gehört netshoot und nicht der Anwendung. Da der Prozess-Namespace gemeinsam genutzt wird, zeigt /proc/1/root/ auf das Dateisystem des Zielprozesses. ls /proc/1/root/ muss jedoch die ptrace-Berechtigungsprüfung des Kernels bestehen. Dass beide Prozesse als root ausgeführt werden, reicht nicht aus. Die Prüfung berücksichtigt außerdem Anmeldedaten, Capabilities, das dumpable-Attribut des Zielprozesses und Security-Module. Ein dumpable-Wert ungleich 1 blockiert den Zugriff, sofern der Aufrufer nicht über CAP_SYS_PTRACE im User-Namespace des Zielprozesses verfügt. Docker gewährt SYS_PTRACE standardmäßig nicht. Das Hinzufügen von --cap-add SYS_PTRACE zur docker run-Zeile erfüllt die Prüfungen für Anmeldedaten und dumpability. Security-Module können den Zugriff jedoch weiterhin verweigern.

Wenn der Dienst nicht läuft, verwenden Sie docker compose run --rm

exec benötigt einen laufenden Container. Wenn Sie den Befehl auf einen gestoppten Dienst anwenden, wird er abgelehnt:

service "web" is not running

Der Befehl startet nichts für Sie. docker compose run führt Folgendes aus:

docker compose run --rm web bash

run erstellt aus der Dienstdefinition web einen neuen Container mit demselben Image, denselben Umgebungsvariablen, Volumes und Netzwerken. Anschließend ersetzt der Befehl den Dienstbefehl durch den von Ihnen eingegebenen Befehl. --rm löscht diesen Container, sobald Sie ihn beenden. Wenn Sie --rm weglassen, sammeln sich die übrigen Container unter Namen wie myproject-web-run-4f1c2b an. docker compose ps -a zeigt diese Container an, und docker compose rm entfernt sie zusammen mit den anderen gestoppten Containern des Dienstes.

Zwei Verhaltensweisen von run überraschen viele Benutzer. Der Befehl veröffentlicht die Ports des Dienstes nicht, sofern Sie nicht --service-ports hinzufügen oder einen Port manuell mit -p zuordnen. Das ist beabsichtigt: Ein zweiter Container, der den Host-Port 8080 bindet, würde fehlschlagen, solange der erste Container diesen Port noch verwendet. bind: address already in use. Außerdem startet run alles, was der Dienst unter depends_on aufführt, bevor Ihre Shell angezeigt wird. Ein kurzer Blick in den Container kann dadurch eine Datenbank und einen Cache starten. --no-deps überspringt diesen Schritt.

run durchläuft den ENTRYPOINT des Images, exec dagegen nicht. exec startet Ihren Befehl direkt im vorhandenen Container. Das Entrypoint-Skript bekommt ihn daher nie zu sehen. Bei run wird Ihr bash als Argument an dieses Skript übergeben. Viele offizielle Images beenden ihr Entrypoint-Skript mit exec "$@". Dadurch wird der Befehl direkt weitergereicht, und Sie erhalten Ihre Shell. Ein Skript, das seine Argumente selbst interpretiert, führt dagegen eine andere Aktion aus. Für diesen einen Lauf können Sie den Entrypoint dann ersetzen:

docker compose run --rm --entrypoint sh web

Das ist der häufigste Grund dafür, dass sich ein Befehl unter exec anders verhält als unter run. Die Trennung zwischen Befehl und Entrypoint erklärt, welchen Teil der Image-Konfiguration Sie jeweils ersetzen.

exec oder run: Auswahl

  • exec benötigt einen laufenden Container. run nicht; run kann außerdem Abhängigkeiten starten.
  • exec sieht die aktuelle Prozessliste und die Dateien in ihrem derzeitigen Zustand, einschließlich aller Daten, die die Anwendung seit ihrem Start geschrieben hat. run erhält eine saubere beschreibbare Schicht aus dem Image. Benannte Volumes und Bind-Mounts stellen jedoch weiterhin die vorhandenen Daten des Dienstes bereit.
  • exec überspringt den Entrypoint. run führt ihn aus.
  • run hinterlässt einen Container, sofern Sie nicht --rm übergeben.

Verwenden Sie exec, um zu prüfen, was tatsächlich passiert. Verwenden Sie run --rm für eine kurzlebige Kopie derselben Umgebung, für einen einmaligen Migrationsbefehl oder wenn der eigentliche Dienst nicht lange genug aktiv bleibt, um exec darin auszuführen.

Nützliche exec-Flags: Benutzer, Arbeitsverzeichnis und Replikate

Die meisten Images wechseln zu einem Nicht-root-Benutzer. Deshalb kommen Sie beim Installieren eines Diagnosewerkzeugs innerhalb Ihrer exec-Shell an dieser Stelle nicht weiter:

E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)

-u root öffnet eine root-Shell im selben Container:

docker compose exec -u root web sh

-w /srv/app legt nur für diesen Befehl das Arbeitsverzeichnis fest. -e KEY=value fügt Ihrer Sitzung eine Umgebungsvariable hinzu, nicht dem Dienst. Wenn ein Dienst mit mehr als einem Replikat ausgeführt wird, bestimmt --index 2, in welchem Container Sie landen. Wenn Sie die Dateibesitzrechte in einem eingebundenen Verzeichnis untersuchen, erklärt PUID und PGID in Container-Images, warum die numerischen IDs und nicht die Benutzernamen bestimmen, wer dort schreiben darf.

Eine psql- oder mysql-Shell im Datenbank-Container öffnen

Der Client ist bereits im Datenbank-Image enthalten. Sie benötigen daher keinen Client auf dem Host und müssen den Port nicht veröffentlichen:

docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -p

Postgres-Images enthalten psql, MySQL-Images enthalten mysql und MariaDB-Images enthalten mariadb. Die Verbindung wird innerhalb des Containers hergestellt. Das funktioniert daher auch dann, wenn die Compose-Datei überhaupt keinen Datenbankport veröffentlicht. Das ist die sicherere Konfiguration im standardmäßigen Bridge-Netzwerk von Docker: Externe Hosts können einen nicht veröffentlichten Datenbankport nicht direkt erreichen. Der Docker-Host und Container im selben Netzwerk können dies jedoch weiterhin.

Eine Falle kostet häufig einen ganzen Nachmittag. Ihre Shell expandiert Variablen auf dem Host, bevor Docker den Befehl erhält. Daher übergibt -U "$POSTGRES_USER" eine leere Zeichenkette, wenn die Variable nur innerhalb des Containers existiert. Mit einfachen Anführungszeichen und einer Shell innerhalb des Containers wird die Variable an der richtigen Stelle expandiert:

docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'

Verwenden Sie hier nicht docker compose run --rm db ohne Befehl. Dadurch wird ein zweiter Postgres-Server für dasselbe Datenvolume gestartet. Dieser Server startet nicht:

FATAL:  lock file "postmaster.pid" already exists

Die Sperrdatei erfüllt ihre Aufgabe, weil zwei Server beim Schreiben in dasselbe Datenverzeichnis dieses beschädigen würden. Solange die Datenbank läuft, verwenden Sie exec für den Zugriff auf den laufenden Container. Ob die Datenbank überhaupt in Compose ausgeführt werden sollte, ist eine separate Entscheidung. Die Datenbank in Docker oder auf dem Host ausführen erläutert die jeweiligen Vor- und Nachteile.

Dienste, die beim Start eine Konsole benötigen: stdin_open und tty

exec und run decken Shells ab, die Sie manuell öffnen. Ein Dienst, dessen Hauptprozess interaktiv arbeitet, benötigt zwei Schlüssel in der Compose-Datei:

services:
  console:
    image: python:3.12-slim
    command: python
    stdin_open: true
    tty: true

stdin_open: true ist docker run -i und tty: true ist docker run -t. Ohne diese Einstellungen startet der Container und beendet sich sofort mit Code 0. docker compose ps -a zeigt dann Exited (0). Es ist kein Fehler aufgetreten. python ohne Terminal an stdin liest sofort das Dateiende und beendet sich normal. Das ist das korrekte Verhalten für ein Programm, in das niemand Eingaben macht.

Wenn beide Schlüssel gesetzt sind, verbinden Sie sich mit dem laufenden Prozess:

docker attach $(docker compose ps -q console)

Trennen Sie die Verbindung mit Ctrl-P und anschließend Ctrl-Q. Der Prozess läuft dabei weiter. Diese Tastenkombination funktioniert nur, wenn der Container sowohl über ein TTY als auch über geöffnetes stdin verfügt. Ctrl-C sendet dagegen ein Interrupt-Signal (SIGINT) an PID 1. Dadurch wird der Dienst nur beendet, wenn das Programm auf SIGINT mit dem Beenden reagiert. Linux stellt für PID 1 keine standardmäßige Signalverarbeitung bereit. Verwenden Sie Ctrl-C daher nicht zum Trennen der Verbindung.

Lassen Sie beide Schlüssel bei gewöhnlichen Diensten deaktiviert. Ein Webserver liest niemals stdin. tty: true veranlasst viele Programme außerdem, auf Farbausgabe und Zeilenpufferung umzuschalten, weil sie davon ausgehen, dass jemand die Ausgabe beobachtet. Dadurch wird docker compose logs mit Escape-Codes gefüllt.

Warum ein skriptgesteuertes exec in cron und CI fehlschlägt: das Flag -T

Ein exec-Befehl, der in Ihrem Terminal funktioniert, kann fehlschlagen, wenn ein Skript ihn ausführt, in einem cron-Job oder einem Continuous-Integration-(CI-)Runner läuft oder über eine Pipe geleitet wird:

the input device is not a TTY

Compose fordert ein Pseudo-Terminal an, sobald die eigene Ausgabe an ein Terminal geht. Die Anforderung schlägt fehl, bevor Ihr Befehl ausgeführt wird, wenn stdin ebenfalls kein Terminal ist. Der aktuelle Docker-CLI-Quellcode bezeichnet denselben Fehler als cannot attach stdin to a TTY-enabled container because stdin is not a terminal. Aktuelle Compose-Versionen überspringen die Anforderung selbstständig, wenn die Ausgabe umgeleitet oder über eine Pipe geleitet wird, wie es unter cron normalerweise der Fall ist. Einige frühere Releases stellten die Anforderung unabhängig davon. Auch cat dump.sql | docker compose exec db psql, das Sie an Ihrer eigenen Eingabeaufforderung eingeben, löst den Fehler weiterhin aus. -T deaktiviert die Anforderung in jedem Fall. Verwenden Sie das Flag daher in Skripten, statt sich auf die Erkennung zu verlassen:

0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump

-T ist aus einem zweiten Grund wichtig. Ein TTY verändert den Bytestrom bei der Ausgabe. Ein komprimiertes Dump-File, das ein TTY durchläuft, kommt daher beschädigt an. Geben Sie -T bei jeder umgeleiteten oder über eine Pipe geleiteten Ausgabe explizit an.

Beachten Sie bei cron zwei weitere Details. Geben Sie -f mit einem absoluten Pfad an, weil cron den Job aus dem Home-Verzeichnis startet. Dort befindet sich keine Compose-Datei. Compose beendet sich dann mit no configuration file provided: not found. Außerdem gibt exec den Exit-Code des ausgeführten Befehls zurück. Ein fehlschlagendes pg_dump lässt Ihr Skript unter set -e daher fehlschlagen, statt ein leeres Backup zu schreiben und Erfolg zu melden. Die übrigen Befehle für den Alltag sind in einer Compose-Befehlsübersicht zusammengestellt, die Sie neben diesen Skripten aufbewahren sollten.

Warum Änderungen im Container verschwinden

Sie installieren ein Tool mit exec, bearbeiten eine Konfigurationsdatei, beheben das Problem, und eine Woche später ist die Änderung verschwunden. Das entspricht dem vorgesehenen Verhalten der beschreibbaren Container-Schicht. docker compose up -d zerstört nach jeder Änderung am Image-Tag oder an der Servicedefinition den alten Container und erstellt anhand des Images einen neuen. Jede manuelle Änderung geht mit dem alten Container verloren.

docker compose restart arbeitet anders. Es stoppt und startet denselben Container, sodass manuelle Änderungen erhalten bleiben. Deshalb kann eine manuelle Korrektur wochenlang zu funktionieren scheinen und dann bei einem unabhängigen Update verschwinden. Named Volumes und Bind-Mounts überstehen beide Vorgänge, weil ihre Daten außerhalb des Containers gespeichert werden. Bind-Mounts und Named Volumes beschreibt, welche Variante für Daten geeignet ist, die Sie dauerhaft behalten möchten.

Betrachten Sie eine exec-Shell daher als Ort zum Lesen und Testen. Sobald die Korrektur feststeht, tragen Sie sie dort ein, wo sie erhalten bleibt: ein Paket in die Dockerfile, eine Einstellung in die Compose-Datei. Führen Sie anschließend docker compose up -d aus, und prüfen Sie mit einem weiteren exec-Befehl, ob der neue Container die Änderung tatsächlich enthält.

FAQ

Was ist der Unterschied zwischen docker compose exec und docker compose run?

exec führt einen Befehl in einem bereits laufenden Container neben dem Hauptprozess aus und überspringt den EntryPoint des Images. run erstellt anhand derselben Servicedefinition einen neuen Container mit demselben Image, derselben Umgebung, denselben Volumes und denselben Netzwerken, übergibt Ihren Befehl an den EntryPoint und startet zuerst alle depends_on-Dienste. run veröffentlicht die Ports des Dienstes außerdem nicht, sofern Sie nicht --service-ports oder ein -p-Mapping hinzufügen. Verwenden Sie exec, um den laufenden Dienst zu untersuchen. Verwenden Sie run --rm, wenn der Dienst gestoppt ist oder Sie einen separaten Container benötigen. Beachten Sie jedoch, dass Named Volumes und Bind-Mounts gemeinsam verwendet werden.

Warum meldet docker compose exec, dass der Dienst nicht läuft?

exec verbindet sich mit einem vorhandenen Container und kann keinen Container erstellen. Deshalb führt ein gestoppter oder abgestürzter Dienst zu service "web" is not running. Prüfen Sie docker compose ps -a. Der Befehl listet beendete Container mit einem Status wie Exited (1) auf. Lesen Sie docker compose logs web, um den Grund für das Beenden zu ermitteln. Um trotzdem eine Shell zu öffnen, führen Sie docker compose run --rm --entrypoint sh web aus. Dadurch wird anhand derselben Servicedefinition ein neuer Container erstellt, ohne den fehlerhaften Startbefehl auszuführen.

Wie öffne ich eine Shell, wenn das Image kein bash enthält?

Wenn docker compose exec web bash mit exec: "bash": executable file not found in $PATH fehlschlägt, wurde in den Verzeichnissen von PATH kein bash gefunden. Das bedeutet fast immer, dass das Image bash nicht enthält. Das ist bei Images auf Basis von Alpine normal. Verwenden Sie docker compose exec web sh, weil BusyBox /bin/sh bereitstellt. In einem Image ohne Shell kann exec keine Shell öffnen. Es kann jedoch weiterhin ausführbare Dateien starten, die im Image enthalten sind. Wechseln Sie zum :debug-Tag des Images, falls der Herausgeber einen solchen anbietet. Alternativ können Sie mit docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot einen Debug-Container in den Namespaces des Zielcontainers starten. Dabei stammt $CID aus docker compose ps -q web.

Warum schlägt mein exec-Befehl in cron mit „the input device is not a TTY“ fehl?

docker compose exec fordert ein Pseudo-Terminal an, wenn die Ausgabe an ein Terminal geht. Die Anforderung schlägt ebenfalls fehl, wenn stdin kein Terminal ist. Aktuelle Compose-Versionen überspringen die Anforderung selbstständig, wenn die Ausgabe umgeleitet wird, wie es in cron normalerweise der Fall ist. Einige frühere Releases forderten ein TTY jedoch unabhängig davon an. Auch das Weiterleiten von Eingaben aus einer interaktiven Shell an exec löst den Fehler weiterhin aus. Fügen Sie -T hinzu, um die Anforderung zu deaktivieren: docker compose exec -T db pg_dump -U postgres app. Verwenden Sie -T auch für umgeleitete oder weitergeleitete Ausgaben, weil ein TTY den Byte-Datenstrom verändert und einen Binär-Dump beschädigt. Übergeben Sie cron außerdem -f mit dem absoluten Pfad zu Ihrer Compose-Datei. Andernfalls beendet sich Compose mit no configuration file provided: not found.

Bleiben Änderungen, die ich mit exec in einem Container vornehme, nach einem Neustart erhalten?

Sie bleiben nach docker compose restart erhalten, weil dabei derselbe Container wiederverwendet wird. Nach docker compose up -d gehen sie bei jeder Änderung am Image oder an der Konfiguration verloren, weil der Container aus dem Image neu erstellt und seine beschreibbare Schicht verworfen wird. Daten in Named Volumes oder Bind-Mounts bleiben in beiden Fällen erhalten, weil sie außerhalb des Containers gespeichert sind. Nehmen Sie Diagnoseänderungen mit exec vor. Legen Sie die dauerhafte Version anschließend im Dockerfile oder in der Compose-Datei fest.

War dieser Artikel hilfreich?