Docker初心者向け: compose.yml の中身を1項目ずつ読む入門――services / ports / volumes / environment

Docker初心者向け: compose.yml と Dockerfile の違いを最小構成で理解する で役割分担を見たあと、次に詰まりやすいのが compose.yml 自体の読み方です。この記事では app 1 サービスの最小 PHP サンプルを使い、services ports volumes environment command を上から順に読みます。Compose キーの全網羅、Dockerfile 命令の詳細、本番向け構成は扱いません。

1. 記事のゴール

到達する状態:

• compose.yml を開いたら、どこから見始めればよいか分かる
• ports の左右がホスト側とコンテナ側のどちらか説明できる
• volumes と environment が実行時の設定だと整理できる
• command が起動コマンドの上書きだと判断できる

扱わない内容:

• Compose キーの全網羅
• depends_on や networks の詳細
• Dockerfile 命令の詳細解説
• 本番運用の設計論

目的は、「設定を全部覚えること」ではありません。既存記事や既存リポジトリの compose.yml を見たとき、確認ポイントを順番に追えるようにすることに絞ります。

2. compose.yml は何をするファイルか

先に 1 文で置くと、compose.yml は「コンテナをどう起動するかをまとめるファイル」です。

読む順番も先に固定しておくと迷いにくくなります。

1. services で登場するサービス名を確認する
2. ports でホストからどこへ入るかを見る
3. volumes でホストのファイルがどこへ見えるかを確認する
4. environment で実行時に渡す値を見る
5. command で起動方法の上書き有無を確認する

Dockerfile がイメージの中身を決めるのに対して、compose.yml はそのイメージをどう動かすかを決めます。今回の本文では、起動設定としての compose.yml にだけ絞ります。

関係を図にすると次の形です。

flowchart LR
    A[compose.yml] --> B[services]
  B --> C[app]
  C --> D[ports]
  C --> E[volumes]
  C --> F[environment]
  C --> G[command]
  D --> H[container]
  E --> H
  F --> H
  G --> H

3. 完成形を先に見る

今回使う構成は 2 ファイルだけです。

compose-yml-reading-demo/
├─ compose.yml
└─ app/
   └─ index.php

作業ディレクトリを作って開きます。

mkdir -p ~/projects/compose-yml-reading-demo/app
cd ~/projects/compose-yml-reading-demo
code .

3-1. compose.yml を作成する

services:
  app:
    image: php:8.5-cli
    ports:
      - "8080:8000"
    volumes:
      - ./app:/app
    environment:
      APP_MESSAGE: "Hello from compose.yml"
    command: php -S 0.0.0.0:8000 -t /app

3-2. app/index.php を作成する

<?php

declare(strict_types=1);

$message = getenv('APP_MESSAGE') ?: 'Hello from PHP';

echo "<h1>{$message}</h1>";
echo '<p>compose.yml を上から読むサンプルです。</p>';

このサンプルでは Dockerfile を使いません。理由は、compose.yml の主要項目だけを短く読みたいからです。image で公式イメージを直接指定すると、ports volumes environment command の役割をそのまま追えます。

4. services とは

services は、どのコンテナをどういう名前で扱うかを決める場所です。

services:
  app:
    image: php:8.5-cli

今回の例では app がサービス名です。docker compose up app や docker compose logs app のように、後続コマンドでもこの名前を使います。

複数サービス構成になると、ここに db や nginx が並びます。最初に services を見る理由は、「登場人物が何人いるか」を把握できるからです。既存の compose.yml を読むときも、まずサービス数と名前を見るだけで全体像を追いやすくなります。

今回のサンプルでは working_dir を置いていません。command の -t /app でドキュメントルートを指定できるため、主要項目の読み解きに不要なキーは外しています。

5. ports の左右の意味

ports は、ホストのどのポートからコンテナのどのポートへつなぐかを決めます。

ports:
  - "8080:8000"

この書き方では、左の 8080 がホスト側、右の 8000 がコンテナ側です。

• ブラウザや curl で開くのは左側の 8080
• コンテナ内で PHP の開発サーバが待ち受けるのは右側の 8000

今回の command は php -S 0.0.0.0:8000 -t /app なので、コンテナ内アプリは 8000 を使っています。外から http://localhost:8080 で見えるのは、ports が 8080 と 8000 をつないでいるからです。

