compose.yamlの基本構文
Docker Composeの設定は、YAML形式で記述します。ファイル名はcompose.yaml(またはdocker-compose.yml)を使用します。
| 💡 ポイント |
|---|
Docker Compose V2(現在の標準)ではcompose.yamlが推奨ファイル名です。インターネット上の古いチュートリアルではdocker-compose.ymlが使われていることがありますが、どちらでも動作します。本章では推奨されるcompose.yamlを使用します。Docker公式のHow Compose worksにも「The default path for a Compose file is compose.yaml (preferred) or compose.yml that is placed in the working directory.」と明記されています。 |
ここでは、シンプルな構成から段階的に機能を追加していく形で、compose.yamlの書き方を学んでいきます。
1. シンプルなサービスの定義
まずは、1つのコンテナだけを起動する最もシンプルな例から見ていきましょう。
services:
web:
image: nginx:alpine
この設定ファイルは、以下のdocker container runコマンドと同等の動作をします。
docker container run nginx:alpine
servicesセクションは、Docker Composeで起動するコンテナを定義する場所です。webはサービス名で、任意の名前を付けることができます。imageは、コンテナのベースとなるDockerイメージを指定します。
Dockerfileからイメージをビルドする場合は、imageの代わりにbuildを使用します。
services:
api:
build: ./api
この設定は、以下のDockerコマンドを順番に実行するのと同等です。
docker image build -t api-image ./api
docker container run api-image
./apiディレクトリにあるDockerfileを使用してイメージをビルドし、そのイメージからコンテナを起動します。docker compose upを実行すると、これらの処理が自動的に行われます。
2. 複数のサービスの定義
Docker Composeの真価は、複数のコンテナを同時に管理できることにあります。servicesセクションに複数のサービスを記述することで、複数のコンテナを一括で起動できます。
services:
db:
image: mysql:8.0
api:
build: ./api
web:
image: nginx:alpine
この設定では、3つのコンテナ(データベース、API、Webサーバ)が定義されています。docker compose upコマンドを1回実行するだけで、3つのコンテナがすべて起動します。
Dockerコマンドで同じことを行う場合、以下の複数のコマンドを実行する必要があります。
docker image build -t api-image ./api
docker container run -d -e MYSQL_ROOT_PASSWORD=rootpassword mysql:8.0
docker container run -d api-image
docker container run -d nginx:alpine
Docker Composeを使うことで、これらのコマンドを1つのdocker compose upで置き換えられます。
| 💡 ポイント |
|---|
Docker Composeは、同じプロジェクト内のサービス間で自動的にネットワークを作成し、サービス名でお互いに通信できるようにします。例えば、apiサービスからdbサービスへは、ホスト名dbで接続できます。 |
3. ポート・環境変数・ボリュームの設定
実際のアプリケーションでは、ポートの公開や環境変数の設定、データの永続化が必要です。これらの設定は、各サービスの下に追加していきます。
3.1 ports(ポートマッピング)
portsは、ホストマシンのポートとコンテナのポートをマッピングします。これにより、ホストマシンからコンテナ内のアプリケーションにアクセスできるようになります。
services:
web:
image: nginx:alpine
ports:
- "8080:80"
この設定は、以下のDockerコマンドと同等です。
docker container run -p 8080:80 nginx:alpine
ホストの8080番ポートにアクセスすると、コンテナの80番ポートに転送されます。
複数のポートをマッピングすることもできます。
ports:
- "8080:80"
- "8443:443"
3.2 environment(環境変数)
environmentは、コンテナに環境変数を渡します。データベースの接続情報やアプリケーションの設定値など、外部から注入したい値を指定します。
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: appdb
MYSQL_USER: appuser
MYSQL_PASSWORD: apppassword
この設定は、以下のDockerコマンドと同等です。
docker container run \
-e MYSQL_ROOT_PASSWORD=rootpassword \
-e MYSQL_DATABASE=appdb \
-e MYSQL_USER=appuser \
-e MYSQL_PASSWORD=apppassword \
mysql:8.0
環境変数は、リスト形式で記述することもできます。
environment:
- MYSQL_ROOT_PASSWORD=rootpassword
- MYSQL_DATABASE=appdb
どちらの形式でも動作は同じですが、キーと値を明確に分離できるマップ形式(最初の例)が読みやすいでしょう。
3.3 volumes(ボリューム・バインドマウント)
volumesは、データの永続化やホストとのファイル共有を設定します。
名前付きボリュームは、Dockerが管理する永続的なデータ領域です。データベースのデータなど、コンテナを削除しても残しておきたいデータに使用します。
services:
db:
image: mysql:8.0
volumes:
- db-data:/var/lib/mysql
volumes:
db-data:
この設定は、以下のDockerコマンドと同等です。
docker volume create db-data
docker container run -v db-data:/var/lib/mysql mysql:8.0
サービスのvolumesで使用する名前付きボリュームは、ファイル末尾のvolumesセクション(トップレベル)で宣言する必要があります。Docker Composeは、トップレベルで宣言されたボリュームを自動的に作成します。
バインドマウントは、ホストマシンのディレクトリをコンテナにマウントします。開発時にソースコードを即座に反映させたい場合などに使用します。
services:
web:
image: nginx:alpine
volumes:
- ./html:/usr/share/nginx/html
この設定は、以下のDockerコマンドと同等です。
Macの場合:
docker container run -v $(pwd)/html:/usr/share/nginx/html nginx:alpine
Windowsの場合(PowerShell):
docker container run -v ${PWD}/html:/usr/share/nginx/html nginx:alpine
ホストの./htmlディレクトリがコンテナの/usr/share/nginx/htmlにマウントされます。ホスト側でファイルを編集すると、コンテナ内にも即座に反映されます。
4. 起動順序の制御
複数のコンテナが依存関係を持つ場合、起動順序を制御する必要があります。例えば、APIサーバはデータベースが起動してから起動する必要がある場合などです。
4.1 depends_on(基本的な起動順序)
depends_onは、サービス間の依存関係を定義し、起動順序を制御します。
services:
api:
build: ./api
depends_on:
- db
db:
image: mysql:8.0
この設定では、dbサービスが先に起動し、その後にapiサービスが起動します。docker compose upを実行すると、Docker Composeが自動的にこの順序を守ってコンテナを起動します。
Dockerコマンドで同じことを行う場合、手動で正しい順序でコンテナを起動し、さらに同じネットワークに接続する必要があります。
まずネットワークを作成します。
docker network create myapp
続いて、DBコンテナをネットワークに接続して起動します。
docker container run -d --name db --network myapp -e MYSQL_ROOT_PASSWORD=rootpassword mysql:8.0
APIコンテナ用のイメージをビルドします。
docker image build -t api ./api
APIコンテナを同じネットワークに接続して起動します。
docker container run -d --name api --network myapp api
Docker Composeのdepends_onを使えば、この順序とネットワーク接続を自動的に管理できます。
| 💡 ポイント |
|---|
depends_onは「コンテナの起動順序」を制御するだけで、「アプリケーションの準備完了」を待つわけではありません。例えば、MySQLコンテナが起動しても、MySQL自体が接続を受け付けられる状態になるまでには時間がかかります。アプリケーションの準備完了を待つには、次に説明するヘルスチェックを使用します。 |
5. ヘルスチェック
healthcheckは、コンテナ内のアプリケーションが正常に動作しているかを定期的にチェックする機能です。ヘルスチェックとdepends_onを組み合わせることで、依存先のアプリケーションが本当に準備完了してから起動するように制御できます。Docker公式のCompose file reference - Servicesにも、depends_onの長い構文では「service_healthy: Specifies that a dependency is expected to be "healthy" (as indicated by healthcheck) before starting a dependent service.」と明記されており、condition: service_healthyを指定することで依存先のヘルスチェックがpassしてから起動できることが分かります。
services:
api:
build: ./api
depends_on:
db:
condition: service_healthy
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: appdb
healthcheck:
test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p$$MYSQL_ROOT_PASSWORD"]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
$$は、compose.yaml内で環境変数を参照するためのエスケープ記法です。シェルで実行される際に$MYSQL_ROOT_PASSWORDとして展開されます。
dbサービスのヘルスチェック設定は、以下のDockerコマンドと同等です。
docker container run \
--health-cmd="mysqladmin ping -h localhost -u root -p\$MYSQL_ROOT_PASSWORD" \
--health-interval=5s \
--health-timeout=3s \
--health-retries=10 \
--health-start-period=30s \
mysql:8.0
healthcheckの各オプションの意味は以下のとおりです。
| オプション | 説明 |
|---|---|
| test | ヘルスチェックで実行するコマンド。終了コード0で成功、1で失敗 |
| interval | チェックを実行する間隔(デフォルト: 30s) |
| timeout | コマンドのタイムアウト時間(デフォルト: 30s) |
| retries | 失敗と判定するまでの連続失敗回数(デフォルト: 3) |
| start_period | コンテナ起動後、ヘルスチェックを開始するまでの待機時間(デフォルト: 0s) |
depends_onでcondition: service_healthyを指定すると、依存先サービスのヘルスチェックが成功するまで、自サービスの起動を待機します。これにより、データベースが本当に接続可能な状態になってからAPIサーバを起動できます。
6. ネットワークの設定
Docker Composeは、デフォルトで同じcompose.yaml内のサービスが通信できる専用ネットワークを自動作成します。そのため、通常はネットワークを明示的に定義する必要はありません。
ただし、より複雑な構成(フロントエンドとバックエンドを別のネットワークに分離するなど)が必要な場合は、networksを使用してカスタムネットワークを定義できます。
services:
web:
image: nginx:alpine
networks:
- frontend
api:
build: ./api
networks:
- frontend
- backend
db:
image: mysql:8.0
networks:
- backend
networks:
frontend:
backend:
Dockerコマンドで同じ構成を実現するには、以下のように複数のコマンドを実行する必要があります。
まず、2つのネットワークを作成します。
docker network create frontend
docker network create backend
Web コンテナを frontend ネットワークに接続して起動します。
docker container run -d --name web --network frontend nginx:alpine
DB コンテナを backend ネットワークに接続して起動します。
docker container run -d --name db --network backend mysql:8.0
API コンテナを起動し、2つのネットワークに接続します。
docker container run -d --name api api-image
docker network connect frontend api
docker network connect backend api
Docker Composeを使えば、これらの複雑なネットワーク設定もcompose.yamlに記述するだけで自動的に構成されます。
この例では、2つのネットワーク(frontendとbackend)を定義しています。
webサービスはfrontendネットワークにのみ接続apiサービスは両方のネットワークに接続dbサービスはbackendネットワークにのみ接続
この構成により、webサービスからdbサービスへの直接通信はできなくなり、必ずapiサービスを経由する必要があります。セキュリティやアーキテクチャ上の理由でネットワークを分離したい場合に有効です。
| 💡 ポイント |
|---|
ネットワークを明示的に指定しない場合、すべてのサービスはデフォルトネットワーク(プロジェクト名_default)に接続され、サービス名でお互いに通信できます。多くの開発環境では、この自動設定で十分です。 |
7. 設定の全体像
ここまで学んだ設定をすべて組み合わせると、以下のような構成になります。
services:
db:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: appdb
volumes:
- db-data:/var/lib/mysql
healthcheck:
test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p$$MYSQL_ROOT_PASSWORD"]
interval: 5s
timeout: 3s
retries: 10
start_period: 30s
api:
build: ./api
ports:
- "8000:8000"
environment:
DB_HOST: db
DB_NAME: appdb
depends_on:
db:
condition: service_healthy
web:
image: nginx:alpine
ports:
- "3000:80"
volumes:
- ./html:/usr/share/nginx/html
volumes:
db-data:
このcompose.yamlは、3層アーキテクチャのアプリケーションを定義しています。docker compose up -dコマンド1つで、データベース・API・Webサーバの3つのコンテナが適切な順序で起動します。