Docker Compose 基本と最新仕様 – V2への移行とベストプラクティス

2026年6月2日

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

エンジニアの世界では、「いつでも動ける状態を作っておけ」とよく言われます。
技術やポートフォリオがあっても、自分に合う案件情報を日常的に見れていないと、いざ動こうと思った時に比較や判断が難しくなってしまいます。
普段から案件情報が集まる環境を作っておくと、良い案件が出た時にすぐ動きやすくなりますよ。
筆者自身も、メガベンチャー勤務時代に年収1,500万円を超えた経験があります。振り返ると、技術だけでなく「どんな案件や働き方があるか」を日頃から見ていたことが、キャリアの選択肢を広げるきっかけになりました。
このブログを読んでくれた方に感謝を込めて、実際に使っている情報収集サービスを紹介します。

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

Contents

1 Docker Compose の基本と最新仕様
2 サービス構成パターン：シングル vs マルチ
3 ビルド・イメージ管理・環境変数・ボリューム活用法
4 実務で必須のオプションとネットワーク設計
- 4.1 depends_on・healthcheck・restart の実装例
- 4.2 ネットワーク分離と外部ネットワーク活用例
5 シークレット管理の実践例（Swarm 非対応でも安全に）
6 Docker Desktop での基本操作とトラブルシューティング

スポンサードリンク

Docker Compose の基本と最新仕様

Docker Compose は 複数コンテナを 1 つの YAML ファイルで宣言的に管理 できるツールです。2026 年時点では CLI が Compose V2 に統合され、ファイル形式は Compose Specification（バージョン番号不要）を推奨しています。本セクションでは、最新仕様の全体像と従来との主な違いを整理し、実務で迷わないためのポイントを解説します。

Compose ファイルの基本構造

Compose ファイルはトップレベルに 4 つのキー を持ちます。以下はそれぞれの役割と最小構成例です（インデント・コメントは統一しています）。

# docker-compose.yml （バージョン省略が推奨）
services:                     # コンテナ定義本体
  app:
    image: node:20-alpine

networks:                     # サービス間通信を司る論理ネットワーク
  default:

volumes:                      # 永続化データ用のボリューム宣言
  data:

# docker-compose.yml （バージョン省略が推奨）

services: # コンテナ定義本体

app:

image: node:20-alpine

networks: # サービス間通信を司る論理ネットワーク

default:

volumes: # 永続化データ用のボリューム宣言

data:

services：起動対象コンテナとその設定。
networks：明示的に定義しなくても default が自動生成されますが、分離したい場合はここで名前を付けます。
volumes：永続化領域を Docker が管理する named volume を宣言します。

ポイント：version: フィールドは省略可能です。Docker はファイルを自動的に最新仕様として解釈し、非推奨構文の使用を防ぎます。

バージョン指定の変遷とベストプラクティス

時期	記述方法	主な特徴
Compose V1（2020 以前）	`version: "3.9"` 必須	スキーマが固定、拡張性が低い
Compose V2（現在）	`version:` 省略可	プラグインで機能追加可能、CLI が統合

結論：新規プロジェクトは バージョン行を削除 した形で作成し、将来の互換性を確保してください。

Compose V2 と従来 v3.9 の比較

以下の表は、CLI の実装とファイル形式の違いをまとめたものです。表の前に簡単な説明文を入れています。

比較ポイント：主に「バージョン指定」「拡張性」「ネットワーク自動生成」の観点で差異があります。

項目	Compose V2（CLI）	従来 v3.9 形式
`version` フィールド	任意・省略可	必須（非推奨）
プラグイン拡張	`docker compose plugin install <name>` で追加可能	スキーマ固定
デフォルトネットワーク	自動作成 (`bridge`) が標準	明示的に `default` 必要
シークレット管理	BuildKit の `--secret` と組み合わせて利用可	Swarm 専用 `secrets:` キーのみ

サービス構成パターン：シングル vs マルチ

プロジェクト規模や開発フェーズに応じて 単一サービス、または 複数サービス の構成を選択します。ここでは代表的な実装例と、依存関係・起動順序のベストプラクティスを示します。

最小構成のシングルサービス（Nginx）

単体コンテナで動作確認したい場合の最短例です。ports によるポートマッピングだけで完結します。

