docker-composeとは？複数コンテナをymlで定義し一括管理する仕組みを解説

docker-composeは、複数のコンテナで構成されるアプリケーションを1つのYAMLファイル（compose.yaml）に宣言し、docker compose upという単一コマンドで一括起動・停止できるツールです。WebサーバーとAPI、データベース、キャッシュを別々のdocker runで立ち上げていた手作業を、定義ファイル1枚に集約します。この記事では、compose.yamlのservices・networks・volumesの書き方、up/downなど日常で使う主要コマンド、Python製の旧docker-composeからGo製Compose V2への移行状況、そして開発・検証・本番での使いどころと、単一ホストで完結させてよい境界からKubernetesへ移すべき条件までを、実装者の視点で整理します。

まとめ：docker-composeで複数コンテナを一括管理する要点

docker-composeの本質は、複数コンテナの構成・依存関係・ネットワーク・永続化をcompose.yamlに宣言し、1コマンドで環境ごと再現できる点にあります。docker runを人手で何度も打つ運用を置き換え、開発者ごとの環境差をなくすのが最大の効き目です。

現在の標準はGo実装のCompose V2で、コマンドはdocker-compose（ハイフン）からdocker compose（スペース区切りのサブコマンド）へ移りました。用途としては、単一ホストでの開発・検証・小規模な本番までがdocker-composeの守備範囲です。複数ホストにまたがる冗長構成や自動スケールが要件になった時点でKubernetesへ移す、という線引きを判断の章で条件付きに示します。

docker-composeの仕組みと単一コマンドで複数コンテナを動かす構成

まず押さえるべきは、docker-composeが「何を宣言し、何を自動化するか」です。ここでの起点は、複数コンテナの定義を1ファイルにまとめる宣言的な考え方にあります。コンテナ技術そのものの基礎や企業の導入判断は、コンテナと仮想マシンの違いから導入判断までの解説で先に押さえておくと、composeが解く課題をつかみやすくなります。

services・networks・volumesをyamlで宣言する基本構成

compose.yamlは、大きく3つの要素で成り立ちます。servicesが起動するコンテナ群の定義、networksがコンテナ間の仮想ネットワーク、volumesがデータを永続化する名前付きボリュームです。1つのservice（例：webとdb）ごとにイメージ・公開ポート・環境変数を書き、Composeは起動時に既定のネットワークを自動生成して、サービス名（例：db）をホスト名としてコンテナ間の名前解決を通します。この「サービス名で相互に呼べる」挙動が、複数コンテナ構成を簡潔にします。

docker runの手打ちをcompose.yamlへ置き換える一元管理

Docker単体では、コンテナごとにdocker run -d --name db -e ...を個別に実行し、ネットワークやボリュームも手で作る必要があります。docker-composeは、これらをファイルに宣言し、docker compose up一発へまとめる仕組みです。単一コンテナの起動そのものはDockerの仕組みとコンテナ隔離の解説で扱うdocker runが基礎になりますが、composeはその手順書をコード化し、誰が実行しても同じ構成が立ち上がる再現性をもたらします。手打ちのミスや順序の取り違えが減るのが実務上の差です。

Compose V2への移行とcompose.yaml・version廃止の現状

Python製の旧docker-compose（V1）は2023年にサポート終了となり、現在はGoで書かれたCLIプラグインのCompose V2が標準です。呼び出しはハイフンのdocker-composeから、スペース区切りのdocker composeサブコマンドへ変わりました。ファイル名もcompose.yamlが推奨で、従来のdocker-compose.ymlも引き続き読み込めます。また、かつて先頭に書いたversion: "3.8"の指定は、Compose仕様（Compose Specification）への統合にともない現行では不要（記述しても無視される）です。新規に書くならversion行は省く形が2026年時点の書き方になります。

compose.yamlの主要素とdocker compose upまでの基本操作

次に、実際のcompose.yamlの書き方と、起動から確認までのコマンドを見ていきます。ここが日々の運用で最も触れる部分です。ビルド定義はDockerfileをそのまま参照するため、Dockerfileの書き方と主要命令の解説と組み合わせると、イメージのビルドから起動までが一続きになります。

