サイトアイコン ITC Media

【2025年最新版】docker-compose.ymlの書き方を徹底解説｜実例・最新仕様・エラー対策まで

ITC運営

(最終更新月: 2025年7月15日)

✓当記事はこんな方におすすめです

「docker-compose.ymlの書き方を実例付きで丁寧に知りたい」

「docker composeの最新仕様やベストプラクティスを把握したい」

「実際の使い方・エラー対策・開発現場で役立つポイントを知りたい」

✓当記事で理解できること

この記事では、未経験・初学者の方でも迷わないよう、経験に基づく具体例・最新のドキュメント情報（2025年7月時点）を元に「docker-compose.yml」作成から運用、エラー解消のポイントまで詳しく解説します。Dockerを仕事や学習に活かす人が増えている今、他サイトよりも一歩先んじる知識を身につけたい方にもピッタリです。

最後まで読み進めていただくことで、現場ですぐ役立つdocker-compose.yml知識を得られます。それでは、一緒に見ていきましょう。

運営者プロフィール

現在はIT企業のプロダクトマネージャーとして、個人向け/社内向けシステムなど、複数のシステム開発・運営に携わっています。

Webサイト構築やECサイトの開発経験に加えて、PythonなどのプログラミングやSalesforceなどのクラウドアプリケーションに関する幅広い知識・経験を活かして「プログラミング初心者がスムーズに学べるサイト」を目指しています。

Githubでは、趣味で作成したアプリなどを公開しています。

https://github.com/Yulikepython/

✔人に見せても恥ずかしくないコードを書こう

「リーダブルコード」は、わかりやすく良いコードの定義を教えてくれる本です。

  • 見るからにきれいなコードの書き方
  • コードの分割方法
  • 変数や関数の命名規則

エンジニアのスタンダートとすべき基準を一から解説しています。

何回も読むのに値する本なので、ぜひ手にとって読んでみてください。

リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック
created by Rinker

Docker Composeの基本とアプリケーションモデル

このセクションでは、「Docker Compose とは何か・どんな仕組みで動くのか」「現代的なcompose.yaml構造」について解説します。

なぜなら、Docker Composeの全体像がイメージできていないと、書き方やエラーの意味を正しく理解できないからです。

Docker Composeの役割・メリット

Docker Composeは、複数のコンテナから成るアプリケーション環境を1つの宣言的なYAMLファイルで「まとめて管理・起動」できるツールです（参照: 公式ドキュメント）。

この仕組みにより、開発・テスト・本番などあらゆる場面で「同じ手順」「同じ動作環境」を再現できる強みがあります。

たとえばWebアプリ＋DB＋キャッシュサーバーを一発で起動する、CI/CDのジョブごとに新しい環境を用意する、といった作業もシンプルなコマンドだけで実現できます。

「各サーバーの設定が人ごとにバラバラ」「起動する度に手順で戸惑う」といったトラブルもComposeでグッと減らせます。

アプリケーションモデル（services・networks・volumes）

Composeが扱う基本要素はservices（サービス）・networks（ネットワーク）・volumes（ボリューム）です。

services にはWebアプリ、DB、Redisなどの役割を持つ「コンテナ」の定義を書きます。

networks はサービス間通信の経路を分離・制御するしくみで、デフォルトではプロジェクトごとに分離したネットワークが自動生成されます。

volumes は永続データやファイルをサービス間で共有する領域を表します。Composeファイルはこれらを宣言的に管理し、一貫性ある環境を作り出します。

プロジェクト名によるリソース分離と実運用例

Composeは「プロジェクト」という概念で、同じホスト内でもサービス・ネットワーク・ボリュームを安全に分離します。

例えばmyappディレクトリで docker compose up を実行すると、「myapp_default」などプロジェクト名接頭辞つきのリソースが自動生成されます。

この仕組みのおかげで複数のアプリ環境を一台で同時に立ち上げたり、「feature-x」「main」などブランチ単位でまるごと動作比較や検証が可能です。

開発組織やCI/CD、個人学習問わず再現性・安全性を担保する基本設計となっています。

compose.yamlの書き方と現代的な仕様のポイント

このセクションでは、docker-compose.yml（compose.yaml）の基本構造と、最新仕様への移行ポイントを詳しく解説します。

理由は、現代のDocker Composeは「version」キー推奨廃止など変化が大きく、情報が混在しているため、ここで「いま正しい書き方」を頭に入れておくと安心して実践できます。

ファイル名とYAML構文の注意点

Composeファイルはcompose.yamlが標準名です（互換のためdocker-compose.yaml等も読まれる）。

YAMLは空白2つのインデントで階層管理します。タブは使えないのでインデントミスが散発しがちです。

例えば下記のように記述します。


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

ファイル先頭に不要な空白やタブが入っただけでエラーになるため、エディタのYAMLサポートやエラーメッセージの読解力アップが必須です。

現代Composeではversionキーは不要

