Docker Composeで実行中コンテナにシェルで入る方法
docker compose exec web bashで実行中のサービスに対話型シェルを開けます。bashがない場合はshを使い、停止中ならdocker compose runで新しいコンテナを起動します。
docker compose exec で対話型シェルを取得する
docker compose exec web bash は、web サービスとしてすでに実行中のコンテナ内で対話型シェルを開きます。exec の後に指定する名前は、コンテナ名ではなく compose.yaml に記載されたサービス名です。イメージに bash がない場合は、代わりに sh を指定します。
docker compose ps
docker compose exec web bash最初に docker compose ps を実行します。web が running の状態で一覧表示されるはずです。次に2つ目のコマンドを実行すると、コンテナ内のプロンプトが表示されます。exit または Ctrl-D を入力するとホストに戻ります。exec はメインプロセスとは別の2つ目のプロセスを起動するため、シェルを終了してもサービスは実行を続けます。シェルを閉じても PID 1(プロセス ID 1)には影響しません。PID 1 は、コンテナが実行するように構築されたプロセスです。
コンテナに入る方法は2つあり、これはその1つです。exec は、すでに存在するコンテナに接続します。docker compose run は、同じサービス定義から新しいコンテナを作成します。この違い1つから、このガイドのほぼすべての説明が導かれます。
Compose では -it が任意ですが、通常の docker では必須である理由
セッションの対話部分は、2 つのフラグで制御します。-i は標準入力を開いたままにするため、入力した内容がプロセスに渡ります。-t は TTY と呼ばれる疑似端末を割り当てるため、シェルがプロンプトを表示し、矢印キーを処理できます。通常の docker exec では、デフォルトで両方が無効です。そのため、これまでのすべての例で docker exec -it を指定しています。docker compose exec は両方を有効にするため、docker compose exec -it web bash と docker compose exec web bash は同じ動作になります。Compose でも -it を指定できるため、従来の操作方法をそのまま使えます。
TTY がないことは数秒で分かります。シェルは動作しますが、プロンプトが表示されず、Ctrl-C もプロセスに届きません。反対に、Compose に TTY を割り当てないよう指定する必要がある場合は、専用のフラグと、この後の専用セクションで説明します。
bash がないイメージへの対処
Alpine ベースのイメージで bash を指定すると、exec は次のように失敗します。
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH: unknownこれは exec の問題ではありません。コンテナの PATH に列挙されたディレクトリで bash が見つからなかったという意味です。シェルの場合、そのイメージにシェルが含まれていないことをほぼ意味します。Alpine は BusyBox を同梱し、/bin/sh として ash を提供しますが、bash は含みません。そのため、sh を指定します。
docker compose exec web sh-slim タグを含む Debian ベースおよび Ubuntu ベースのイメージには bash も含まれています。bash ではコマンド履歴と、より高機能な補完を利用できます。そのため、最初に bash を試し、失敗したら sh に切り替えます。sh は、ほぼすべての汎用イメージに存在します。
シェルをまったく含まないイメージもあります。Distroless イメージや FROM scratch で構築されたイメージには、意図的にアプリケーションのバイナリとそのライブラリだけが含まれます。存在しないシェルは攻撃に悪用できないためです。この場合、sh は同じメッセージで失敗し、試せる方法はありません。対処方法は 2 つあります。Google の distroless イメージには、BusyBox シェルを追加する :debug タグがあります。一時的にこのタグへ切り替えると、コンテナ内に入れます。もう 1 つは、対象コンテナの namespace 内で別のコンテナを起動する方法です。
CID=$(docker compose ps -q web)
docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshootこれで、netshoot のツールをアプリケーションのネットワークに向けて使用できます。そのため、curl localhost:8080 と ss -lntp は、アプリケーションの内部で実行した場合と同じように動作します。表示されるファイルシステムはアプリケーションのものではなく、netshoot のものです。プロセス namespace は共有されているため、/proc/1/root/ は対象プロセスのファイルシステムを指します。ただし、ls /proc/1/root/ ではカーネルの ptrace 権限チェックに合格する必要があります。両方のプロセスを root として実行するだけでは不十分です。このチェックでは、認証情報、ケイパビリティ、対象の dumpable 属性、セキュリティモジュールも考慮されます。dumpable の値が 1 以外の場合、呼び出し元が対象の user namespace で CAP_SYS_PTRACE を持っていない限り、アクセスは拒否されます。Docker はデフォルトで SYS_PTRACE を付与しません。docker run 行に --cap-add SYS_PTRACE を追加すると、認証情報と dumpability のチェックには対応できます。ただし、セキュリティモジュールによってアクセスが拒否される場合はあります。
サービスが実行されていない場合は、docker compose run --rm を使用します
exec は実行中のコンテナを必要とします。停止中のサービスを指定すると、拒否されます。
service "web" is not runningexec が自動的に起動することはありません。docker compose run なら起動できます。
docker compose run --rm web bashrun は web サービス定義から新しいコンテナを作成します。イメージ、環境変数、ボリューム、ネットワークは同じで、入力したコマンドでサービスのコマンドを置き換えます。--rm を指定すると、終了時にそのコンテナを削除します。--rm を省略すると、残ったコンテナが myproject-web-run-4f1c2b のような名前で蓄積します。docker compose ps -a で確認でき、docker compose rm でサービスの他の停止済みコンテナとともに削除できます。
run には、利用者を驚かせる動作が2つあります。--service-ports を追加するか、-p でポートを手動で割り当てない限り、サービスのポートは公開されません。これは意図した動作です。最初のコンテナがホストの 8080 番ポートを使用中に、2つ目のコンテナが同じポートをバインドすると、bind: address already in use で失敗するためです。また、シェルを表示する前に、サービスが depends_on に列挙しているすべてのサービスを起動します。そのため、内部を少し確認するだけでデータベースやキャッシュが起動することがあります。--no-deps を指定すると、この動作を無効にできます。
run はイメージの ENTRYPOINT を経由しますが、exec は経由しません。exec は既存のコンテナ内でコマンドを直接起動するため、エントリポイントスクリプトはそのコマンドを受け取りません。run では、bash がそのスクリプトへの引数として渡されます。公式イメージの多くはエントリポイントの最後に exec "$@" を記述しているため、引数がそのまま渡され、シェルを使用できます。引数を独自に解釈するスクリプトでは別の動作になります。その場合は、その実行に限ってエントリポイントを置き換えます。
docker compose run --rm --entrypoint sh webexec では動作するコマンドが run では異なる動作をする最も一般的な理由はこれです。command と entrypoint の分担を確認すると、イメージ設定のどちらを置き換えているかを理解できます。
exec と run の選び方
- exec には起動中のコンテナが必要です。run には必要ありません。また、run は依存関係にあるコンテナを起動する場合があります。
- exec では、実行中のプロセス一覧と現在のファイルを確認できます。アプリケーションが起動後に書き込んだ内容も含まれます。run ではイメージから新しい書き込み可能レイヤーが作成されます。ただし、named volume と bind mount では、サービスの既存データが引き続き公開されます。
- exec は entrypoint を実行しません。run は実行します。
--rmを指定しない限り、run はコンテナを残します。
実際に何が起きているかを確認する場合は、exec を使用します。同じ環境の使い捨てコピー、1 回限りのマイグレーションコマンド、または実際のサービスが exec を実行できるほど長く起動し続けない場合は、run --rm を使用します。
便利な exec フラグ: user、作業ディレクトリ、レプリカ
多くのイメージは root 以外のユーザーに切り替わるため、exec シェル内で診断ツールをインストールする場合は、ここで止まります。
E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)-u rootを指定すると、同じコンテナ内で root シェルを取得できます。
docker compose exec -u root web sh-w /srv/appは、そのコマンドに限って作業ディレクトリを設定します。-e KEY=valueは、サービスではなくセッションに環境変数を追加します。サービスが複数のレプリカを実行している場合、--index 2によって接続先のコンテナを選択します。マウントしたディレクトリのファイル所有権を調査している場合は、コンテナイメージ内の PUID と PGIDで、書き込み可能なユーザーを決めるのはユーザー名ではなく数値 ID である理由を確認できます。
データベースコンテナ内で psql または mysql シェルを起動する
クライアントはすでにデータベースイメージに含まれているため、ホストにクライアントを用意する必要はありません。ポートを公開する必要もありません。
docker compose exec db psql -U postgres -d app
docker compose exec db mariadb -u root -pPostgres イメージには psql、MySQL イメージには mysql、MariaDB イメージには mariadb が含まれています。コンテナ内から接続するため、Compose ファイルでデータベースのポートをまったく公開していない場合でも動作します。これは、Docker のデフォルトの bridge ネットワークでは、より安全な構成です。外部ホストから公開していないデータベースポートへ直接アクセスすることはできません。ただし、Docker ホストと同じネットワーク上のコンテナからはアクセスできます。
1 つの落とし穴で、問題の調査に半日かかることがあります。Docker がコマンドを受け取る前に、ホスト上のシェルが変数を展開します。そのため、その変数がコンテナ内にしか存在しない場合、-U "$POSTGRES_USER" は空の文字列を渡します。単一引用符とコンテナ内のシェルを使うと、正しい場所で変数が展開されます。
docker compose exec db sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"'ここで、コマンドを指定せずに docker compose run --rm db を実行しないでください。同じデータボリュームに対して 2 つ目の Postgres サーバーを起動するため、起動に失敗します。
FATAL: lock file "postmaster.pid" already existsロックファイルは、2 つのサーバーが 1 つのデータディレクトリへ書き込むとデータが破損するため、その役割を果たしています。データベースが起動している間に、実行中のコンテナへ exec で入ってください。データベースを Compose で運用するかどうかは別の判断です。Docker またはホストでデータベースを実行するでは、そのトレードオフを説明しています。
起動時にコンソールを必要とするサービス: stdin_open と tty
手動で開くシェルには exec と run を使用します。メインプロセスが本質的に対話型であるサービスでは、compose ファイルに次の2つのキーが必要です。
services:
console:
image: python:3.12-slim
command: python
stdin_open: true
tty: truestdin_open: true は docker run -i、tty: true は docker run -t です。これらがない場合、コンテナは起動直後にコード 0 で終了し、docker compose ps -a には Exited (0) と表示されます。クラッシュしたわけではありません。python は stdin に端末がないと直ちに EOF を読み取り、正常に終了します。誰も入力していないプログラムとしては、これが正しい動作です。
両方のキーを設定したら、実行中のプロセスに接続します。
docker attach $(docker compose ps -q console)Ctrl-P に続けて Ctrl-Q を押すと、プロセスを実行したまま切断できます。このシーケンスは、コンテナで TTY と stdin の両方が開いている場合にのみ機能します。一方、Ctrl-C は PID 1 に割り込み(SIGINT)を送信します。Linux では PID 1 にデフォルトのシグナル処理がないため、サービスが停止するのは、プログラムが SIGINT を受信して終了するよう実装されている場合だけです。そのため、切断する目的で Ctrl-C を使用しないでください。
通常のサービスでは、両方のキーを無効にします。Web サーバーが stdin を読み取ることはありません。また、tty: true により、多くのプログラムは人が出力を見ていると判断して、カラー出力と行バッファリングに切り替えます。その結果、docker compose logs にエスケープコードが大量に記録されます。
cron と CI でスクリプトからの exec が失敗する理由: -T フラグ
ターミナルで動作する exec コマンドでも、スクリプト、cron ジョブ、継続的インテグレーション (CI) runner、またはパイプから実行すると失敗することがあります。
the input device is not a TTYCompose は自身の出力先がターミナルの場合、疑似端末を要求します。標準入力もターミナルでない場合、この要求はコマンドの実行前に失敗します。最近の Docker CLI のソースでは、同じ失敗が cannot attach stdin to a TTY-enabled container because stdin is not a terminal と表現されています。現在の Compose は、出力がリダイレクトまたはパイプされている場合、通常 cron 実行時のように、要求を自動的に省略します。以前のリリースでは常に要求するものがあり、現在でも自分のプロンプトで cat dump.sql | docker compose exec db psql と入力すると、この問題が発生します。-T を指定すると、どのような場合でも要求を無効にできます。検出処理に依存せず、スクリプトではこれを指定してください。
0 3 * * * docker compose -f /srv/app/compose.yaml exec -T db pg_dump -U postgres -Fc app > /srv/backups/app.dump-T には別の理由でも意味があります。TTY は出力時にバイトストリームを書き換えるため、TTY を経由した圧縮ダンプは破損した状態で到着します。リダイレクトまたはパイプする出力では、-T を明示的に指定してください。
cron では、さらに 2 点に注意が必要です。cron はホームディレクトリからジョブを実行します。そこに compose ファイルがない場合、Compose は no configuration file provided: not found で停止するため、絶対パスを指定して -f を渡してください。また、exec は実行したコマンドの終了コードを返します。そのため、pg_dump が失敗すると、set -e の下でスクリプトも失敗します。空のバックアップを作成して成功を報告することはありません。その他の日常的に使うコマンドは、スクリプトのそばに置いておくと便利な Compose コマンドチートシート にまとめています。
コンテナ内で行った変更が消える理由
exec でツールをインストールし、設定ファイルを編集して問題を修正しても、1 週間後には修正が消えていることがあります。これは、コンテナの書き込み可能レイヤーが設計どおりに動作しているためです。docker compose up -d は、イメージタグまたはサービス定義を変更すると古いコンテナを削除し、イメージから新しいコンテナを作成します。そのため、手動で行った編集は古いコンテナとともに失われます。
docker compose restart は動作が異なります。同じコンテナを停止して再起動するため、手動で行った編集は保持されます。そのため、手動の修正が数週間維持された後、関係のない更新時に消えることがあります。名前付きボリュームと bind mount は、どちらの操作でも保持されます。データがコンテナの外部に保存されるためです。保持するデータにどちらを選ぶべきかは、bind mount と名前付きボリュームで説明しています。
そのため、exec シェルは内容の確認とテストを行う場所として扱ってください。修正方法が分かったら、変更が保持される場所に記述します。パッケージは Dockerfile に、設定は compose ファイルに記述します。その後、docker compose up -d で適用し、別の exec を実行して、新しいコンテナに実際に反映されていることを確認してください。
FAQ
docker compose exec と docker compose run の違いは何ですか?
exec は、すでに起動しているコンテナ内でメインプロセスとは別にコマンドを実行します。イメージの entrypoint はスキップします。run は、同じサービス定義とイメージ、環境変数、ボリューム、ネットワークを使って新しいコンテナを作成し、コマンドを entrypoint に渡して実行します。先に depends_on サービスも起動します。run では、--service-ports または -p のマッピングを追加しない限り、サービスのポートは公開されません。起動中のサービスを調査する場合は exec を使用します。サービスが停止している場合や別のコンテナが必要な場合は run --rm を使用します。ただし、名前付きボリュームと bind mount は共有されることに注意してください。
docker compose exec でサービスが起動していないと表示されるのはなぜですか?
exec は既存のコンテナに接続するだけで、コンテナを作成できません。そのため、サービスが停止またはクラッシュしていると service "web" is not running になります。停止したコンテナを Exited (1) のようなステータス付きで一覧表示する docker compose ps -a を確認し、停止理由を docker compose logs web で確認してください。シェルを起動するだけなら docker compose run --rm --entrypoint sh web を実行します。これは同じサービス定義から新しいコンテナを作成しますが、問題のある起動コマンドは実行しません。
イメージに bash がない場合、シェルを開くにはどうすればよいですか?
docker compose exec web bash が exec: "bash": executable file not found in $PATH で失敗する場合、コンテナの PATH にあるディレクトリ内に bash が見つかりません。通常は、イメージに bash が含まれていないことを意味します。Alpine ベースのイメージでは一般的です。BusyBox が /bin/sh を提供するため、docker compose exec web sh を使用してください。シェルのないイメージでは exec でシェルを開けませんが、イメージに含まれる実行ファイルは実行できます。公開元が提供している場合は、イメージの :debug タグに切り替えてください。または、docker run --rm -it --network "container:$CID" --pid "container:$CID" nicolaka/netshoot を使用して対象の namespace 内にデバッグ用コンテナを起動します。ここで $CID は docker compose ps -q web から取得します。
cron で exec コマンドを実行すると「入力デバイスは TTY ではありません」と表示されるのはなぜですか?
docker compose exec は、出力先が端末の場合に pseudo terminal を要求します。stdin も端末でない場合、この要求は失敗します。現在の Compose は、通常 cron で発生するように出力がリダイレクトされている場合、自動的に要求を省略します。ただし、以前のリリースでは常に要求していました。また、対話シェルから exec に入力をパイプすると、現在でもこのエラーが発生します。-T を追加して無効にします: docker compose exec -T db pg_dump -U postgres app。リダイレクトまたはパイプした出力では -T も使用してください。TTY によってバイトストリームが変化し、バイナリダンプが破損するためです。cron では、compose ファイルの絶対パスを -f とともに指定してください。指定しない場合、Compose は no configuration file provided: not found で終了します。
exec でコンテナ内に加えた変更は、再起動後も残りますか?
同じコンテナを再利用する docker compose restart の後は残ります。イメージまたは設定を変更した後の docker compose up -d では、イメージからコンテナが再作成され、書き込み可能レイヤーが破棄されるため、変更は失われます。名前付きボリュームまたは bind mount に書き込んだデータはコンテナの外部に保存されるため、どちらの場合も残ります。exec では診断用の変更だけを行い、永続的な内容は Dockerfile または compose ファイルに記述してください。