services:
  web:
    image: nginx:stable-alpine
    ports:
      - &quot;8080:80&quot;   # ホスト 8080 → コンテナ 80

services:

web:

image: nginx:stable-alpine

ports:

- "8080:80" # ホスト 8080 → コンテナ 80

ポイント：この形はローカル開発やデモ環境での「すぐに起動」向けです。

Node.js + MySQL の典型スタック

アプリと DB を別サービスとして定義し、depends_on と healthcheck で安全な起動順序を実現します。

services:
  api:
    build: ./api                 # Dockerfile が存在するディレクトリ
    environment:
      - DB_HOST=mysql
      - DB_USER=${MYSQL_USER}
      - DB_PASSWORD=${MYSQL_PASSWORD}
    depends_on:
      mysql:
        condition: service_healthy
    ports:
      - &quot;3000:3000&quot;

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: appdb
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: [&quot;CMD&quot;, &quot;mysqladmin&quot;, &quot;ping&quot;, &quot;-h&quot;, &quot;localhost&quot;]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  db_data:

services:

api:

build: ./api # Dockerfile が存在するディレクトリ

environment:

- DB_HOST=mysql

- DB_USER=${MYSQL_USER}

- DB_PASSWORD=${MYSQL_PASSWORD}

depends_on:

mysql:

condition: service_healthy

ports:

- "3000:3000"

mysql:

image: mysql:8.0

environment:

MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}

MYSQL_DATABASE: appdb

MYSQL_USER: ${MYSQL_USER}

MYSQL_PASSWORD: ${MYSQL_PASSWORD}

volumes:

- db_data:/var/lib/mysql

healthcheck:

test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]

interval: 10s

timeout: 5s

retries: 3

volumes:

db_data:

ポイント：healthcheck が成功するまで api は待機し、接続失敗を防げます。

Flask + Redis のバックエンド API パターン

環境変数は .env に外部化し、env_file で一括読み込みします。

services:
  web:
    build: ./flask_app
    env_file: ./.env
    ports:
      - &quot;5000:5000&quot;
    depends_on:
      redis:
        condition: service_started

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    command: [&quot;redis-server&quot;, &quot;--appendonly&quot;, &quot;yes&quot;]

volumes:
  redis_data:

services:

web:

build: ./flask_app

env_file: ./.env

ports:

- "5000:5000"

depends_on:

redis:

condition: service_started

redis:

image: redis:7-alpine

volumes:

- redis_data:/data

command: ["redis-server", "--appendonly", "yes"]

volumes:

redis_data:

ポイント：env_file に書かれた変数はコンテナ内部で自動的に展開されます。

Nginx リバースプロキシ＋複数コンテナ構成

フロントエンド・バックエンドを統合し、外部ネットワーク public を経由してホストと通信させる例です。external: true の意味は公式ドキュメント（Docker Engine reference – network create）で確認できます。

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - &quot;80:80&quot;
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - frontend
      - backend

  frontend:
    build: ./frontend
    networks:
      - internal

  backend:
    build: ./backend
    networks:
      - internal

networks:
  internal:
    driver: bridge               # プライベート通信専用
  public:
    external: true                # Docker Desktop のデフォルトブリッジ (bridge) を再利用

services:

nginx:

image: nginx:stable-alpine

ports:

- "80:80"

volumes:

- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

depends_on:

- frontend

- backend

frontend:

build: ./frontend

networks:

- internal

backend:

build: ./backend

networks:

- internal

networks:

internal:

driver: bridge # プライベート通信専用

public:

external: true # Docker Desktop のデフォルトブリッジ (bridge) を再利用

ポイント：public は既存のブリッジネットワークを共有するため、外部 API やホスト側ツールとの連携が容易です。

ビルド・イメージ管理・環境変数・ボリューム活用法

実務では ビルド方式の選択 と 機密情報の安全な取り扱い が鍵になります。この章でそれぞれのベストプラクティスを具体例と共に示します。

`build` と `image` の使い分け

用途	設定例
ソースからイメージ生成（開発・CI）	`build:` に `context` と `dockerfile` を指定
既製イメージの利用（本番）	`image:` にレジストリタグを記述