ここで混乱しやすいのは、右側を書き換えるとコンテナ内の待受ポートも合わせて直す必要がある点です。左側だけを 9000 に変えるならブラウザの URL が変わるだけですが、右側を変えるならアプリ側の待受設定とも合わせます。

6. volumes の役割

volumes は、ホストのファイルやディレクトリをコンテナ内へ見せる設定です。

volumes:
  - ./app:/app

この書き方では、左の ./app がホスト側、右の /app がコンテナ側です。

手元の app/index.php を編集すると、コンテナから見える /app/index.php も同じ内容になります。ローカル開発で volumes をよく使うのは、イメージを毎回作り直さなくてもソース変更を反映できるからです。

volumes はコピーではありません。起動中のコンテナへホストのファイルを見せている形です。この点を押さえると、「ファイルを変えたのに反映されない」「逆にコンテナ内の見え方がホストに引っ張られる」といった状況を説明しやすくなります。

7. environment の意味

environment は、コンテナ起動時に環境変数を渡す設定です。

environment:
  APP_MESSAGE: "Hello from compose.yml"

今回の index.php では次のように受け取っています。

$message = getenv('APP_MESSAGE') ?: 'Hello from PHP';

この値を Welcome from Docker のように変えて再起動すると、ページの見出しも変わります。ここで重要なのは、イメージを作り替えなくても実行時の値だけ差し替えられる点です。

開発環境ごとに URL やメッセージを変えたいとき、設定の入り口としてまず疑う場所が environment です。既存記事を読むときも、アプリコードの getenv やフレームワーク設定と見比べるとつながりが見えます。

8. command は何を上書きするか

command は、イメージが持っている既定の起動コマンドを、Compose 側で上書きする設定です。

command: php -S 0.0.0.0:8000 -t /app

今回 image に指定しているのは php:8.5-cli です。このイメージをそのまま使うだけでは Web サーバとして待ち受けません。そこで command で PHP の開発サーバを起動し、/app をドキュメントルートにしています。

起動方法をその環境だけ変えたいときは、まず command を確認します。イメージ自体の既定動作を作りたいなら Dockerfile の CMD 側ですが、今回のような最小サンプルでは Compose 側で上書きしたほうが役割を見分けやすくなります。

9. 起動して確認する

起動確認は次の 3 手順で十分です。

まず、コンテナを起動します。

docker compose up -d

次に、ポート公開とコマンドが想定どおりかを一覧で見ます。

docker compose ps

表示確認はブラウザでも curl でも構いません。

curl http://localhost:8080

見出しに Hello from compose.yml が出れば、environment の値がアプリへ渡っています。アクセスできない場合は、docker compose logs app で PHP の開発サーバが 0.0.0.0:8000 で起動しているか確認します。

ここで確認したい対応関係は次の通りです。

• ports の左側 8080 でホストからアクセスする
• command の 8000 でコンテナ内サーバが待ち受ける
• volumes の ./app:/app でホストの index.php がそのまま見える
• environment の APP_MESSAGE がページ見出しへ反映される

10. よくある読み違い

ports の左右を逆に読む

左がホスト、右がコンテナです。ブラウザで開く URL は左側を見ます。右側はコンテナ内アプリの待受ポートです。

volumes はコピーだと思ってしまう

volumes は起動中コンテナへホストのファイルを見せる設定です。イメージへ焼き込む処理ではありません。

environment はイメージへ固定されると思ってしまう

environment は実行時の値です。コンテナ起動時に渡されるため、値だけ差し替えて再起動できます。

command を変えるたびに Dockerfile を直すと思ってしまう

起動方法だけを環境ごとに変えたいなら、まず Compose 側の command を疑います。Dockerfile の CMD を毎回作り替える話とは役割が違います。

11. まとめ

compose.yml を読む順番は、services で登場人物を確認し、ports volumes environment command を続けて追う形が基本です。これだけでも、既存の Docker 構成で「どこを見ればよいか」の順番を揃えやすくなります。

次に読むなら、役割分担を先に整理した Docker初心者向け: compose.yml と Dockerfile の違いを最小構成で理解する、または実務寄りの構成へ進む Windows 11で始めるPHPローカル開発環境（WSL2 + Docker + PostgreSQL） がつながりやすい導線です。