services定義でimage・ports・environmentを指定する書式

各serviceには、既存イメージを使うimage:か、Dockerfileからビルドするbuild:のどちらかを指定します。ports:でホストとコンテナのポート対応（例："8080:80"）を、environment:で環境変数を渡す形です。データベースのように状態を持つserviceにはvolumes:で名前付きボリュームを割り当て、コンテナを作り直してもデータが消えないようにします。1つのファイルにwebとdbを並べて書けば、両者の関係ごと宣言できるのが利点です。

depends_onとhealthcheckで起動順と依存を制御する方法

depends_onは、サービスの起動順序を制御します。ただし既定のdepends_onは「コンテナが起動したか」しか見ず、中のDBが接続を受け付ける状態かまでは待ちません。そこで各serviceにhealthcheckを定義し、depends_on側でcondition: service_healthyを指定すると、DBが実際に応答可能になってからwebを起動できます。起動直後の接続失敗を避けたい構成では、この2つを組み合わせるのが定石になります。

up・down・ps・logs・execなど日常運用で使う主要コマンド

Compose V2で頻用するコマンドを、役割ごとに整理します。基本は起動・停止・状態確認・ログ・コンテナ内操作の5系統です。

ボリュームごと消したいときはdown -vを付けます。downの既定では名前付きボリュームは残るため、データ保持と初期化を使い分けられます。

開発・検証・本番の各段階で使うdocker-composeの実務的な使いどころ

docker-composeが最も効くのは、複数サービスをまとめて再現したい場面です。段階ごとに向く使い方と、注意すべき点が変わります。

開発環境をcompose一発で再現しチーム間の差異をなくす使い方

新しくチームに加わった開発者が、リポジトリをgit cloneしてdocker compose upを打つだけで、Web・API・DB・キャッシュが揃った同一の開発環境を得られます。ローカルにDBやミドルウェアを個別インストールする必要がなく、「自分の環境では動く」というOS差・バージョン差の問題も起きにくいのが利点です。compose.yamlをリポジトリに含めておくことで、環境構築の手順書がコードとして共有される形になります。

profilesとCompose Watchで行うサービス切替とホットリロード

Compose V2のprofilesを使うと、通常は起動しない管理ツールやテスト用サービスを、--profile debugのように必要なときだけ有効化できます。さらにCompose Watch（docker compose watch）は、ソースコードの変更を検知してコンテナへ同期・再起動を行い、開発時のホットリロードに近い体験を実現する仕組みです。手元のファイルを保存するたびにイメージを手動で作り直す手間が消えるため、フロントエンドやAPIの反復開発の速度が上がります。

単一ホストの小規模本番やステージングで使う際の運用上の注意点

docker-composeは、1台のサーバー上で完結する小規模な本番やステージングにも使えます。ただし、コンテナが落ちたときの自動復旧はrestart: alwaysなどの再起動ポリシー頼みで、複数ホストへの分散や無停止デプロイの仕組みは持ちません。単一ホストである以上、そのサーバー自体が単一障害点になります。可用性の要件が上がってきたら、後述のオーケストレーション基盤への移行を検討する前提で運用するのが安全です。

docker-composeを採用すべき条件と本番でKubernetesへ移す境界

ここまでを踏まえ、composeで完結させてよい場合と、別基盤へ移すべき場合を条件で言い切ります。「規模による」で終わらせず、判断軸を具体化します。

composeだけで完結させてよいシステム規模と構成の判断基準

次の条件をすべて満たすなら、docker-composeのまま運用して差し支えありません。

• アプリケーションが1台のホストに収まり、水平スケールの要件がない
• 数分程度の再起動を許容でき、無停止デプロイまでは求められない
• サービス数が十数個までで、compose.yamlで見通しよく管理できる
• 開発・検証環境や、社内利用・小規模なサービスの本番である