services:
  custom-app:
    build:
      context: ./app
      dockerfile: Dockerfile.prod
    # ビルド時に自動生成されるタグは &lt;project&gt;_custom-app

  redis-cache:
    image: redis:7-alpine

services:

custom-app:

build:

context: ./app

dockerfile: Dockerfile.prod

# ビルド時に自動生成されるタグは <project>_custom-app

redis-cache:

image: redis:7-alpine

ポイント：ローカル開発では build、本番環境では CI が作成したレジストリイメージを image: で参照するのが管理しやすいです。

`.env` による環境変数の一元管理

機密情報は .gitignore に追加し、チームごとにローカルで保持します。以下はサンプルです。

# .env (Git 管理外)
MYSQL_ROOT_PASSWORD=StrongP@ssw0rd
MYSQL_DATABASE=myapp
MYSQL_USER=appuser
MYSQL_PASSWORD=UserP@ss

# .env (Git 管理外)

MYSQL_ROOT_PASSWORD=StrongP@ssw0rd

MYSQL_DATABASE=myapp

MYSQL_USER=appuser

MYSQL_PASSWORD=UserP@ss

Compose 側の記述はシンプルです。

services:
  db:
    image: mysql:8.0
    env_file: ./.env   # 全変数を自動ロード

services:

db:

image: mysql:8.0

env_file: ./.env # 全変数を自動ロード

ポイント：env_file はファイル全体をインポートするので、個別に environment: を書く手間が省けます。

永続化ボリュームの種類と設定例

種類	特徴	推奨シーン
named volume	Docker が管理し、バックアップや移行が容易	本番データベース・永続ストレージ
bind mount	ホストディレクトリを直接マウント。コード変更が即時反映	ローカル開発・ホットリロード

services:
  db:
    image: postgres:15-alpine
    volumes:
      - pg_data:/var/lib/postgresql/data   # named volume

  web:
    build: ./web
    volumes:
      - ./src:/app/src                     # bind mount（開発向け）

volumes:
  pg_data:

services:

db:

image: postgres:15-alpine

volumes:

- pg_data:/var/lib/postgresql/data # named volume

web:

build: ./web

volumes:

- ./src:/app/src # bind mount（開発向け）

volumes:

pg_data:

ポイント：本番は named volume、ローカルは bind mount を組み合わせると安全かつ高速です。

実務で必須のオプションとネットワーク設計

コンテナ運用では 起動順序・ヘルスチェック・再起動ポリシー、そして ネットワーク分離 が重要です。以下に具体的な設定例を示します。

`depends_on`・`healthcheck`・`restart` の実装例

services:
  api:
    build: ./api
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped          # 開発機の再起動時も自動復帰
    healthcheck:
      test: [&quot;CMD&quot;, &quot;curl&quot;, &quot;-f&quot;, &quot;http://localhost:3000/health&quot;]
      interval: 15s
      timeout: 5s
      retries: 4

  db:
    image: postgres:15-alpine
    restart: on-failure
    healthcheck:
      test: [&quot;CMD-SHELL&quot;, &quot;pg_isready -U ${POSTGRES_USER}&quot;]
      interval: 10s
      timeout: 3s
      retries: 5

services:

api:

build: ./api

depends_on:

db:

condition: service_healthy

restart: unless-stopped # 開発機の再起動時も自動復帰

healthcheck:

test: ["CMD", "curl", "-f", "http://localhost:3000/health"]

interval: 15s

timeout: 5s

retries: 4

db:

image: postgres:15-alpine

restart: on-failure

healthcheck:

test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]

interval: 10s

timeout: 3s

retries: 5

ポイント：restart: unless-stopped は開発マシンの再起動時にコンテナを自動で復帰させ、手作業を減らします。

ネットワーク分離と外部ネットワーク活用例

内部サービスはプライベート internal ネットワークに閉じ、外部 API と通信が必要なものだけ public に参加させます。public は Docker Desktop がデフォルトで提供するブリッジネットワークを再利用します（公式参照: https://docs.docker.com/engine/reference/commandline/network_create/#options）。

services:
  backend:
    build: ./backend
    networks:
      - internal

  frontend:
    build: ./frontend
    networks:
      - internal
      - public   # 公開ポートは外部ネットワーク経由で提供

networks:
  internal:
    driver: bridge
  public:
    external: true

services:

