Docker Composeのcommandとentrypointの違いと使い分け
Docker ComposeではENTRYPOINTが実行するプログラム、commandが引数です。4つの上書きパターンと、entrypoint設定でイメージのCMDが破棄される仕様を確認します。
Docker Compose の command と entrypoint を 1 つのルールで理解する
Docker Compose では、entrypoint: が実行するプログラムを指定し、command: がそのプログラムに渡す引数を指定します。コンテナのプロセスは、entrypoint のリストの末尾に command のリストを追加したものです。このページの他の動作は、すべてこの 1 文から導けます。
この 2 つのキーは、Dockerfile の 2 つの命令に対応します。entrypoint: はイメージの ENTRYPOINT を置き換えます。command: はイメージの CMD を置き換えます。これらは独立していません。ここで混乱が生じます。entrypoint: を設定すると、イメージの CMD も破棄されます。Compose 仕様には、この動作が明記されています。entrypoint が null でない場合、Compose はイメージのデフォルトコマンドを無視します。
イメージがすでに宣言している内容を確認する
何かを上書きする前に、イメージに含まれる設定を確認します。
docker image inspect --format '{{json .Config.Entrypoint}}' postgres:16
docker image inspect --format '{{json .Config.Cmd}}' postgres:16["docker-entrypoint.sh"] と ["postgres"] が表示されるため、コンテナは docker-entrypoint.sh postgres を実行します。このスクリプトは初回起動時にデータディレクトリを作成し、POSTGRES_* 変数を読み込み、権限を postgres ユーザーに下げ、最後に渡された引数を exec で実行します。どの部分を変更するかを把握することが、判断の要点です。データベースにフラグを渡すには、command: を置き換えます。entrypoint: を置き換えると、この初期設定は一切実行されません。
4 つの組み合わせを小さなイメージで確認する
起動時に渡された引数の一覧を表示することだけを目的とするイメージを作成します。
FROM alpine:3.20
ENTRYPOINT ["/bin/echo", "ep"]
CMD ["cmd"]docker build -t argdemo .services:
demo:
image: argdemo編集するたびに docker compose up を実行し、ログに出力された 1 行を確認します。
- どちらのキーも未設定。 プロセスは
/bin/echo ep cmdで、ログにはep cmdが表示されます。 command: ["cmd2"]のみ。 プロセスは/bin/echo ep cmd2です。entrypoint は変更されず、引数だけが変わります。entrypoint: ["/bin/echo", "ep2"]のみ。 プロセスは/bin/echo ep2で、ログにはep2が表示されます。イメージ由来のcmdはなくなり、警告も表示されません。- 両方のキーを設定。 プロセスは
/bin/echo ep2 cmd2です。引数リスト全体を制御できるのはこの場合だけです。
entrypoint を設定するとイメージの CMD が消える理由
イメージの CMD は、そのイメージの ENTRYPOINT に渡すデフォルトの引数リストとして記述されています。entrypoint を置き換えると、それらの引数は実行されなくなったプログラムに属することになります。そのため Compose は、イメージの作成者が意図していないコマンドラインを構成せず、引数を破棄します。docker run --entrypoint も同じように動作します。これは Compose 固有の問題ではなく、Docker の仕様です。
この結果は明確です。nginx:1.27 は ENTRYPOINT ["/docker-entrypoint.sh"] と CMD ["nginx", "-g", "daemon off;"] を宣言しています。entrypoint: /custom-init.sh を設定すると、スクリプトは空の引数リストで開始します。通常の exec "$@" で終わるスクリプトでは、exec する対象がありません。そのため exec は何もせず、スクリプトは最終行まで進み、コンテナはエラーメッセージを出さずに終了コード 0 で終了します。引数は自分で戻してください。
services:
web:
image: nginx:1.27
entrypoint: /custom-init.sh
command: ["nginx", "-g", "daemon off;"]覚えておくルールは次のとおりです。entrypoint: を設定する場合は、同じ編集で command: に何を指定するかも決めてください。
Exec 形式と shell 形式、および Compose との違い
Dockerfile では 2 種類の構文を使用できます。CMD ["nginx", "-g", "daemon off;"] は exec 形式です。バイナリが shell を介さずに直接実行されます。CMD nginx -g "daemon off;" は shell 形式です。Docker はこれを /bin/sh -c 'nginx -g "daemon off;"' に書き換えるため、最初に shell が実行され、プログラムはその子プロセスになります。
Compose はこの規則を引き継ぎません。ここが混乱しやすい点です。command: の文字列は引数に分割され、/bin/sh -c のラッパーなしで直接実行されます。Compose のリファレンスにも明記されています。command フィールドは、イメージで定義された SHELL コンテキスト内では実行されません。そのため、shell の機能が必要な場合は、自分で shell を呼び出す必要があります。
そのため、command: echo "hello $$HOSTNAME" はリテラルテキスト hello $HOSTNAME を出力します。文字列を解釈する shell が存在しないため、何も展開されません。shell を使用する場合は、shell を明示的に呼び出します。
services:
demo:
image: alpine:3.20
command: /bin/sh -c 'echo "hello $$HOSTNAME"'シグナル、PID 1、正常な docker compose down
docker compose stop と docker compose down は、各コンテナ内の PID 1 にコンテナの停止シグナルを送信します。そのシグナルは、イメージの STOPSIGNAL またはサービスの stop_signal: で別のシグナルが設定されていない限り、SIGTERM です。Compose は最大 stop_grace_period 待機し、コンテナがまだ実行中の場合に限って SIGKILL を送信します。デフォルトの猶予期間は 10 秒です。
Linux では、PID 1 は特別な扱いになります。カーネルはシグナルのデフォルト動作を PID 1 に適用しません。そのため、SIGTERM ハンドラーを登録していないプロセスは、PID 1 として動作するとき SIGTERM を単に無視します。プロセスは猶予期間全体にわたって動作し続け、その後強制終了されます。この場合、開いている接続やコミット前のトランザクションが切断されます。
プログラムの前段にシェルを置くと、この問題が起きやすくなります。シェルが PID 1 になり、多くのシェルは子プロセスへシグナルを転送しないためです。一部のシェルは -c 文字列内の最後のコマンドで自身を置き換えるため、プログラムが PID 1 になる場合もあります。これはシェルと正確な文字列によって異なるため、推測してはいけません。次のように確認してください。
docker compose exec -T web cat /proc/1/cmdline | tr '\0' ' '; echoPID 1 がプログラム名ではなく /bin/sh -c ... と表示される場合は、2 つの対処方法があります。イメージで exec 形式を使用するか、シェルを残したまま exec でプロセスを引き渡します。
services:
web:
image: myapp:1.4
command: /bin/sh -c 'exec myapp --config /etc/myapp.toml'exec は子プロセスを fork する代わりに、シェルプロセスをプログラムで置き換えます。そのため、プログラムが PID 1 を引き継ぎ、シグナルを受信します。
子プロセスを生成しても回収しないプログラムがあります。この場合、PID 1 は子プロセスの回収も担うため、ゾンビプロセスが残ります。Compose には、そのためのスイッチがあります。
services:
web:
image: myapp:1.4
init: true
stop_grace_period: 30sinit: true は小さな init プロセスを PID 1 として実行します。このプロセスは、シグナルをプログラムへ転送し、子プロセスを回収します。stop_grace_period を指定すると、実際に時間のかかる正常終了のために、より長い時間を確保できます。プログラムが別のシグナルを想定している場合は、stop_signal: SIGQUIT で Compose が送信するシグナルを変更します。イメージがすでに要求しているシグナルは docker image inspect --format '{{.Config.StopSignal}}' nginx:1.27 で確認できます。
docker compose down がサービスごとに必ず 10 秒かかるスタックでは、SIGTERM を処理しているものがないことを示しています。ツールの問題だと判断する前に修正してください。各サブコマンドが削除する対象については、docker compose down と stop の違いを参照してください。
同じ exec 形式と shell 形式の違いは、もう 1 か所にも現れます。test: ["CMD", "curl", "-f", "http://localhost/"] として記述した healthcheck はバイナリを直接実行します。一方、test: ["CMD-SHELL", "curl -f http://localhost/ || exit 1"] はシェル経由で実行されるため、|| が意味を持ちます。このフィールドの残りの内容については、正しく失敗を報告する Compose healthcheck の記述を参照してください。
公式イメージにフラグを追加する
ここが、多くの読者が知りたい内容です。postgres に追加のフラグを 1 つ指定しつつ、初期化スクリプトは変更したくありません。
services:
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- pgdata:/var/lib/postgresql/data
command: postgres -c max_connections=200 -c shared_buffers=256MB
volumes:
pgdata:変更したのは command: だけなので、docker-entrypoint.sh は引き続き実行され、指定した内容をそのまま exec します。思い込みで判断せず、結果を確認してください。
docker compose up -d db
docker compose exec -T db psql -U postgres -c 'show max_connections;'出力には 200 と表示されます。100 と表示される場合は、docker compose config を実行し、想定した command がマージ後の出力に含まれていることを確認してください。Compose はオーバーライドファイルをマージするとき、command を追加するのではなく、全体を置き換えます。そのため、別のファイルでも command: を設定すると、後の設定が何も通知されずに優先されます。
上記の ${POSTGRES_PASSWORD} は、コンテナが作成される前に、Compose がホスト上の .env ファイルから展開します。その値を安全に保存できる場所については、Compose の環境ファイルと Secret を参照してください。
docker compose run で一度だけマイグレーションを実行する
docker compose run は、同じサービス定義から新しいコンテナを作成し、サービス名の後に入力した内容でコマンドを置き換えます。イメージの entrypoint は引き続き実行されるため、長時間稼働するコンテナとまったく同じ状態に準備されます。
docker compose run --rm app python manage.py migrate--rmは、コマンドの終了時にコンテナを削除します。これを指定しない場合、実行するたびに停止済みコンテナが残り、docker compose ps -aで確認できます。- ポートは公開されません。
runコンテナは--service-portsを追加しない限り、サービスのports:を無視するため、すでに起動しているサービスと競合しません。 - 依存関係にあるサービスが先に起動します。
depends_onに指定されたものはコマンドの実行前に起動し、--no-depsはそれを省略します。 - コンテナには
myproject-app-run-9f2c1aのような生成された名前が付くため、サービスコンテナと名前が競合することはありません。
entrypoint も置き換えるには、専用のフラグを使用します。
docker compose run --rm --entrypoint /bin/sh app -c 'python manage.py migrate'結果として得られる引数リストは /bin/sh -c 'python manage.py migrate' です。サービス名の後に指定した語句は、引き続きコマンドとして扱われるためです。docker compose exec はもう一方のツールで、動作が異なります。すでに起動しているコンテナ内でプロセスを実行し、entrypoint: と command: は完全に無視します。新しいコンテナが必要なタスクには run を使用し、実行中のコンテナの内部を確認するには exec を使用します。Compose コマンド早見表では、その他のサブコマンドも並べて比較できます。
コンテナが直ちに終了するのはなぜですか?
まず終了コードを確認してください。原因をすばやく絞り込めます。
docker compose ps -a
docker compose logs app出力がなく、終了コードが 0。 コマンドは実行され、正常に終了しています。最も一般的な原因は、entrypoint: による上書きでイメージの CMD も失われたことです。その結果、エントリポイントが空の引数リストで実行され、引き渡す処理がなくなります。
permission denied で終わるエラー。 イメージ内でスクリプトに実行権限がありません。通常は、リポジトリ内のファイルに実行権限が設定されていなかったことが原因です。ビルド時に COPY --chmod=0755 entrypoint.sh /entrypoint.sh で設定してください。
イメージ内には明らかに存在するファイルについて、no such file or directory で終わるエラー。 スクリプトの改行コードが Windows 形式です。そのため、先頭行は #!/bin/sh に復帰文字バイトが付いたものとして解釈されます。カーネルはそのバイトを含む名前のインタープリターを探すため、見つけられません。dos2unix entrypoint.sh を実行し、再発しないように * text eol=lf を .gitattributes に追加してください。
executable file not found in $PATH。 command: に指定したプログラムが、コンテナの PATH に含まれるどのディレクトリにもありません。イメージにそのプログラムが含まれていないか、PATH の外部にインストールされています(その場合は完全なパスを指定します)。または、実在するプログラムだけを指定できる場所に cd のようなシェル組み込みコマンドを記述しています。
エントリポイントが失敗するイメージに shell で入る
エントリポイントが調査前に終了する場合は、エントリポイントを置き換えます。
docker compose run --rm --entrypoint /bin/sh appstat /bin/sh: no such file or directory で失敗する場合、イメージに /bin/sh がありません。Distroless ベースや scratch ベースのイメージには、shell 自体が含まれていないことがあります。エントリポイントを起動せずに、外部からファイルシステムを読み取ることはできます。
docker create --name probe myapp:1.4
docker export probe | tar -tv | head -40
docker rm probe繰り返し attach できるようにコンテナを起動したままにする場合は、終了しないプロセス上で待機させます。これを、コミットしない override ファイルに記述します。
services:
app:
entrypoint: ["tail", "-f", "/dev/null"]
command: []command: [] は必須ではありません。entrypoint: を設定すると、イメージの CMD はすでに解除されるためです。ただし、記述しておけば、次にファイルを読む人に意図が伝わります。起動して中に入ります。
docker compose -f compose.yaml -f compose.debug.yaml up -d app
docker compose exec app /bin/sh次に、実際のエントリポイントを手動で実行し、どこで停止するかを確認します。これにより、半秒前に終了したコンテナ内ではなく、端末上でエラーメッセージを確認できます。まだ最初の stack を構築中であれば、VPS 上で最初の Compose stack を構築するで、ここで前提としているファイル構成を説明しています。
FAQ
コンテナで docker compose up を実行すると、すぐに終了するのはなぜですか?
終了コードを確認するには docker compose ps -a を使用します。出力がなく終了コードが 0 の場合、通常はサービスに entrypoint: を設定したため、イメージの CMD もクリアされています。その結果、entrypoint が空の引数リストで実行され、終了します。command: で引数を戻してください。permission denied で終わるエラーは、entrypoint スクリプトに実行権限がないことを示します。存在するファイルに対するエラーが no such file or directory で終わる場合、そのスクリプトは Windows の改行コードを使用しています。そのため、shebang 行が指定するインタープリターが見つかりません。
Compose で entrypoint を設定すると、イメージの CMD は削除されますか?
はい。entrypoint が null でない場合、Compose はイメージで宣言されたデフォルトコマンドを無視します。これは文書化された動作であり、docker run --entrypoint と一致します。イメージの CMD は、そのイメージの ENTRYPOINT に渡す引数として記述されるためです。entrypoint を置き換えると、元の引数は渡し先を失います。新しい entrypoint に引数が必要な場合は、同じサービスで command: を設定してください。
Compose の command に指定した文字列は、シェル経由で実行されますか?
いいえ。Dockerfile の CMD とは異なり、Compose の command: に指定した文字列は引数に分割され、/bin/sh -c のラッパーなしで直接実行されます。そのため、Compose がコンテナ内でシェルを起動して $VARIABLE を展開することはありません。シェルが必要な場合は、command: /bin/sh -c 'echo "hello $$HOSTNAME"' のように自分でシェルを呼び出してください。$$ の二重指定はドル記号をエスケープします。これにより、Compose はホスト上で展開せず、そのままコンテナに渡します。
1 つのコンテナに対する docker compose down に 10 秒かかるのはなぜですか?
Compose は PID 1 に停止シグナルを送信します。PID 1 は、イメージまたはサービスで別の値が設定されていない限り SIGTERM です。続いて最大 stop_grace_period(デフォルトは 10 秒)待機し、コンテナがまだ実行中であれば SIGKILL を送信します。カーネルは PID 1 にデフォルトのシグナル動作を適用しません。そのため、SIGTERM ハンドラーを持たないプログラムはシグナルを無視し、常に待機時間を使い切ります。docker compose exec -T app cat /proc/1/cmdline | tr '\0' ' ' で PID 1 の実体を確認してください。シェルの場合は、イメージを exec 形式に変更するか、シェル文字列内に exec を記述してください。プロセスが子プロセスを生成しても回収しない場合は、サービスに init: true を設定してください。