Docker Compose実運用コマンドチートシート

実際に使用する Compose コマンド

Docker Compose には40以上のサブコマンドがあります。サーバーの日常運用で使うのは、そのうち約12個です。このページでは、作業内容ごとにコマンドを分類し、それぞれの用途を簡潔に説明します。コマンドに潜む注意点については、詳しい解説も示します。

ここではすべて Compose V2 を使用します。つまり、スペースを含む docker compose です。従来の docker-compose スクリプトではありません。V2 は Docker Engine とともにインストールされる Go 製プラグインです。V1 は現在のパッケージから削除されているため、2026年7月時点で新規に用意した Ubuntu に docker-compose: command not found が存在するのは、故障ではなく想定された状態です。docker compose version で確認してください。何も表示されない場合は、docker-compose-plugin パッケージをインストールしてください。

以下の各コマンドは、compose.yaml を置いたディレクトリから実行します。Compose はそのディレクトリ名からプロジェクト名を取得し、そこを基準にファイルを探すためです。同じコマンドを1つ上のディレクトリで実行すると、Compose は no configuration file provided: not found で停止します。ファイル形式自体が初めての場合は、まず VPS で初めて Compose ファイルを作成する方法 を確認し、その後ここに戻って各コマンドを参照してください。

ライフサイクル: 入力する4つのコマンドと、コンテナを削除するコマンド

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -dはネットワークを作成し、コンテナを作成して起動した後、戻ります。コンテナが作成された時点ですぐに戻るため、続けてcurlプローブを実行するデプロイスクリプトは、初回実行時に失敗することがよくあります。up -d --waitは、healthcheckを宣言しているすべてのサービスがhealthyを報告するまでブロックし、いずれかがhealthyにならない場合は0以外の終了ステータスで終了します。このフラグの有効性は、その背後にあるチェックの内容に左右されます。そのため、自動化で利用する前に、Composeが信頼できるhealthcheckを作成してください。

stopはコンテナを停止した後も保持します。そのため、startを実行すると、同じ書き込み可能レイヤーを持つ同じコンテナが再び起動します。downはコンテナを停止し、その後コンテナとプロジェクトネットワークを削除します。コンテナ内でvolumeの外部に書き込まれたデータは、すべて失われます。これはComposeで最も影響の大きい誤解です。downとstopの完全な違いでは、どのような場面で問題になるかを説明しています。

restartはreloadではありません。既存の設定を使って同じコンテナを停止・起動するだけなので、変更した環境変数、新しいimage tag、編集したポートマッピングはまったく反映されません。ファイルの変更を反映するには、再度up -dを実行します。Composeは各サービスと実行中のコンテナを比較し、設定が変更されたコンテナだけを再作成します。

変更を適用する: 再作成、pull、または再ビルド

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

設定に変更がない場合、up -d は何も実行しません。そのため、繰り返し安全に実行できます。--force-recreate はこの比較を無視し、設定が同一でもすべてのコンテナを置き換えます。コンテナ内に残った不審な状態を最も早く解消できる方法です。

イメージの更新に 2 つのコマンドが必要なのは、それぞれの役割が異なるためです。pull は、ファイルに記載された各タグの最新イメージをダウンロードします。続いて up -d が、サービスのイメージ ID と実行中のコンテナのイメージ ID が一致しないことを検出し、コンテナを再作成します。pull を省略すると、up -d は先月の latest をエラーなしで実行し続けます。逆に、複数サービスのスタックでは、すべてのサービスについて一度に latest を pull すると、10 秒前まで正常に動作していたアプリケーションが壊れるおそれがあります。そのため、セルフホストの AFFiNE ワークスペースでは、4 つのイメージタグをそれぞれ固定しています。タグを固定すると、アップグレードはタグを意図的に編集してから、同じ pull と再作成を実行する手順になります。起動時にデータベースを移行するスタックでは、どちらのコマンドを実行する前にもダンプを用意します。セルフホストの Chatwoot サポートデスクでは、バージョンを更新するたびにこの手順を実施しています。

build は、image: ではなく build: セクションを宣言するサービスに適用します。up -d --build はビルドと起動を1つの手順で実行します。コードを変更している間は、通常この手順を繰り返します。キャッシュされたレイヤーが明らかに古い場合に限り --no-cache を使用してください。これはすべてのレイヤーを最初から再ビルドするためです。レジストリのイメージではなく、checkout した git tag からスタックをデプロイする場合も、同じビルド手順が更新方法になります。自己ホスト型 openGym ワークアウトトラッカーは、この方法で固定したバージョンを次のバージョンへ更新します。

実行中の状態を確認する

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