backend:

build: ./backend

networks:

- internal

frontend:

build: ./frontend

networks:

- internal

- public # 公開ポートは外部ネットワーク経由で提供

networks:

internal:

driver: bridge

public:

external: true

ポイント：internal は他サービスからのみアクセス可能。攻撃面を最小化しつつ、必要な通信だけ public に露出させます。

シークレット管理の実践例（Swarm 非対応でも安全に）

Docker Desktop の GUI では Secrets 機能が Swarm 専用で利用できません。その代わりに BuildKit の --secret オプション を組み合わせると、ビルド時に機密情報をコンテナ内部へ安全に流し込めます。以下は実際の手順です。

1. シークレットファイルを用意

# .db_pass（Git 管理外）
SuperSecretPassword123!

# .db_pass（Git 管理外）

SuperSecretPassword123!

.gitignore に .db_pass を追加してください。

2. Dockerfile 側でシークレットを参照

# syntax=docker/dockerfile:1.4   ← BuildKit が必要な宣言

FROM node:20-alpine AS builder
ARG DB_PASSWORD        # ビルド時に渡すシークレット名
RUN --mount=type=secret,id=db_password \
    cat /run/secrets/db_password &gt; /tmp/password.txt &amp;&amp; \
    echo &quot;Using password from secret&quot;   # 実際の処理例

# 以降は通常通りビルドを続行

# syntax=docker/dockerfile:1.4 ← BuildKit が必要な宣言

FROM node:20-alpine AS builder

ARG DB_PASSWORD # ビルド時に渡すシークレット名

RUN --mount=type=secret,id=db_password \

cat /run/secrets/db_password > /tmp/password.txt && \

echo "Using password from secret" # 実際の処理例

# 以降は通常通りビルドを続行

3. Compose で BuildKit ビルドを実行

services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile
      secrets:
        - db_password   # secret 名とファイルパスは下記で紐付け

secrets:
  db_password:
    file: .db_pass

services:

app:

build:

context: ./app

dockerfile: Dockerfile

secrets:

- db_password # secret 名とファイルパスは下記で紐付け

secrets:

db_password:

file: .db_pass

コマンド例:

DOCKER_BUILDKIT=1 docker compose build --ssh default --secret id=db_password,src=.db_pass

1 2	DOCKER_BUILDKIT=1 docker compose build --ssh default --secret id=db_password,src=.db_pass

ポイント：シークレットはビルドプロセスの中だけで利用され、最終イメージには残りません。実行時に環境変数として渡す場合は docker compose up -d 時に同様の --env-file を併用してください。

Docker Desktop での基本操作とトラブルシューティング

Docker Desktop は GUI と CLI のハイブリッド環境です。以下は日常的に使用するコマンドと、よくあるエラーへの対処法です。

基本コマンド一覧

コマンド	説明
`docker compose up -d`	定義されたサービスをバックグラウンド起動
`docker compose down`	コンテナ・ネットワーク・ボリューム（オプション）を削除
`docker compose logs -f`	リアルタイムで全コンテナのログを見る
`docker compose exec <svc> sh`	起動中コンテナにシェル接続

GUI でも同等操作が可能ですが、CI/CD や自動化では CLI が必須 です。

よくあるエラーと公式ドキュメントでの対処法

エラーメッセージ	原因例	推奨対策（公式リンク）
`Error starting userland proxy` (ポート競合)	ホスト側で同じポートが使用中	`docker compose ps` で確認し、`ports` のマッピング先を変更。参照: https://docs.docker.com/compose/networking/
`permission denied`（ボリューム権限）	macOS/Windows とコンテナ UID が不一致	ボリュームオプションに `cached` / `delegated` を付与、または Docker Desktop の File Sharing 設定で対象ディレクトリを追加。参照: https://docs.docker.com/desktop/mac/#file-sharing
`healthcheck failed repeatedly`	起動待ち時間が短すぎる	`interval`, `timeout`, `retries` を長めに設定し、実際の起動ログで遅延を測定。参照: https://docs.docker.com/engine/reference/builder/#healthcheck

ポイント：エラーメッセージはそのまま検索すると公式ドキュメントや GitHub Issue がヒットしやすいので、まずは Google / DuckDuckGo で検索しましょう。

