Contents
1️⃣ Compose プラグインの取得と配置
1.1 Docker Desktop を利用している場合 (Windows / macOS)
Docker Desktop（現在の安定版）には Compose プラグインが標準で同梱 されています。追加作業は不要です。
| OS | 確認コマンド |
|---|---|
| Windows | docker compose version |
| macOS | docker compose version |
Docker Desktop のバージョンが古い場合は、アプリ内の「Settings → General」から自動更新を有効にしてください。
1.2 Linux（または Docker Engine 単体）で手動インストールする場合
Linux 環境ではプラグインを 公式 GitHub リリース から取得し、CLI が検索できるディレクトリへ配置します。
| 項目 | 推奨パス例 |
|---|---|
| デフォルト (多くのディストリビューション) | /usr/local/lib/docker/cli-plugins |
| ユーザー単位でインストールしたいとき | $HOME/.docker/cli-plugins |
ポイント：プラグインは実行権限が付与された状態で配置し、ディレクトリが
PATHに含まれているか確認してください。
手順（Linux 共通）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# 1. 最新リリースのタグ名を取得 VERSION=$(curl -sSf https://api.github.com/repos/docker/compose/releases/latest \ | grep '"tag_name":' | cut -d '"' -f4) # 2. アーキテクチャに合わせたバイナリをダウンロード ARCH=$(uname -m) case "$ARCH" in x86_64) FILE=docker-compose-linux-x86_64 ;; aarch64) FILE=docker-compose-linux-aarch64 ;; *) echo "Unsupported architecture: $ARCH"; exit 1 ;; esac curl -SL "https://github.com/docker/compose/releases/download/${VERSION}/${FILE}" \ -o docker-compose # 3. 実行権限を付与し、プラグインディレクトリへ配置 chmod +x docker-compose sudo mkdir -p /usr/local/lib/docker/cli-plugins sudo mv docker-compose /usr/local/lib/docker/cli-plugins/docker-compose # 4. 配置が正しく認識されたか確認 docker compose version # 例: Docker Compose version v2.28.0 |
macOS（Homebrew がインストール済みの場合）
|
1 2 3 |
brew install docker-compose # Homebrew がプラグインとして配置してくれます docker compose version |
Windows（PowerShell）
- Docker Desktop を利用しない場合は、以下の手順でプラグインを取得。
- バイナリは
C:\Program Files\Docker\cli-pluginsに配置。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# 1. 最新バージョン取得 $version = (Invoke-RestMethod -Uri https://api.github.com/repos/docker/compose/releases/latest).tag_name # 2. ダウンロード（x86_64 用） $url = "https://github.com/docker/compose/releases/download/$version/docker-compose-windows-x86_64.exe" Invoke-WebRequest -Uri $url -OutFile docker-compose.exe # 3. 配置 $dest = "$Env:ProgramFiles\Docker\cli-plugins\docker-compose.exe" Move-Item -Force docker-compose.exe $dest # 4. バージョン確認 docker compose version |
注意：Windows 環境で PowerShell の実行ポリシーが制限されている場合は、
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser等で緩和してください。
2️⃣ version: フィールドの扱いと推奨設定
2.1 現在の Compose Specification の位置付け
Compose Specification（compose-spec.io）は バージョン非依存 を目指した設計です。そのため、docker-compose.yml に version: キーを記述しなくても構文エラーにならないように実装されています。
重要：
version:を省略すると「最新の仕様でパース」されますが、将来的に 新しいフィールドや制約が追加された場合 は、既存ファイルが意図しない動作をする可能性があります。
したがって 「必ず互換性が保たれる」 と断言できませんが、現在のベストプラクティスとしては省略して問題ありません。
2.2 推奨記述例
|
1 2 3 4 5 6 |
# version: "3.9" ← 省略可（任意） services: web: image: nginx:alpine ports: ["8080:80"] |
- 利点
- ファイルがシンプルになる。
-
docker compose config実行時に自動で最新スキーマが適用され、余計なバリデーションエラーを回避できる。 -
留意点
- 大規模プロジェクトや長期間運用するシステムでは、使用している Compose Spec のバージョンを明示的に管理（例：CI パイプラインで
compose spec validate）すると安全です。
3️⃣ docker compose と従来の docker‑compose の主な違い
| 項目 | 従来 (docker‑compose) |
現行 (docker compose) |
|---|---|---|
| 実行形式 | 独立したバイナリ | Docker CLI に組み込まれたサブコマンド |
| 設定ファイルのデフォルト名 | docker-compose.yml |
同上 |
| バージョン管理 | version: が必須（過去は必須） |
任意（仕様非依存） |
| 拡張機能 | プラグイン方式が限定的 | profiles, extensions などの新機能をサポート |
| コマンドヘルプ | docker-compose --help |
docker compose --help |
ポイント：CLI が一本化されたことで、スクリプトや CI/CD の記述が統一され、エラーメッセージも Docker Engine と同様の形式になるためデバッグが容易です。
4️⃣ v2 固有機能と実践的な活用例
4.1 profiles（サービス群の切り替え）
|
1 2 3 4 5 6 7 8 9 |
services: app: build: ./app ports: ["8080:80"] profiles: [dev] # 開発時だけ起動したい場合に指定 redis: image: redis:7-alpine profiles: [prod] # 本番環境でのみ使用 |
- 開発モード：
docker compose --profile dev up -d - 本番モード：
docker compose --profile prod,dev up -d（複数指定可）
4.2 extensions（実験的機能の宣言）
Compose Specification が提供する拡張は、現行安定版ではオプション扱いです。以下は 実験的に利用できる例 であり、必須ではありません。
|
1 2 3 4 5 6 7 8 9 10 |
services: app: image: myapp:latest # extensions は Docker Engine がサポートしている場合のみ有効になる extensions: x-logging: driver: json-file options: max-size: "10m" |
注意：
extensions:にcompose-spec: {}とだけ書くと、現在の安定版 Docker Engine では無視されます。実際に使う拡張機能は公式ドキュメントで対応状況を確認してください。
4.3 healthcheck の記述例
|
1 2 3 4 5 6 7 8 9 |
services: redis: image: redis:7-alpine healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 10s timeout: 5s retries: 3 |
depends_on: と併用すると、依存サービスは 健康状態が “healthy” になるまで待機します。
4.4 シークレット管理（Docker Swarm / Kubernetes 向け）
|
1 2 3 4 5 6 7 8 9 10 11 |
secrets: db_password: external: true # 外部シークレットストアに委譲 services: app: image: myapp:latest secrets: - source: db_password target: /run/secrets/db_password |
- 作成手順（Swarm）
bash
echo "s3cr3t" | docker secret create db_password -
4.5 マルチステージ Dockerfile の例（Flask アプリ）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# ---------- Build stage ---------- FROM python:3.12-slim AS builder WORKDIR /src COPY requirements.txt . RUN pip install --user -r requirements.txt # ---------- Runtime stage ---------- FROM python:3.12-alpine WORKDIR /app ENV PATH=/root/.local/bin:$PATH COPY --from=builder /root/.local /root/.local COPY . . CMD ["python", "main.py"] |
マルチステージ構成により ビルドツールが最終イメージに残らない ため、サイズ削減とセキュリティ向上が同時に実現できます。
5️⃣ 実践チュートリアル：Flask + Redis のマルチコンテナ構成
5.1 ディレクトリ構成
|
1 2 3 4 5 6 7 |
flask-redis-demo/ ├─ app/ │ ├─ Dockerfile │ ├─ main.py │ └─ requirements.txt └─ docker-compose.yml |
app/requirements.txt
|
1 2 3 |
Flask==3.0.0 redis==5.0.1 |
app/main.py（先ほどと同様）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
from flask import Flask import redis app = Flask(__name__) r = redis.Redis(host='redis', port=6379) @app.route('/') def hello(): r.incr('hits') return f'Hello! This page has been visited {r.get("hits").decode()} times.' if __name__ == '__main__': app.run(host='0.0.0.0', port=80) |
docker-compose.yml（profiles と healthcheck を活用）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
services: app: build: ./app ports: - "8080:80" depends_on: redis: condition: service_healthy # 健康状態を待機 profiles: [dev, prod] redis: image: redis:7-alpine healthcheck: test: ["CMD", "redis-cli", "ping"] interval: 5s timeout: 3s retries: 4 profiles: [prod] # 本番環境で必ず起動 # 任意でネットワーク名を明示的に指定（衝突回避） networks: default: name: ${COMPOSE_PROJECT_NAME}_default |
5.2 起動手順
|
1 2 3 4 5 |
cd flask-redis-demo docker compose --profile dev up -d # 開発モードで起動 # もしくは docker compose --profile prod up -d # 本番モード（Redis も含む） |
ブラウザで http://localhost:8080/ にアクセスすると、訪問回数がインクリメントされて表示されます。
6️⃣ トラブルシューティングとベストプラクティス
| 症状 | 確認ポイント | 解決策 |
|---|---|---|
docker compose: command not found |
プラグイン配置先が CLI の検索パスに含まれているか | - Linux：echo $PATH \| grep cli-plugins - Windows：環境変数 Path に C:\Program Files\Docker\cli-plugins があるか |
| コンテナ起動時に ネットワーク名が競合 | docker network ls で同名ネットワークが複数存在しないか |
networks: セクションでプロジェクト変数 ${COMPOSE_PROJECT_NAME} を使用して名前空間を分離 |
depends_on が期待通りに待機しない |
対象サービスの healthcheck が正しく定義されているか | docker compose logs <service> でヘルスチェック結果を確認、必要なら interval/retries を調整 |
docker compose config の出力に不明なフィールドがある |
extensions: に実験的キーを書いていないか |
実験的拡張は 公式のサポート情報 と照らし合わせ、不要なら削除 |
追加ベストプラクティス
-
CI/CD パイプラインでバージョン固定
docker compose versionの出力を CI のビルドログに残すことで、環境差異による不具合を早期検知できます。 -
Compose ファイルは YAML Linter で事前検証
bash
docker run --rm -i mikefarah/yq yq eval '.' - < docker-compose.yml -
環境変数の管理は
.envファイルか Docker Secret を推奨。平文でパスワードを書かないように注意。
7️⃣ まとめ（要点）
- インストール
- Docker Desktop → 何もしなくても利用可能。
-
Linux・Windows の手動インストールは、公式リリースからバイナリを取得し OS に合わせたプラグインディレクトリへ配置するだけで完了。
-
version:フィールド - 現行の Compose Specification は非依存設計なので省略可能。
-
将来的な仕様変更に備えて、長期運用プロジェクトでは CI に
compose spec validateを組み込むと安全。 -
CLI 統合と新機能
docker composeが標準化されたことでスクリプトがシンプルになる。-
profiles,healthcheck,extensions（実験的）など v2 固有の拡張は、開発/本番環境の切り替えやコンテナ健全性管理に有効。 -
実践例：Flask + Redis のマルチコンテナ構成は、数ファイルで完結し
docker compose up -dだけで起動できる。 profilesにより開発と本番を同一 Compose ファイルで管理。-
healthcheckとdepends_onの組み合わせでサービス間の起動順序を保証。 -
トラブル対策：プラグイン配置、ネットワーク命名、ヘルスチェック設定、
docker compose config出力確認を行えば多くの問題は解決できる。
これらの手順とベストプラクティスに従うことで、Docker Compose v2 を 安全・迅速かつ拡張性高く 導入し、マルチコンテナアプリケーションの開発・運用を円滑に進めることができます。