Docker Compose 入門 — 複数コンテナを一括管理

2026年10月16日 2026年10月16日

akinori

概要

Web アプリケーションの開発環境は、アプリ本体だけでは完結しません。データベース、キャッシュ、リバースプロキシなど、複数のコンテナを同時に動かす必要があります。これらを docker run で 1 つずつ起動すると、ポート・ネットワーク・環境変数・起動順序をすべて手作業で管理することになり、すぐに破綻します。

Docker Compose は、複数コンテナの構成を 1 つの YAML ファイル（compose.yaml）に宣言的に記述し、docker compose up の一発で丸ごと起動・停止できるツールです。本記事では、基本から実用的な構成までを入門者向けに解説します。

環境

Docker Engine 20.10 以降（Compose V2 同梱）
コマンドは docker compose（V2・スペース区切り）を前提とします
旧 docker-compose（V1・ハイフン区切り）は非推奨です

docker compose version

Docker Compose とは

Compose は「複数コンテナをまとめて 1 つのアプリケーションとして扱う」ためのツールです。docker run との違いは次のとおりです。

項目	`docker run`	Docker Compose
設定の記述	コマンドライン引数	YAML ファイル（宣言的）
複数コンテナ	個別に起動	一括起動
ネットワーク	手動作成	自動作成（サービス名で名前解決）
再現性	低い（属人的）	高い（ファイルで共有）
起動・停止	コンテナごと	`up` / `down` で一括

開発環境の構成をコードとして管理でき、チームでファイルを共有すれば全員が同じ環境を瞬時に再現できます。

最小構成から始める

単一サービス

プロジェクトルートに compose.yaml を作成します。

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"

docker compose up -d

http://localhost:8080 で nginx のデフォルトページが表示されれば成功です。なお Compose V2 では冒頭の version: キーは不要です。

アプリ + データベース

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/appdb
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

ポイントは 3 つです。

サービス名で通信できる — app から DB へは db:5432 で接続できます。Compose が自動でネットワークを作り、サービス名を DNS として解決するためです。
名前付きボリュームで永続化 — db-data に DB のデータを保存します。これがないとコンテナ削除のたびにデータが消えます。
depends_on で起動順を制御 — db を先に起動します（後述の注意あり）。

主要ディレクティブ

ディレクティブ	役割
`image`	使用するイメージ
`build`	Dockerfile からビルド
`ports`	`ホスト:コンテナ` のポートマッピング
`environment` / `env_file`	環境変数
`volumes`	ボリューム / バインドマウント
`depends_on`	起動順の依存
`restart`	再起動ポリシー
`healthcheck`	ヘルスチェック

認証情報は `.env` に外出しする

パスワードなどを compose.yaml に直書きせず、.env に分離して .gitignore で除外します。

services:
  db:
    image: postgres:16
    env_file:
      - .env

# .env（Git にコミットしない）
POSTGRES_USER=app
POSTGRES_PASSWORD=change_me
POSTGRES_DB=appdb

よく使うコマンド

docker compose up -d            # 起動（バックグラウンド）
docker compose up -d --build    # ビルドし直して起動
docker compose down             # 停止・削除（ボリュームは残る）
docker compose logs -f app      # ログ追跡（特定サービス）
docker compose ps               # 稼働状態の一覧
docker compose exec app sh      # コンテナ内でコマンド実行
docker compose config           # 構成を検証（起動せず確認）

実装例: healthcheck で準備完了を待つ 3 サービス構成

services:
  app:
    build: .
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    env_file:
      - .env
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5
    restart: unless-stopped

  proxy:
    image: nginx:1.27
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app
    restart: unless-stopped

volumes:
  db-data:

healthcheck と condition: service_healthy を組み合わせ、DB が実際に接続可能になってからアプリを起動しています。

確認方法

docker compose config    # 設定の構文・変数展開を検証
docker compose ps        # 各サービスの状態（healthy 判定含む）

docker compose config は .env の展開結果を含めた最終構成を出力するため、「変数が効いていない」系トラブルの切り分けに有効です。

注意点

depends_on は準備完了を待たない — プロセス起動を待つだけなので、DB が接続を受け付ける前にアプリが落ちることがあります。healthcheck + condition: service_healthy、またはアプリ側のリトライで対処します。
down -v は破壊的 — docker compose down はボリュームを残しますが、-v を付けるとボリュームごと削除され DB データが消えます。実行前に必ず対象を確認してください。
ポートの衝突 — ホスト側ポートが埋まっていると起動に失敗します。"8080:80" の左側を調整します。