Contents
スポンサードリンク
1. 前提条件と対象 OS・Docker Engine バージョン
1‑1. 要点（冒頭にまとめ）
- Docker Engine が v20.10.13 以上 の環境であれば、公式リポジトリから
docker-compose-pluginをインストールするだけで V2 が利用可能。 - 対象 OS は Ubuntu 22.04 LTS、Debian 12、CentOS Stream 9、Rocky Linux 8、Amazon Linux 2023 の最新版を想定。
- バージョンが古い場合は 公式スクリプトでバイナリを手動配置 するか、
docker-compose-pluginパッケージを別途取得して/usr/lib/docker/cli-plugins/に配置する必要がある。
1‑2. サポート対象 Linux ディストリビューション
| ディストリビューション | 推奨 Docker Engine バージョン | 主なパッケージマネージャ |
|---|---|---|
| Ubuntu 22.04 LTS | 20.10.13 以上 | apt |
| Debian 12 | 20.10.13 以上 | apt |
| CentOS Stream 9 | 20.10.13 以上 | dnf / yum |
| Rocky Linux 8 | 20.10.13 以上 | dnf / yum |
| Amazon Linux 2023 | 20.10.14 以上 | yum |
ポイント：Docker Engine が上記バージョン未満の場合は、後述の「プラグイン手動配置」セクションを必ず実施してください。
1‑3. Docker Engine バージョン別インストール要件
| バージョン | インストール方法 |
|---|---|
| 20.10.13 以上 | docker-ce パッケージに同梱された /usr/lib/docker/cli-plugins/docker-compose が自動配置される。 |
| 20.10.12 以下 | docker-compose-plugin を別途取得し、手動で上記パスへコピーする必要がある。 |
1‑4. 前提条件チェックリスト
|
1 2 3 4 5 6 7 8 9 |
# (1) OS のバージョン確認 cat /etc/os-release # (2) Docker Engine のバージョン確認 docker version --format '{{.Server.Version}}' # (3) 現在インストールされている docker‑compose バイナリと権限の確認 which docker-compose && ls -l $(which docker-compose) |
- 例:
Ubuntu 22.04、Docker Engine 20.10.14が表示されたら プラグイン同梱版 のインストールが可能です。 - バージョン取得に失敗した場合は、公式インストールガイド（Docker Engine インストール手順）を参照してください。
2. Docker Compose V2 プラグインのインストール方法
2‑1. 要点
- apt / dnf で公式リポジトリから
docker-compose-pluginをインストールすれば、最も簡単かつ推奨される手順。 - リポジトリにパッケージが無い古い環境は、GitHub の最新リリースを取得してバイナリを直接配置 するスクリプトで対処できる。
pipによるインストールは Compose V1（Python 製） 用であり、V2 の機能は利用できないため非推奨。
公式情報へのリンク
- Docker Compose plugin: https://docs.docker.com/compose/install/
- GitHub Releases API (最新タグ取得): https://api.github.com/repos/docker/compose/releases/latest
2‑2. apt / dnf によるインストール手順
Ubuntu / Debian（apt）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# 1️⃣ Docker の公式リポジトリを追加（未設定の場合） sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) \ signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 2️⃣ パッケージリストを更新し、Docker Engine と Compose プラグインを同時にインストール sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin |
CentOS / Rocky Linux（dnf / yum）
|
1 2 3 4 5 6 7 |
# 1️⃣ Docker の公式リポジトリ設定 sudo dnf install -y dnf-plugins-core sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 2️⃣ Docker Engine と Compose プラグインをインストール sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin |
注意：
docker-compose-pluginがリポジトリに存在しない古い OS（例: CentOS 7）では、次節の「公式スクリプト」方式を利用してください。
2‑3. 公式インストールスクリプトによる手動配置
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# jq がインストールされていなければ取得 sudo apt-get install -y jq # Ubuntu/Debian 系の場合 # sudo dnf install -y jq # RHEL/CentOS 系の場合 # GitHub の最新リリースタグを取得（例: v2.23.0） DOCKER_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | jq -r .tag_name) # バイナリのダウンロードと配置 sudo curl -SL "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-linux-$(uname -m)" \ -o /usr/lib/docker/cli-plugins/docker-compose # 実行権限を付与 sudo chmod +x /usr/lib/docker/cli-plugins/docker-compose |
スクリプトのポイント
- 自動取得：
DOCKER_COMPOSE_VERSIONは実行時に最新タグを取得するため、バージョン固定による陳腐化リスクが低減されます。 - パス：Docker CLI がプラグインを検索する標準ディレクトリは
/usr/lib/docker/cli-plugins/です。
2‑4. インストール確認コマンド
|
1 2 |
docker compose version |
期待される出力例（バージョンは実行時の最新）
Docker Compose version v2.23.0
3. 既存 docker‑compose から docker compose への移行手順
3‑1. 要点まとめ
- エイリアスは一時的な切り替えに便利だが、永続的に利用したい場合は シンボリックリンク が推奨される。
- 旧バイナリをバックアップすれば、障害発生時に即座に V1 にロールバック可能。
docker-compose.ymlは概ね互換性があるが、V2 の新機能（profiles、--watch等）を活用すると運用効率が向上する。
3‑2. エイリアスとシンボリックリンクの比較
| 方法 | 永続性 | メリット | デメリット |
|---|---|---|---|
シェルエイリアス (alias dc='docker compose') |
セッションごとに設定が必要（.bashrc 等へ追記すれば永続化） |
手軽に導入可能、環境変数やオプションの追加が簡単 | シェル外（CI スクリプト等）では無効 |
シンボリックリンク (ln -s /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose) |
ファイルシステム上に常駐し、全プロセスで有効 | 既存の docker-compose コマンドがそのまま V2 に置き換わる |
バックアップ・削除作業が必要 |
推奨手順（シンボリックリンク）
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# 1️⃣ 既存バイナリの場所を確認 which docker-compose # 例: /usr/local/bin/docker-compose # 2️⃣ バックアップ取得 sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak # 3️⃣ シンボリックリンク作成 sudo ln -s /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose # 4️⃣ 動作確認 docker compose version # V2 が表示されれば完了 |
ロールバックは
sudo rm /usr/local/bin/docker-compose && sudo mv /usr/local/bin/docker-compose.v1.bak /usr/local/bin/docker-composeで実行できます。
3‑3. docker-compose.yml の互換性と V2 推奨機能
基本的な互換性
- バージョン宣言 (
version: "3"、"3.8"等) はそのままで動作。 - サービス定義やボリューム・ネットワークの書式は従来通り。
新機能サンプル
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
services: web: image: nginx:latest ports: - "8080:80" profiles: ["dev"] # ← 開発環境専用プロファイル db: image: postgres:15 environment: POSTGRES_PASSWORD: example profiles: ["prod"] # ← 本番環境専用プロファイル # プロファイルを選択して起動 # docker compose --profile dev up -d # docker compose --profile prod up -d |
--watchオプション
bash
docker compose up --watch # ソースコード変更時に自動で再デプロイ
3‑4. 移行後の検証フロー
| 手順 | コマンド | 確認項目 |
|---|---|---|
| 構文チェック | docker compose config |
YAML が正しくパースできるか |
| プラン確認 | docker compose up --dry-run |
生成されるリソース一覧を表示 |
| 実行テスト | docker compose up -d |
コンテナが正常に起動するか |
| ログ取得 | docker compose logs -f |
起動直後の標準出力でエラーが出ていないか |
4. CI/CD パイプラインへの適用とベストプラクティス
4‑1. 要点まとめ
- CI 環境でも Docker Engine と Compose V2 を同一バージョンに統一すれば、ローカルで確認した挙動をそのまま再現できる。
- GitHub Actions・GitLab CI の公式アクション／イメージを活用し、
docker-compose-pluginのインストールを自動化する。 - キャッシュの有効活用と 権限設定がビルド時間短縮・安全性向上の鍵。
4‑2. GitHub Actions（Ubuntu 22.04）実装例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
name: CI (Docker Compose V2) on: push: branches: [ main ] jobs: build-and-test: runs-on: ubuntu-22.04 steps: - name: ソースコード取得 uses: actions/checkout@v3 # Docker Engine と Buildx のセットアップ（公式アクション） - name: Set up Docker + Buildx uses: docker/setup-buildx-action@v2 # Compose V2 プラグインのインストール - name: Install Docker Compose plugin (apt) run: | sudo apt-get update sudo apt-get install -y docker-compose-plugin # バージョン確認（デバッグ用） - name: Verify Compose version run: docker compose version # ビルド & テスト実行例 - name: Build services run: | docker compose build --pull docker compose up -d docker compose ps # 必要に応じてテストスクリプトを実行 |
ポイント解説
docker/setup-buildx-actionが Docker Engine（v23 系）と BuildKit を提供。apt install docker-compose-pluginだけで V2 が利用可能になるため、追加のスクリプトは不要。- CI のログにバージョン情報を出すことで、環境差異が原因の失敗を防止できる。
4‑3. GitLab CI（Alpine ベース）実装例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
stages: - build - test variables: DOCKER_HOST: "tcp://docker:2375" COMPOSE_DOCKER_CLI_BUILD: "1" services: - docker:dind # Docker-in-Docker を使用 build: stage: build image: docker:23.0.6 # Docker CLI が入った公式イメージ script: # Alpine に compose plugin をインストール（apk パッケージは community リポジトリにあります） - apk add --no-cache docker-compose-plugin - docker compose version # バージョン確認 - docker compose build --pull - docker compose up -d cache: key: "$CI_COMMIT_REF_SLUG" paths: - .docker/cache/ |
ベストプラクティス
- キャッシュの活用
docker compose buildのレイヤーは--cache-fromと組み合わせ、.docker/cache/に保存すれば次ジョブで再利用可能。 - 権限設定
GitLab Runner が Docker デーモンにアクセスできるよう、DOCKER_HOSTとdocker:dindの組み合わせは必須。 - プラグインのバージョン固定（必要に応じて）
yaml - apk add --no-cache docker-compose-plugin=2.23.0-r0
→ 予期しないメジャーアップデートによる破壊的変更を防止。
4‑4. セキュリティ上の留意点
| 項目 | 推奨設定 |
|---|---|
| 最小権限 | CI ランナーは docker グループに所属させ、root 権限で実行しない。 |
| イメージ署名 | docker compose pull --quiet 前に Notary / Cosign でイメージの署名検証を実施。 |
| ネットワーク分離 | CI 内部用のブリッジネットワークは外部と切り離し、ポート公開は最小限に抑える。 |
5. トラブルシューティングとロールバックガイド
5‑1. よくあるエラーと対処法
| エラーメッセージ | 想定原因 | 解決策 |
|---|---|---|
docker: error while loading shared libraries: libcompose.so |
/usr/lib/docker/cli-plugins/ にバイナリが無い、または権限不足 |
sudo apt-get install -y docker-compose-plugin もしくは公式スクリプトで手動配置し、実行権限 (chmod +x) を付与 |
docker compose: command not found |
PATH に /usr/lib/docker/cli-plugins が含まれていない |
/etc/profile.d/docker-cli.sh に export PATH=$PATH:/usr/lib/docker/cli-plugins を追記し、シェルを再起動 |
failed to create network bridge: address already in use |
同名ブリッジネットワークが既に存在 | docker network rm <name> で削除、または Compose ファイル側で別名に変更 |
5‑2. 旧バージョン（Compose V1）との競合解消手順
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# (1) 既存の docker-compose バイナリを確認 which docker-compose # 例: /usr/local/bin/docker-compose # (2) バックアップ取得（すでに実施済みならスキップ） sudo mv /usr/local/bin/docker-compose /usr/local/bin/docker-compose.v1.bak # (3) V2 用シンボリックリンクを再作成 sudo ln -sf /usr/lib/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose # (4) 競合プラグインが残っていないか確認 docker compose version # 正常にバージョン表示されれば完了 |
5‑3. ネットワークモード変更時の注意点
network_mode: hostを使用するサービスは、ホスト側で同名ネットワークが存在しないことを必ず確認。- V2 の
docker compose upはデフォルトで bridge モードを生成しますが、hostに変更すると権限エラー (permission denied) が出やすいため、CI 環境ではprivileged: trueと併用しないこと。
5‑4. ロールバック手順（V2 → V1）
|
1 2 3 4 5 6 7 8 9 10 11 |
# 1️⃣ V1 バイナリを復元 sudo cp /usr/local/bin/docker-compose.v1.bak /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose # 2️⃣ 互換モードを有効化（必要に応じて） export COMPOSE_COMPATIBILITY=1 # 一時的に有効 echo 'export COMPOSE_COMPATIBILITY=1' >> ~/.bashrc # 永続化 # 3️⃣ 動作確認 docker-compose version # V1 のバージョンが表示されれば完了 |
復旧ポイント
- バイナリを上書きする前に必ずバックアップ (*.bak) を取得。
- 環境変数COMPOSE_COMPATIBILITYは V1 が一部 V2 の構文を受け入れるためのフラグであり、CI スクリプトでも同様に設定可能。
6. 参考リンク・公式情報
| 項目 | URL |
|---|---|
| Docker Engine インストールガイド | https://docs.docker.com/engine/install/ |
| Docker Compose Plugin（公式） | https://docs.docker.com/compose/install/ |
| GitHub Releases API（最新タグ取得例） | https://api.github.com/repos/docker/compose/releases/latest |
| Docker Buildx アクション（GitHub） | https://github.com/docker/setup-buildx-action |
| Docker Compose V2 リファレンス | https://docs.docker.com/compose/reference/ |
7. まとめ（最終チェックリスト）
- OS と Docker Engine のバージョンが要件を満たすか確認
docker-compose-pluginを公式リポジトリ経由でインストール、もしくはスクリプトで最新版取得- シンボリックリンクまたは エイリアスで
docker composeへ切り替え docker compose versionが期待通りに表示されることを検証- CI/CD パイプラインに同様の手順を組み込み、キャッシュと権限設定を最適化
- 障害が起きたら バックアップバイナリでロールバックし、
COMPOSE_COMPATIBILITY=1を活用
これらの手順を踏めば、Docker Compose V2 への移行は安全かつスムーズに完了します。実運用環境や CI ランナーでぜひお試しください。
スポンサードリンク