【Drupal】dockerでDDEVを使って開発環境を構築する（Mac）

この記事は約16分で読めます。

Mac上にDocker環境を構築し、DDEVを使ってDrupalの開発環境を立ち上げる手順をやってみたので、やった内容やトラブルシューティングをいかにメモしておきます。

Windowsとは異なり、MacはUNIXベースなのでDockerとの相性が良く、比較的スムーズに構築できました。

1. Docker Desktop for Mac のインストール

DockerをMacで動かすための公式ツールです。

  1. Docker Desktop のダウンロード:

    以下の公式サイトから「Docker Desktop for Mac」をダウンロードします。

    Docker Desktop
    Docker Desktop is collaborative containerization software for developers. Get started and download Docker Desktop today ...
    www.docker.com
    • チップの種類に注意: お使いのMacのチップ（Apple Silicon (M1/M2/M3) または Intel）に合わせて適切なバージョンをダウンロードしてください。
  2. インストールの実行:

    ダウンロードした .dmg ファイルを開き、Docker.app を「Applications」フォルダにドラッグ＆ドロップします。

  3. Docker Desktop の起動:

    「Applications」フォルダから「Docker Desktop」を起動します。

    初回起動時には、必要なコンポーネントのインストールや設定の許可が求められます。指示に従って進めてください。管理者パスワードが必要になる場合があります。

  4. Docker の動作確認:

    Docker Desktopが起動すると、メニューバーにクジラのアイコンが表示されます。アイコンが緑色になっていれば正常に起動しています。

    ターミナル（Terminal.app または iTerm2 など）を開き、以下のコマンドを実行してDockerが正しく動作しているか確認します。

    docker --version
docker compose version # Docker Desktopに同梱されているDocker Composeのバージョンを確認

    バージョン情報が表示されればOKです。

2. DDEVのインストール

DDEV のインストール (推奨)

Drupal開発に特化した機能が多く、シンプルで使いやすいです。

  1. Homebrew のインストール (まだの場合):

    MacのパッケージマネージャーであるHomebrewをインストールします。ターミナルで以下のコマンドを実行します。

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    指示に従って進めてください。

  2. DDEV のインストール:

    Homebrewを使ってDDEVをインストールします。

    brew install ddev/ddev/ddev

  3. DDEV の動作確認:

    ddev --version

    バージョン情報が表示されればOKです。

3. 新しいDrupalプロジェクトの作成とDDEVでのセットアップ (例: DDEV)

既存のDrupalプロジェクトがある場合は4へ進みます。

  1. プロジェクトディレクトリの作成:

    ターミナルで、Drupalプロジェクトを格納したいディレクトリに移動し、新しいディレクトリを作成します。

    mkdir my-drupal-project
cd my-drupal-project
  2. DDEV の設定:

    プロジェクトディレクトリ内で、DDEVの設定を初期化します。Drupalのバージョンなどを尋ねられるので、指示に従って入力します。

    ddev config
    • Project type: drupal10 (Drupal 9/10の場合) または drupal9 を選択
    • Docroot Location: web (Drupalの標準ドキュメントルート)
  3. Drupalのインストール (Composer経由):

    DDEV環境を起動し、その中でComposerを使ってDrupalプロジェクトをダウンロードします。

    ddev start
ddev composer create "drupal/recommended-project:^10" # または "^9"

    ddev startは初回にコンテナイメージのダウンロードなどを行うため時間がかかります。

    Composerでのダウンロードが完了したら、ddev startをもう一度実行する必要があるかもしれません。

  4. Drupalのインストール (WebインストーラーまたはDrush):

    DDEVが提供するURL（ddev describe で確認できる URL）にアクセスして、WebブラウザからDrupalのインストールを完了します。

    または、Drushを使ってCLIからインストールすることもできます。

    ddev drush site:install -y --account-name=admin --account-pass=admin install_configure_form.enable_update_status_module=0 install_configure_form.enable_default_config=0

    (これは最小限の設定例です。要件に応じてオプションを調整してください。)
    私はブラウザから手動で設定をして、インストールを完了させました。

  5. Drupalサイトの確認:

    ddev describe で表示されるURLにアクセスし、Drupalサイトがブラウザで表示されることを確認します。

4. 既存のDrupalプロジェクトをDDEVでセットアップする (例: DDEV)

既にGitリポジトリにあるDrupalプロジェクトをDDEVで動かす場合。

  1. プロジェクトのクローン:

    Gitリポジトリからプロジェクトをクローンします。

    git clone your-repository-url.git