かつては version: ‘3.8’ などファイルの先頭でバージョンを明示していましたが、2025年時点のdocker composeコマンド（スペース区切り）は “version” キーを不要としています（参照: Compose file reference）。

Compose Specification（統一仕様）に則って常に最新スキーマで解釈されるため、今から新規作成する場合は省略しましょう。

昔のサンプルや他サイトの例で “version” があっても、機能的な意味は無いので混乱しないでください。

トップレベル要素と最新Compose Specification

compose.yamlは主に次のトップレベル要素からなります。

この他にも、build, environment, depends_onなど様々な属性がservicesの中で使えます。

servicesセクションの書き方と主要パターン

このセクションでは、compose.yamlの中心となるservicesセクション（各サービスの定義方法）およびよく使うオプションを具体的に解説します。

なぜなら、servicesセクションはDocker Composeの肝であり、ここを理解すればほとんどの設定が自信を持って書けるからです。

imageとbuildの使い分け

サービス定義で核になるのが image および build キーです。

imageはDockerHub等の既存イメージ指定、buildはカスタムDockerfileを使う時指定します。

併用（build＋imageも同時に書く）することで、「このDockerfileからビルドしたイメージに指定名（タグ）を付けてね」と明示でき、CI/CDパイプラインでのイメージ管理にも最適です。


services:
  app:
    build: ./src
    image: myorg/myapp:1.0 # この指定があるとレジストリプッシュにも連携しやすい

環境変数とenv_fileで機密管理

バージョンやパスワードなどの設定値は environment か env_file で渡せます。

env_fileにしておくと機密値（APIキーやDBのパスワード）を.gitignore管理しやすく、本番や開発など環境ごとに切り替えも便利です。


services:
  db:
    image: postgres:14-alpine
    environment:
      POSTGRES_DB: mydb
    env_file:
      - ./.env

.env ファイルはバージョン管理から除外し、本番はDocker Secretsを利用するのが推奨です。

詳しくはDocker ComposeでMySQLを使う方法｜コード例付きも参考にどうぞ。

ポート・ネットワーク・ボリュームの記述法

外部からアクセスするAPIやWebアプリのサービスは ports でホスト→コンテナへのマッピングを行います。

networksはサービス間の接続範囲を制御するために利用し、volumesは永続ストレージを提供します。


services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    networks:
      - frontend
    volumes:
      - ./app:/usr/share/nginx/html

enetworks:
  frontend: {}

依存関係（depends_on＋healthcheck）のベストプラクティス

サービス間の起動順制御には depends_on を使い、healthcheck を組み合わせることで「DBなど内部プロセスが完全に起動してからアプリを起動する」制御が可能になります。

従来のdepends_onは単なる起動順制御でしたが、condition: service_healthy を加えるとアプリケーションの起動のタイミングも安全に制御できます。


services:
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

この仕組みは、特に「初めてDBコンテナを立ち上げる時に接続エラー」というつまずきを防ぎます。

開発現場で役立つcompose.yaml 実践Tips

このセクションでは、実務やハンズオン学習ですぐに使えるcompose.yamlの書き方・発展テクニックを紹介します。

背景には、「設定の使い回しや開発・本番切り分け」「複雑なサービス構成の管理」が必要になる場面が多いからです。

開発・本番で設定を分ける方法（複数ファイルのマージ）

compose.yaml＋compose.override.yamlなど複数ファイルを作成し、docker composeコマンドの-fオプションでマージするのが主流です。

たとえば、開発用はバインドマウント、デバッグ、ポート公開、本番用は最小限公開と役割を分離できます。


# compose.yaml（共通設定）
services:
  app:
    image: myorg/app:latest

# compose.override.yaml（開発用）
services:
  app:
    ports:
      - "3000:3000"
    volumes:
      - ./src:/app/src

docker compose up だけで両者が自動的にマージされ、環境ごとに柔軟に対応可能です。

profiles/extends/includeによる設定の再利用

profilesを使えば「テスト用サービスだけ起動」「デバッグ時だけphpmyadminを追加起動」といった柔軟制御も一発です。


services:
  backend:
    image: my-backend
  db:
    image: mysql
  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

extendsやincludeで設定をモジュール化・チーム共有することもできます。

YAMLアンカー＋extendsは似ているようで役割が違うため、状況に応じて賢く使い分けましょう。

watchモードでライブリロードを実現

docker compose up –watch を使うと、ホスト側ファイルの変更を即座にコンテナに反映して、ライブコーディング・ホットリロード開発が快適にできます。

srcやconfigファイルごとに sync・rebuild・sync+restart のアクションを分けて設定できるのが強みです。


services:
  frontend:
    build: ./frontend
    develop:
      watch:
        - path: ./frontend/src
          action: sync
          target: /app/src
        - path: ./frontend/package.json
          action: rebuild

従来のバインドマウントよりもパフォーマンス＆安定性に優れた現代的な開発手法になりつつあります。

