docker-compose.yml の全オプション解説【入門】

2026年10月22日 2026年10月22日

akinori

概要

Docker を使っていると、アプリ本体・データベース・キャッシュといった複数のコンテナをまとめて起動したくなります。そこで使うのが Docker Compose です。設定ファイル docker-compose.yml（現在は compose.yaml が推奨）に「どのコンテナを・どう動かすか」を宣言的に書いておけば、docker compose up ひとつで環境が立ち上がります。

本記事では、docker-compose.yml の主要オプションをトップレベル項目ごとに、入門者向けに整理します。各オプションが「何のためにあるのか」が分かることをゴールにします。なお本記事は Compose v2（docker compose サブコマンド）を前提とします。

ファイルの全体構造

トップレベルには主に次のキーが並びます。

services:   # コンテナの定義（中心）
networks:   # ネットワークの定義
volumes:    # 名前付きボリュームの定義
configs:    # 設定ファイルの共有
secrets:    # 機密情報の共有

かつて先頭に書いていた version: "3.8" は、Compose v2 では非推奨（書かなくてよい）になりました。新規に書くなら省略します。

services 配下のオプション

services: の下に、サービス（コンテナ）名ごとの設定をぶら下げます。

image / build — イメージの指定

コンテナの元になるイメージを、既存イメージを使うか Dockerfile からビルドするかで指定します。

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - APP_ENV=production
      target: production
  db:
    image: postgres:16

build: . と短縮もできます。image と build を両方書くと、ビルドしたイメージに名前タグを付けられます。

container_name — コンテナ名の固定

services:
  db:
    image: postgres:16
    container_name: myapp-db

指定しないと プロジェクト名-サービス名-連番 が自動で付きます。固定するとスケール（複数起動）できなくなる点に注意します。

ports / expose — ポート公開

services:
  web:
    ports:
      - "8080:80"              # ホスト:コンテナ
      - "127.0.0.1:443:443"    # ホスト側IPを限定
  db:
    expose:
      - "5432"                 # 同一ネットワーク内のみ公開

ports の値は、YAML が数値を60進数と誤解する事故を避けるため必ずクォートで囲みます。expose はホストに晒さず、同じネットワーク内のコンテナからのみ到達可能にします。

environment / env_file — 環境変数

services:
  web:
    environment:
      APP_ENV: production
      TZ: Asia/Tokyo
    env_file:
      - .env

機密を含む値は .env に逃がし、.env はリポジトリにコミットしないのが基本です。

volumes — データの永続化とマウント

services:
  db:
    volumes:
      - db-data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d
      - ./config.yml:/app/config.yml:ro
volumes:
  db-data:

コンテナを消してもデータを残すなら名前付きボリューム、ソースのホットリロードならバインドマウントを使います。末尾の :ro は読み取り専用です。

depends_on / healthcheck — 起動順序と死活監視

services:
  web:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s

depends_on は起動順を制御しますが、短縮形では「コンテナが起動した」ことしか保証しません。「DB が接続を受け付けられる状態になった」まで待つには、healthcheck と condition: service_healthy を組み合わせます。入門者が「DB接続エラーで落ちる」とハマる典型ポイントです。

restart — 再起動ポリシー

services:
  web:
    restart: unless-stopped

値	挙動
`no`（既定）	自動再起動しない
`always`	常に再起動する
`on-failure`	異常終了時のみ
`unless-stopped`	手動停止以外は再起動

command / entrypoint — 起動コマンドの上書き

services:
  worker:
    image: myapp:latest
    command: ["php", "artisan", "queue:work"]

イメージ側の ENTRYPOINT / CMD を上書きします。exec 形式（配列）で書くとシェルを介さず正確に渡せます。

リソース制限・ログ・その他

services:
  app:
    working_dir: /app
    user: "1000:1000"
    tty: true
    stdin_open: true
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    extra_hosts:
      - "host.docker.internal:host-gateway"

logging を設定しないとログが無制限に膨らみディスクを圧迫します。長期稼働させるなら max-size / max-file を入れておくと安心です。

トップレベル volumes / networks / secrets

networks:
  backend:
    driver: bridge
    internal: true      # 外部に出られない閉域ネットワーク

volumes:
  db-data:
    external: true      # 既存ボリュームを参照（Composeは作らない）

secrets:
  db_password:
    file: ./db_password.txt

ネットワークを明示しなくても、全サービスは既定ネットワークに参加し、サービス名で名前解決できます。external: true は「このファイルでは作らず既存のものを使う」宣言です。secrets はコンテナ内 /run/secrets/<名前> に配置され、環境変数より漏れにくい利点があります。

実装例（Web + DB の最小構成）

services:
  web:
    build: .
    ports:
      - "8080:80"
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - ./src:/var/www/html

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: appdb
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5
    secrets:
      - db_password
    restart: unless-stopped

volumes:
  db-data:

secrets:
  db_password:
    file: ./db_password.txt

確認方法

docker compose config    # 最終形（.env展開済）を検証
docker compose up -d      # 起動
docker compose ps         # 状態・ヘルスチェック確認
docker compose logs -f web
docker compose down       # 停止・削除（-v でボリュームも削除）

docker compose config は .env 展開まで含めた「実際に適用される最終形」を表示するため、書き間違いの切り分けに最も役立ちます。

注意点

version: キーは Compose v2 では不要（非推奨）。
ports の値は YAML の数値誤解釈を避けるため必ずクォートする。
depends_on 単体は「起動順」であり「準備完了」ではない。待ちたいなら healthcheck + condition: service_healthy。
docker compose down -v はボリュームごと消す。DB データを残したいときは -v を付けない。
機密は environment 直書きより .env / secrets を使い、実体はコミットしない。

まとめ

docker-compose.yml のオプションは数が多く見えますが、「どのイメージを・どう公開して・何を永続化し・どの順で起動するか」という4つの軸で捉えると整理しやすくなります。まずは image / ports / volumes / environment / depends_on を押さえ、安定運用の段階で healthcheck / restart / logging を足していきましょう。迷ったら docker compose config で最終形を確認する習慣をつけるのがおすすめです。