設定ファイルの分割と CI/CD への組み込み

設定ファイル分割
docker-compose.yml … 共通ベース
docker-compose.override.yml … ローカル開発用上書き（IDE が自動適用）
docker-compose.prod.yml … 本番環境向け設定

実行例:

bash docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

シークレットの安全な取り扱い（上記 BuildKit 参照）
CI/CD パイプライン
GitHub Actions の docker/compose-action を使用し、docker compose build --push → レジストリへプッシュ。
デプロイステップは docker compose pull && docker compose up -d で実行。

結論：ファイル分割と BuildKit によるシークレット管理を組み合わせれば、ローカル開発から本番デプロイまで同一の Compose 定義を安全に再利用できます。

スポンサードリンク

もっとスキルを活かしたいエンジニアへ

スポンサードリンク

働き方から選べる

無料で使えて良質な案件の情報収集ができるサービス

フルリモート・週3日・高単価、どんな条件も妥協したくないなら

フリーランスボードに無料会員登録する

利用者10万人以上。業界最大規模45万件の案件。AIマッチ機能や無料の相場情報が人気。

年収800万円以上のキャリアアップ・ハイクラス正社員を視野に入れているなら

Beyond Careerに無料相談する

内定獲得率90%以上。紹介先企業とは役員クラスのコネクションがある安心と信頼できるエージェント。

-Docker

comment コメントをキャンセル

: Docker

M1 MacへDocker Desktopをインストールする手順と要件

M1 Mac（Apple Silicon）でDocker Desktopを動かすためのシステム要件確認からインストール、初期設定、よくあるトラブル対策までをわかりやすく紹介します。

: Docker

Docker Desktop 4.28 の macOS Ventura・Sonoma・Sequoia 対応とインストールガイド

Docker Desktop 4.28 が macOS Ventura・Sonoma・Sequoia に対応し、Apple Silicon と Intel のシステム要件や公式 DMG と Homebrew Cask のインストール方法、初回設定とトラブルシューティングをまとめました。

: Docker

Docker 環境構築と実務で使える CI/CD パイプライン完全ガイド

Docker 環境構築 + CI/CD パイプラインを実務ですぐに使える形でまとめました。

: Docker

Docker クライアントとデーモンの API バージョン不一致対策 – 2025‑2026 最新環境

Docker クライアントとデーモン間の API バージョン不整合によるエラーの原因と、バージョン確認・環境変数設定・Desktop 再起動・Engine アップグレード／ダウングレードの具体的手順をまとめました。

: Docker

Docker Desktopでマルチコンテナ構成とGitHub Actions CI/CDを実装する手順

Docker Desktop をローカルにインストールし、マルチステージ Dockerfile と docker‑compose でマルチコンテナ環境を構築し、GitHub Actionsで自動デプロイまで実現する方法をご紹介します。

Gravity Sketch vs Blender 2026比較ガイド

保育園ICT導入比較｜CoDMONの三大機能と費用対効果

Docker Compose 基本と最新仕様 – V2への移行とベストプラクティス

Docker Compose の基本と最新仕様

Compose ファイルの基本構造

バージョン指定の変遷とベストプラクティス

Compose V2 と従来 v3.9 の比較

サービス構成パターン：シングル vs マルチ

最小構成のシングルサービス（Nginx）

Node.js + MySQL の典型スタック

Flask + Redis のバックエンド API パターン

Nginx リバースプロキシ＋複数コンテナ構成

ビルド・イメージ管理・環境変数・ボリューム活用法

build と image の使い分け

.env による環境変数の一元管理

永続化ボリュームの種類と設定例

実務で必須のオプションとネットワーク設計

depends_on・healthcheck・restart の実装例

ネットワーク分離と外部ネットワーク活用例

シークレット管理の実践例（Swarm 非対応でも安全に）

1. シークレットファイルを用意

2. Dockerfile 側でシークレットを参照

3. Compose で BuildKit ビルドを実行

Docker Desktop での基本操作とトラブルシューティング

基本コマンド一覧

よくあるエラーと公式ドキュメントでの対処法

設定ファイルの分割と CI/CD への組み込み

`build` と `image` の使い分け

`.env` による環境変数の一元管理

`depends_on`・`healthcheck`・`restart` の実装例