psは実行中のコンテナだけを一覧表示します。起動中にクラッシュしたサービスは、-aを追加するまでここには表示されません。そのため、psには表示されないコンテナが、ps -aではExited (1)として表示されるのは、起動失敗時の通常の状態です。終了コードを確認してから、ログを確認します。

logs -fはすべてのサービスを同時に追跡し、各行の先頭にサービス名を付けます。サービス間の通信やイベントの順序を確認する場合に適した表示です。サービス名を指定すると対象を絞れます。1 か月間起動し続けているコンテナでは、--tail=100も重要です。デフォルトでは履歴全体が表示され、端末が大量の出力で埋まるためです。--since 15mを使うと、通常確認したい内容である、直前に実行した再起動中に何が起きたかを確認できます。

topは各コンテナ内のプロセスを一覧表示します。これにより、「コンテナが実行中である」ことと「コンテナ内のプロセスが実行中である」ことを区別できます。lsを使うと現在のディレクトリを離れ、ホスト上のすべての Compose プロジェクトとその状態を一覧表示できます。3 か月前に起動したスタックも見つけられます。

サービス内でシェルを起動する

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec は、すでに起動しているコンテナ内でコマンドを実行します。run は同じサービス定義から新しいコンテナを起動します。サービスが exec できるほど長く起動し続けない場合は、こちらが必要です。必ず run と --rm を組み合わせてください。これを付けないと、実行するたびに停止済みコンテナが残ります。停止済みコンテナが蓄積すると、docker compose ps -a が読みづらくなります。

bash の前に sh を試してください。Alpine ベースのイメージには bash が含まれていないため、失敗時には exec: "bash": executable file not found in $PATH と表示されます。run に --no-deps を追加すると、サービスの依存関係を起動せずに済みます。これにより、簡単な設定確認のためにデータベース全体を起動する事態を避けられます。

run --rm web env は、.env ファイル、environment: ブロック、シェル変数をすべてマージした後に、サービスが実際に取得した環境を確認する最も速い方法です。値が誤っている場合は、通常、マージ順序が原因です。Compose が env ファイルと Secret を解決する方法では、どのソースが優先されるかを説明しています。

ネットワーク、ポート、名前解決

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose はすべてのサービスを 1 つのプロジェクトネットワークに接続し、各サービス名をそのネットワーク上の DNS 名として扱います。web 内で getent hosts db を実行すると、名前解決に成功した場合はコンテナの IP が表示され、失敗した場合は何も表示されません。そのため、「これらのコンテナは相互に通信できるか」を 2 秒で確認できます。名前解決はできても接続が拒否される場合、db 内のプロセスは 0.0.0.0 ではなく 127.0.0.1 に bind されています。そのため、別のコンテナからのパケットを受け付けません。docker run で起動したコンテナや独立した stack など、プロジェクトの外部で起動したコンテナが jellyfin のような名前をまったく解決できないのも、同じネットワーク境界で説明できます。これは、Jellyfin ライブラリ用の Halcyon フロントエンドが指定先のサーバーに接続できない場合に、最初に確認すべき点です。この仕組みの詳細は、Compose のネットワークとサービス DNS の仕組みを参照してください。

port web 80 は、コンテナのポートが公開されているホストアドレスとポートを表示します。マッピング元が変数の場合でも、推測する必要がありません。ポートを公開すると、Docker が管理するファイアウォールルールも追加されます。このルールはユーザー自身のルールより先に適用されるため、非公開のつもりだったサービスがインターネットからアクセス可能になることがあります。このケースについては、公開された Docker ポートが ufw を迂回する理由で説明しています。これらのポートを公開せず、代わりにプロジェクトネットワーク上で認証機能を持つ単一のプロキシをサービスの前段に置く構成のほうが安全です。Authentik をシングルサインオン層として運用するでは、この構成を実現します。

ボリュームとデータ

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes は、プロジェクトで宣言されている名前付きボリュームを 1 行に 1 つずつ表示します。この一覧がバックアップ対象です。ボリュームに失うと復元できないデータが含まれている場合は、一覧だけでなく正確なバックアップコマンドも重要です。そのため、PhotoPrism と Immich の比較では、各フォトサーバーに必要なダンプおよびコピーコマンドを詳しく説明しています。cp はシェルを開かずに、コンテナとの間でファイルをコピーします。コンテナ側には service:path 形式を使用します。

down -v は、コンテナとともに名前付きボリュームも削除します。テスト用スタックを解体する場合には適切なコマンドですが、必要なデータを保持している環境では使用すべきではありません。確認を求められず、取り消しもできないためです。バインドマウントはホストのファイルシステム上に存在するため、この操作の影響を受けません。この影響範囲の違いが、バインドマウントと名前付きボリュームを意図的に使い分ける理由の 1 つです。