よくある実践例とdocker-compose.ymlサンプル集

このセクションでは、さまざまな用途で役立つdocker-compose.yml（compose.yaml）の具体的な書き方サンプルを紹介します。

理由は、「実際のユースケースを自分の環境に合わせてまねる」のが初学者や現場エンジニアのテクニック向上に直結するからです。

WordPress＋MySQLのサンプル

Web開発学習、業務用WordPressサイトの立ち上げで人気な構成例です。（参照：awesome-compose）


services:
  db:
    image: mariadb:10.6
    command: '--default-authentication-plugin=mysql_native_password'
    volumes:
      - db_data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=somewordpress
      - MYSQL_DATABASE=wordpress
      - MYSQL_USER=wordpress
      - MYSQL_PASSWORD=wordpress
    expose:
      - 3306
  wordpress:
    image: wordpress:latest
    volumes:
      - wp_data:/var/www/html
    ports:
      - "8080:80"
    environment:
      - WORDPRESS_DB_HOST=db
      - WORDPRESS_DB_USER=wordpress
      - WORDPRESS_DB_PASSWORD=wordpress
      - WORDPRESS_DB_NAME=wordpress
    depends_on:
      - db
volumes:
  db_data:
  wp_data:

解説：サービス名がDNS解決されるので、WORDPRESS_DB_HOST=db のような指定でOK。ボリューム利用でデータが消える心配もありません。

さらに詳しいWordPress活用例はDockerでWordPressを立ち上げる方法｜具体例・解説付きもどうぞ。

Node.js + PostgreSQLの開発環境

APIサーバー＋DBの定番セット。ホストのsrcをマウントしnodemonでライブリロードのコツを紹介します。


services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: node-postgres-api:dev
    ports:
      - "3000:3000"
    volumes:
      - ./src:/usr/src/app/src
      - /usr/src/app/node_modules
    env_file:
      - ./.env
    environment:
      - NODE_ENV=development
    depends_on:
      postgres:
        condition: service_healthy
    command: npm run dev
  postgres:
    image: postgres:14.1-alpine
    restart: always
    env_file:
      - ./.env
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $POSTGRES_USER"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  postgres-data:

この例ではnode_modulesを匿名ボリュームで上書きし、OS差異によるバグを防止。DBサービスのhealthcheckと連動したdepends_onで失敗しづらい起動順に整えています。

Node.js環境詳細や応用例はDockerでNode.jsを扱う方法｜Dockerfile例付きもおすすめです。

Nginxリバースプロキシで複数サービス分岐

マイクロサービスや本格的なAPI構成に不可欠な「Nginxが各サービスへリクエストを分配」するケースを紹介します。


services:
  proxy:
    image: nginx:1.25-alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "80:80"
    networks:
      - app-network
    depends_on:
      - service-a
      - service-b
  service-a:
    image: my-service-a:latest
    networks:
      - app-network
  service-b:
    image: my-service-b:latest
    networks:
      - app-network
networks:
  app-network:
    driver: bridge

サンプルnginx.confでは location /api/a/ で service-a:8080 に転送、と柔軟なリバースプロキシが実現できます。

「本番に向けたセキュリティや構成の工夫」はDockerでNginxを利用する方法｜具体例付きで丁寧に解説でも触れています。

docker compose コマンドの基礎とエラー対策

このセクションでは、compose.yamlの作成・デバッグ・運用に欠かせないdocker composeコマンド群と「やりがちなエラー」「トラブル時の対策」をまとめます。

これは、新人・現場問わず「起動できない・設定が反映されない・謎エラー」などに出くわす機会が多いからです。

よく使うdocker composeコマンドとオプション

主なコマンドと使い分け例は以下の通りです（参照: 公式CLIリファレンス）。

プロジェクトごとの分離や複数ファイルの組み合わせ時は-p, -f, –profileなどグローバルオプションも効果的です。

典型的なエラー・トラブルと解決策

、インデント・コロン抜け・versionキー混在など細かいミスが初学者の失敗パターン1位です。

構文エラー時はdocker compose configで「意図した設定か/どこでパースエラーが出てるか」をチェックないしYAML lintツールを事前活用をおすすめします。

また、depends_onの罠（DB準備が遅い/healthcheck未設定）、イメージタグ:latestのまま（予期せぬバージョン障害）、環境変数エスケープ漏れなども失敗しやすいポイントです。

解消のコツとしては「公式ドキュメントの該当セクションを確認+構成を小さくして一つずつ積み上げる」のが王道です。

まとめ

この記事で押さえておきたい重要ポイントは次の3つです。

現場に出る・受託案件を進める・自分の開発を加速したい方も、docker-composeを積極的に活用し、効率的なインフラ管理を実現してください！

さらに一歩踏み込んだクラウド活用やサーバー選びも検討したい方はDigitalOceanなどもぜひチェックしてみてください。

モバイルバージョンを終了