cd your-repository-name
  2. DDEV の設定:

    プロジェクトディレクトリ内でDDEVの設定を初期化します。

    ddev config

    通常、DDEVはDrupalプロジェクトを自動的に検出し、適切な設定を提案してくれます。

  3. DDEV の起動と依存関係の解決:

    DDEV環境を起動し、Composerの依存関係を解決します。

    ddev start
ddev composer install
  4. データベースのインポート:

    本番環境や既存のデータベースダンプがある場合、それをDDEV環境にインポートします。

    例えば、database.sql.gz というファイルがプロジェクトルートにある場合：

    ddev import-db --file=database.sql.gz

    または、既存のDDEVプロジェクトからエクスポートした.sqlや.sql.gzファイルがある場合：

    ddev import-db --src=path/to/your/database.sql
  5. Drupalのデータベース更新とキャッシュクリア:

    データベースをインポートしたら、必ずDrupalの更新とキャッシュクリアを行います。

    ddev drush updb -y
ddev drush cim -y # 設定管理を使っている場合
ddev drush cr
  6. Drupalサイトの確認:

    ddev describe で表示されるURLにアクセスし、Drupalサイトがブラウザで表示されることを確認します。

トラブルシューティング

1. Error: Your Command Line Tools are too outdated.

DDEVのインストール中にエラーが出ました。「Command Line Tools」が古すぎたとのこと。 DDEV (そして多くのHomebrewでインストールされるツール) は、XcodeのCommand Line Toolsに依存しているようです。

Error: Your Command Line Tools are too outdated.
Update them from Software Update in System Settings.
If that doesn’t show you any updates, run:
sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select –install
Alternatively, manually download them from:
https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 16.4.

以下のように対応しました。

  • 古いCommand Line Toolsを削除: ターミナル（Terminal.app など）を開き、以下のコマンドを実行すると、管理者パスワードの入力が求められます。

    sudo rm -rf /Library/Developer/CommandLineTools

    このコマンドは、現在のCommand Line Toolsを完全に削除します。

  • 新しいCommand Line Toolsをインストール: 続けて、以下のコマンドを実行します。これにより、最新のCommand Line Toolsのインストールプロンプトが表示されます。

    sudo xcode-select --install

    ダイアログが表示されたら、「インストール (Install)」をクリックして進めて、完了です。

2. Could not connect to a Docker provider. Please start or install a Docker provider.

DDEVがDockerと通信できないというエラーが出ました。

DDEVはDockerコンテナの上で動作するため、Docker Desktopが起動していて、完全に準備ができている必要があります。

Docker Desktop が起動しているか確認する

MacのメニューバーにDockerのクジラのアイコンをみて、いかに応じて対応しました。

  • アイコンが灰色: Docker Desktopが起動していません。アプリケーションフォルダからDocker Desktopを起動してください。
  • アイコンが緑色: Docker Desktopは起動していますが、まだ完全に準備ができていないか、DDEVとの通信に問題がある可能性があります。

Dockerの動作をターミナルで確認する

Docker Desktopが起動したら、ターミナルで以下のコマンドを実行してDockerがコマンドラインから認識されているか確認します。

docker ps

これにより、現在実行中のDockerコンテナのリストが表示される（何も実行していなければ空のリストが表示される）。もし Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? のようなエラーが表示される場合は、Docker Desktopがまだ完全に機能していないことを示している。

3. Docroot Location (project root):

ddev config

でDDEVの設定を対話型で進めていくときに、出てきたメッセージです。

The docroot is the directory from which your site is served.:
This is a relative path from your project root at　<<ローカルPCのパス>>
Leave docroot empty (hit <RETURN>) to use the location shown in parentheses.:
Or specify a custom path if your index.php is in a different directory.
Or use '.' (a dot) to explicitly set it to the project root.

上記のように、いろいろ聞かれるので、答える形でDDEVを設定していきます。
私の場合は、
Docroot Location (project root):
→DDEVはあなたのプロジェクトタイプ（Drupal）を認識し、Drupalの標準的なドキュメントルートを提案しています。私の場合、ここでwebと入力しました。

    • Drupal 8/9/10 (Composerベースのプロジェクト) の場合、標準のドキュメントルートは通常 web です。
    • もし括弧内に web と表示されていれば、ほとんどの場合、何も入力せずにエンターキーを押す（空のまま確定する）のが正しい選択です。

