2020年に、Magento コミュニティの開発者たちによって Cloud Docker for Commerce という Docker コンテナへのデプロイ自動化ツールがリリースされました。Adobe Commerce のローカル開発環境の構築が容易になり、PHPの定番デバッグツールである Xdebug を組み合わせれば、さらに開発効率を向上させることができます。
この記事では、その具体的な手順をご紹介します。Cloud Docker for Commerce の公式ドキュメントはこちらです。

前提条件

macOS 10.13 以降
アクティブな Adobe Commerce のライセンス
Google Chrome
Docker Desktop on Mac
Mutagen
Git
VSCode

Docker 環境の構築

Adobe Commerce Cloud テンプレートのダウンロード

上記の magento/magento-cloud は、Adobe が提供する Adobe Commerce Cloud のクラウド環境へのデプロイ向けに用意されたテンプレートです。オンプレミス版の Adobe Commerce が依存パッケージに含まれており、ブランチ名が Adobe Commerce のバージョンと対応しています。

git コマンドで最新のバージョンをクローンします

git clone https://github.com/magento/magento-cloud.git

冒頭でご紹介した Cloud Docker for Commerce も、依存パッケージに含まれているので、通常ダウンロードする必要はありません。しかし、Docker イメージを自分でビルドする場合（ARM64 プラットフォーム向けの Docker イメージの作成で後述）、下記の magento/magento-cloud-docker リポジトリから別途ダウンロードする必要があります。

Adobe Commerce オンプレミス版について

オンプレミス版の Adobe Commerce のプロジェクトでも、自分で Docker の設定ファイルを作成し、magento/magento-cloud-docker リポジトリ内のツールを使うことで、ほぼ同じ手順で進めることができます。詳しくはこちらの公式ドキュメントをご覧ください。

アクセスキーの取得

Adobe Commerce の依存パッケージが保管されている、repo.magento.com リポジトリサーバーへのアクセスには認証が必要です。magento-cloud のルートディレクトリに、アクセスキーを含む auth.jsonファイルを作成します。

Commerce Marketplace にログインし、右上のユーザー名をクリックし、My Profileを選択します
Access Key をクリックします
Create A New Access Key をクリックして、任意の名前を付けて OK をクリックします
magento-cloud のルートディレクトリに、以下のように auth.json を記述し保存します。<public-key> と <private-key> を先ほど作成したアクセスキーに置き換えます
```
{
  "http-basic": {
    "repo.magento.com": {
      "username": "<public-key>",
      "password": "<private-key>"
    }
  }
}
```

`hosts` ファイルの設定と依存パッケージのインストール

/etc/hosts に magento2.docker を追加します

echo "127.0.0.1 magento2.docker" | sudo tee -a /etc/hosts

magento-cloud のルートディレクトリに移動します
```
cd magento-cloud
```
依存パッケージをインストールします
```
composer update
```

`docker-compose.yml` の作成

ece-docker ツールを使って、docker-compose.yml を作成します

./vendor/bin/ece-docker build:compose --mode="developer" --sync-engine="mutagen"  --with-xdebug

ARM64 プラットフォーム向けの Docker イメージの作成

M1 Mac などの ARM64 プラットフォームの場合にのみ、必要な手順です

2024年2月現在、 Docker Hub で公開されている Magento の Docker イメージは全て AMD64 プラットフォーム向けです。Apple Sillicon 搭載の Mac などの ARM64 プラットフォームを使用されている場合、Docker イメージを自分でビルドする必要があります。Issue として報告され Backlog に入っているので、近日不要になると思われます。

magento-cloud の docker-compose.yml に記述されている、Docker イメージ名末尾のバージョンを確認します（この場合 1.3.6）
```
...
opensearch:
    hostname: opensearch.magento2.docker
    image: 'magento/magento-cloud-docker-opensearch:2.4-1.3.6'
...
```
magento/magento-cloud-docker リポジトリをクローンします
```
git clone https://github.com/magento/magento-cloud-docker.git
```
magento-cloud-docker のルートディレクトリに移動します
```
cd magento-cloud-docker
```
確認したバージョンをチェックアウトします
```
git checkout refs/tags/1.3.6
```

必要なイメージをビルドします

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-opensearch:2.4-1.3.6 ./images/opensearch/2.4

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-php:8.2-fpm-1.3.6 ./images/php/8.2-fpm

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-nginx:1.19-1.3.6 ./images/nginx/1.19

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-varnish:6.6-1.3.6 ./images/varnish/6.6

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-php:8.2-cli-1.3.6 ./images/php/8.2-cli

docker image build --platform=linux/arm64/v8 -t magento/magento-cloud-docker-mailhog:1.0-1.3.6 ./images/mailhog/1.0

Docker Desktop のリソース設定

Docker 環境をサポートするために、必要となる Docker Desktop のリソースの最小要件は以下になります。Docker Desktop の Preferences にある Resources タブから設定します。

CPUs: 2
Memory: 6.00 GB
Swap: 1.00 GB

Docker コンテナの起動

ファイルをコンテナにビルドして、バックグラウンドモードで実行します
```
docker compose up -d
```
Mutagen によるファイル同期を開始します
```
bash ./mutagen.sh
```

Docker 環境に Adobe Commerce のインストール

Docker コンテナに Adobe Commerce をデプロイします
```
docker compose run --rm deploy cloud-deploy
```

post-deploy フックを走らせます

docker compose run --rm deploy cloud-post-deploy

Varnishに接続します

docker compose run --rm deploy magento-command config:set system/full_page_cache/caching_application 2 --lock-env

docker compose run --rm deploy magento-command setup:config:set --http-cache-hosts=varnish

キャッシュをクリアします

docker compose run --rm deploy magento-command cache:clean

ストアフロントのページの確認

こちらの URL にブラウザからアクセスして、ページが問題なく開くか確認します。
http://magento2.docker

管理画面の確認

こちらの URL にブラウザからアクセスして、問題なくログインできるか確認します。
http://magento2.docker/admin
Username Admin
Password 123123q

Xdebugの導入

VSCode 拡張機能のインストール

左サイドメニューにある Extensions タブを開きます
左上の検索バーで「PHP Debug」を検索します
Install ボタンをクリックします

.vscode フォルダを作成し、 launch.json を、下記のように記述し保存します。name は何でも構いませんが、ここでは Listen for Xdebug とします

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9001,
      "pathMappings": {
        "/app": "${workspaceFolder}"
      }
    }
  ]
}

左サイドメニューの Run and Debug から、今作成した Listen for Xdebug を起動します

Xdebug helper のインストール

Chrome ウェブストアの Xdebug helper を開きます
Chrome に追加ボタンをクリックして、拡張機能をインストールします

動作確認

bootstrap.php などにブレークポイントを配置し、Adobe Commerce の任意のページを読み込んだ際に、実行が該当箇所で止まることを確認できれば成功です。