データを失わずにディスク容量を確保するクリーンアップ

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans は、プロジェクトに属しているもののファイルには記載されなくなったコンテナを削除します。サービス名を変更した後は、まさにこの状態になります。これを実行しないと、そのコンテナは動作し続け、docker compose ps からは見えません。

docker system df は、削除する前にディスク使用量の内訳を表示します。イメージ、コンテナ、ローカルボリューム、ビルドキャッシュごとに分類し、再利用可能な容量も示します。image prune -a は、タグから参照されていないすべてのイメージを削除します。大容量イメージを複数のバージョンで取得しているサーバーでは、通常これが最も大きな効果をもたらします。builder prune はビルドキャッシュを削除します。独自のイメージをビルドするサーバーでは、ビルドキャッシュが気付かないうちに増加します。

これらの操作は、名前付きボリュームには影響しません。名前付きボリュームに影響するのは docker volume prune と docker compose down -v だけです。

変更による影響が出る前にファイルを確認する

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet は成功時に何も出力せずに検証するため、デプロイ前の手順や git hook に組み込めます。単独の config は、変数の展開と上書きファイルの適用が想定どおりか確認できるよう、マージと補間が完了したファイルを出力します。未設定の変数は、警告 The "X" variable is not set. Defaulting to a blank string. とともに空の値として表示されます。

--dry-run はサブコマンドのフラグではなくグローバルフラグであるため、up より前に指定します。Compose が実行するすべての操作を表示し、状態は変更しません。重要なスタックで down を実行する前に、この 30 秒の確認を行う価値があります。

ファイル、プロファイル、プロジェクトをまたいだ運用

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

複数の -f フラグは指定順にマージされ、後のファイルがキー単位で前のファイルを上書きします。これは、1 つのベースファイルに小さな本番用の上書き設定を重ねる標準的な方法です。ただし、リストとマップではルールが異なるため、予期しない結果を調査する前に、Compose が複数のファイルをマージする方法を確認してください。

--profile は、そのプロファイルが付いたサービスを、プロファイルが付いていないサービスとともに起動します。これにより、通常の up にデバッグ用ツールを含めずに済みます。-p はプロジェクト名を設定するため、1 つのスタックを 2 つ起動し、それぞれに別のネットワーク名とボリューム名を割り当てて並行稼働させられます。再起動後にスタックを復元する処理は、手動で入力するコマンドではありません。自動的に実行される unit を設定します。設定方法は、起動時に Compose スタックを開始する方法で説明しています。

FAQ

ハイフン付きの docker-compose に取って代わったものは何ですか？

Compose V2 です。スペースを入れた docker compose として実行します。これは Docker Engine に同梱されるプラグインで、V1 の Python ツールは現在のパッケージには含まれていません。スペース形式を実行しても何も表示されない場合は、ディストリビューション用の docker-compose-plugin パッケージをインストールしてください。エイリアスを追加するのではなく、古いスクリプトをスペース形式に更新してください。V2 には V1 にはなかったフラグがあるためです。

docker compose restart で設定変更が反映されないのはなぜですか？

restart は、既存のコンテナを、作成時の設定を使って停止・起動します。compose.yaml を再読み込みすることはありません。環境変数、ポート、ボリューム、イメージタグを変更した場合は docker compose up -d が必要です。これは各サービスを実行中のコンテナと比較し、差異があるコンテナを再作成します。ファイルの内容に変更がなくても置き換える場合は --force-recreate を追加してください。

サービスを新しいイメージに更新するにはどうすればよいですか？

まず docker compose pull を実行し、続けて docker compose up -d を実行します。pull により、ファイル内の各タグに対応する最新のイメージが取得されます。up -d は、イメージ ID がコンテナと一致しなくなったサービスを再作成します。up -d だけを実行すると、ディスク上にすでにあるイメージが再利用されます。そのため、latest に固定したスタックが、エラーを表示せず数か月前のビルドのままになることがあります。

稼働中のサーバーで安全に実行できるクリーンアップコマンドはどれですか？

docker system df、docker image prune -a、docker builder prune はイメージとキャッシュだけを削除します。そのため、実行中のサービスは動作を継続し、名前付きボリュームも変更されません。危険なのは docker compose down -v と docker volume prune の組み合わせです。これらは確認なしで名前付きボリュームを削除します。最初に docker compose config --volumes を実行し、何が影響を受けるか確認してください。

スタック全体を起動せずに、1 つのコマンドを実行できますか？

はい。docker compose run --rm --no-deps web sh は web のサービス定義から単一のコンテナを起動し、依存関係をスキップします。終了時にはコンテナを削除します。コンテナがすでに実行中の場合は exec を使用してください。exec は実行中のプロセスに接続し、サービスの実際の状態を表示するためです。