小さく始めるフェーズでは、Kubernetesの運用コストを負うより、composeで素早く回すほうが合理的です。

複数ホストと冗長化が要る本番でKubernetesへ移す境界

逆に、次のいずれかに至ったらオーケストレーション基盤への移行を検討します。複数ホストへコンテナを分散して冗長化したい、負荷に応じて自動でスケールさせたい、無停止でローリングデプロイしたい、といった要件です。この段階でのKubernetesやマネージドサービスの位置づけは、コンテナオーケストレーションとKubernetesの役割の解説で判断軸を整理しています。単一ホスト前提のcomposeでは、可用性と自動スケールを満たせないのが移行の境界線です。本番のコンテナ基盤をAWS・GCP・Azure上で設計・移行したい場合は、AWS/GCP/Azureでのインフラ構築の相談から具体的な構成を詰められます。

docker-composeで失敗しやすい典型パターンと回避策

よくある失敗は、開発用のcompose.yamlをそのまま本番へ持ち込むことです。開発向けのポート全公開・デバッグ設定・平文の環境変数を本番に流用すると、セキュリティと安定性の両面で問題になります。回避策は、環境ごとに設定を分けることです。共通定義をcompose.yamlに置き、環境差分をcompose.override.yamlや別ファイルに分離し、機密値は.envやsecretsで外出しします。もう1つの典型は、composeで無理にスケールさせようとして単一ホストの限界にぶつかるパターンで、これは移行の境界を越えたサインと捉えるべきです。

docker-composeの仕組みと使い方に関するよくある質問

導入検討でよく挙がる質問に、実装の観点から簡潔に答えます。

docker-composeとdocker composeの違いは何ですか？

ハイフンのdocker-composeはPython製の旧V1、スペース区切りのdocker composeはGo製のV2で、現在の標準はV2です。V1は2023年にサポート終了しました。機能面はV2が上位互換で、既存のdocker-compose.ymlもそのまま読み込めます。新規に始めるならdocker composeコマンドを使ってください。

compose.yamlとdocker-compose.ymlはどちらを使うべきですか？

新規作成ではcompose.yamlが推奨のファイル名です。従来のdocker-compose.ymlも引き続き認識されるため、既存プロジェクトを無理に改名する必要はありません。中身の書式は同じで、ファイル名の差だけです。迷う場合はcompose.yamlで統一すると現行の仕様に沿います。

versionの記述は今も必要ですか？

不要です。かつて先頭に書いたversion: "3.x"は、Compose仕様への統合で廃止扱いになり、記述しても無視されます。むしろ古い記事のまま残すと混乱のもとになるため、新規のcompose.yamlではversion行を省いて、servicesから書き始めます。

docker-composeは本番環境で使えますか？

単一ホストで完結する小規模な本番なら使えます。ただし複数ホストへの分散・自動スケール・無停止デプロイは扱えないため、可用性が要件になる本番ではKubernetes等のオーケストレーション基盤へ移すのが妥当です。開発・ステージングまでをcompose、規模拡大後を別基盤、という使い分けが現実的です。

compose内の複数コンテナはどう通信しますか？

Composeが自動生成する既定ネットワーク上で、サービス名をホスト名として名前解決できます。例えばwebからDBへは、IPではなくdbというサービス名で接続する形です。別ネットワークに分離したい場合はnetworksを明示的に定義し、どのサービスをどのネットワークに属させるかを指定します。

関連記事

• コンテナとは？仮想マシンとの違いから導入判断まで：composeの前提となるコンテナ技術の基礎と企業導入の判断軸を解説しています。
• Dockerの仕組みを原理から理解する：composeが束ねる個々のコンテナの隔離・アーキテクチャの基礎です。
• Dockerfileとは？書き方と主要命令の解説：composeのbuild指定が参照するイメージ定義の書き方です。
• Dockerコンテナを起動する基本手順：composeが自動化する前の、単体コンテナ起動の基礎操作です。
• コンテナオーケストレーションとは？Kubernetesの役割：composeから移行する先の基盤選定の判断軸を整理しています。