その他、補足。

  • Or specify a custom path if your index.php is in a different directory.:
    もしあなたのDrupalプロジェクトが非標準的な構成で、index.php ファイルが web 以外のディレクトリ（例えば、プロジェクトルート直下や htdocs など）にある場合は、そのカスタムパスを指定。

  • Or use '.' (a dot) to explicitly set it to the project root.:
    もし index.php がプロジェクトのルートディレクトリ直下にある場合は、ドット (.) を入力してエンターキーを押す。これはDrupal 7など古いバージョンのプロジェクトによく見られていたそうです。

Project Type [backdrop, cakephp, craftcms, drupal, drupal6, drupal7, drupal8, drupal9, drupal10, drupal11, generic, laravel, magento, magento2, php, shopware6, silverstripe, symfony, typo3, wordpress] (php):

これはトラブルシューティングというより、私の中でメモしておきたかったので、記載しています。

これはDDEVがプロジェクトのタイプを尋ねています。

DDEVは非常に多機能なツールで、Drupalだけでなく、CakePHP、Craft CMS、Laravel、WordPressなど、様々なPHPベースのプロジェクトに対応していて、そのため、どの種類のプロジェクトをセットアップしようとしているのかを尋ねているものです。

括弧内に php と表示されているのは、DDEVが現在のディレクトリの内容から特定のプロジェクトタイプを自動検出できなかったため、最も汎用的な「PHPプロジェクト」をデフォルトとして提案していることを意味します。

4. Problem with your Docker provider: installed Docker version 20.10.22 is not supported, please update to version 25.0 or newer.

これは、インストールされているDockerのバージョンが古すぎるため、DDEVが要求する最低バージョン（25.0以上）を満たしていないことを示しています。

対応する手順

この問題に対応するに、Docker Desktopを最新バージョンにアップデートしました。

-----

### Docker Desktop のアップデート

1.  **Docker Desktop を終了する:**
    Macのメニューバーにあるクジラのアイコンをクリックし、「**Quit Docker Desktop**」を選択してDocker Desktopアプリケーションを完全に終了する。

2.  **Docker Desktop を起動する:**
    「Applications」フォルダから「Docker Desktop」を再度起動する。

3.  **アップデート通知を確認する:**
    Docker Desktopが起動すると、通常は新しいバージョンが利用可能であることを示す通知やダイアログが表示される。もし表示されなければ、メニューバーのクジラのアイコンをクリックし、メニュー内（または設定画面）にアップデート関連のオプションがないか確認する。

    多くの場合、以下のような表示が見つかる：

      * 「**Updates available**」
      * 「**Download update**」
      * 「**Check for updates**」
      * Docker Desktopの設定画面（Preferences/Settings）に移動し、「**Software Updates**」または「**About Docker Desktop**」セクションでアップデートを確認する。

4.  **アップデートを実行する:**
    表示される指示に従ってアップデートをダウンロードし、インストールを実行。これには少し時間がかかる場合がある。インストール完了後、Docker Desktopの再起動が求められることがある。

5.  **Docker のバージョンを確認する:**
    アップデートが完了し、Docker Desktopが起動したら、ターミナルを開き以下のコマンドを実行して、Dockerのバージョンが25.0以上になっていることを確認。

    ```bash
    docker --version
    ```

    例：`Docker version 25.0.0, build c9f68bf` のように表示されればOK。
-----

### DDEV の起動を再試行

Docker Desktopのアップデートが完了し、バージョンが確認できたら、再度DDEVの起動コマンドを実行。

```bash
ddev start
```

今度はDockerのバージョンエラーなしで、DDEVがコンテナの起動を始めるはず。

その他

・途中、ポート80で競合していましたが、DDEVが自動的に解決してくれました。

・drupal/recommended-project テンプレートは、以下のようなディレクトリ構造を持つDrupalプロジェクトを作成することを想定していて、

my-drupal-project/  <-- ここがプロジェクトのルート
├── composer.json
├── composer.lock
├── drush/
├── .ddev/       <-- DDEVの設定ファイル
├── vendor/      <-- Composerでインストールされるライブラリ
└── web/         <-- Drupalのコアファイルと公開ウェブサイトのファイル（index.phpなど）
    ├── core/
    ├── modules/
    ├── themes/
    └── index.php

この構造のトップレベル（my-drupal-project）に composer.json が配置され、web ディレクトリはそのサブディレクトリとして作成されます。

・Composer 依存関係のインストール:
Composerを使ってDrupalのファイルをダウンロードします。

ddev composer install
タイトルとURLをコピーしました