ローカル Dispatcher ツールを設定する set-up-local-dispatcher-tools

Adobe Experience Manager（AEM）の Dispatcher は、CDN と AEM パブリッシュ層の間のセキュリティとパフォーマンスのレイヤーを提供する Apache HTTP web サーバーモジュールです。Dispatcher は、Experience Manager アーキテクチャ全体に不可欠な要素であり、ローカル開発セットアップの一部になります。

AEM as a Cloud Service SDK には、Dispatcher の設定、検証およびシミュレーションをローカルで容易に行えるようにする推奨 Dispatcher ツールバージョンが含まれています。Dispatcher ツールは、以下の要素で構成されています。

~ は、ユーザーのディレクトリの短縮形として使用されることにご注意ください。 Windows の場合、これは %HOMEPATH% に相当します。

前提条件

Dispatcher ツールのダウンロード（AEM SDK の一部として）

AEM as a Cloud Service SDK（AEM SDK）には、開発用に Dispatcher モジュールで Apache HTTP web サーバーをローカルに実行するための Dispatcher ツールと、互換性のある QuickStart Jar が含まれています。

AEM as a Cloud Service SDK を既にダウンロードしてローカル AEM ランタイムをセットアップしてある場合は、再度ダウンロードする必要はありません。

AEM SDK zip から Dispatcher ツールを抽出

Dispatcher ツールのバージョンは、AEM SDK のバージョンとは異なります。Dispatcher ツールのバージョンが、AEM as a Cloud Service バージョンと一致する AEM SDK バージョンから提供されていることを確認します。

$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

以下で発行されるすべてのコマンドでは、展開する Dispatcher ツール内容が現在の作業ディレクトリに含まれていると仮定しています。

このビデオでは説明のために macOS を使用しています。Windows／Linux 版の同等のコマンドを使用すれば、同様の結果を得ることができます。

Dispatcher 設定ファイルについて

Dispatcher ツールは、ローカル開発を含むすべての環境の動作を定義する、Apache HTTP web サーバーと Dispatcher 設定ファイルのセットを提供します。

これらのファイルは、Experience Manager Maven プロジェクトにコピーして dispatcher/src フォルダーに保存するためのものです（Experience Manager Maven プロジェクトにまだ存在しない場合）。

設定ファイルに関する完全な説明は、展開された Dispatcher ツールでは dispatcher-sdk-x.x.x/docs/Config.html として利用できます。

設定を検証

オプションで、Dispatcher および Apache web サーバー設定（httpd -t経由）は、 validate スクリプト（validator 実行可能と混同しないこと）を使用して検証できます。 validate スクリプトは、validator の 3 つのフェーズの実行に便利です。

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Dispatcher のローカルでの実行

AEM Dispatcher は、src Dispatcher および Apache web サーバーの設定ファイルに対して Docker を使用してローカルで実行されます 。

$ ./bin/docker_run_hot_reload.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

$ bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

$ ./bin/docker_run_hot_reload.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

<aem-publish-host> は host.docker.internal に設定できます。これは、Docker がコンテナで指定し、ホストマシンの IP に解決される特別な DNS 名です。host.docker.internal が解決されない場合は、以下のトラブルシューティングの節を参照してください。

例えば、Dispatcher ツールが提供するデフォルトの設定ファイルを使用して Dispatcher Docker コンテナを起動するには、次のようにします。

Dispatcher 設定の src フォルダーへのパスを指定する、Dispatcher Docker コンテナを起動します。

$ ./bin/docker_run_hot_reload.sh ./src host.docker.internal:4503 8080

$ bin\docker_run src host.docker.internal:4503 8080

$ ./bin/docker_run_hot_reload.sh ./src host.docker.internal:4503 8080

AEM as a Cloud Service SDK のパブリッシュサービスは、ポート 4503 でローカルに動作しており、http://localhost:8080 の Dispatcher から利用できます。

Experience Manager プロジェクトの Dispatcher 設定に対して Dispatcher ツールを実行するには、プロジェクトの dispatcher/src フォルダーを指定します。

$ ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080

$ bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080

$ ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080

Dispatcher ツールのログ

Dispatcher ログは、ローカル開発中に HTTP リクエストがブロックされているかどうか、およびその理由を理解するのに役立ちます。ログレベルは、docker_run の実行の前に環境パラメーターを付けることで設定することができます。

docker_run が実行されていると、Dispatcher ツールのログが標準出力に出力されます。

Dispatcher のデバッグに役立つパラメーターは以下のとおりです。

1 つ以上のパラメーターを docker_run に渡すことができます。

$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080

$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080

$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080

ログファイルへのアクセス

Apache web サーバーと AEM Dispatcher のログには、Docker コンテナー内で直接アクセスすることができます。

Dispatcher ツールを更新するタイミング dispatcher-tools-version

Dispatcher ツールのバージョン番号は、Experience Manager よりもインクリメントされる頻度が低いため、ローカル開発環境で Dispatcher ツールのアップデートの頻度が低くなります。

推奨される Dispatcher ツールバージョンは、AEM as a Cloud Service SDK にバンドルされているもので、Experience Manager as a Cloud Service バージョンと一致します。AEM as a Cloud Service のバージョンは、Cloud Manager で見つけることができます。

Dispatcher ツールのバージョンは、Experience Manager のバージョンと一致しないことに注意してください。

Apache 設定と Dispatcher 設定のベースラインセットを更新する方法

Apache 設定と Dispatcher 設定のベースラインセットは定期的に強化され、AEM as a Cloud Service SDK バージョンと共にリリースされます。ベストプラクティスとしては、強化されたベースライン設定を AEM プロジェクトに取り込み、ローカル検証や Cloud Manager パイプラインのエラーを回避するとよいでしょう。.../dispatcher-sdk-x.x.x/bin フォルダーの update_maven.sh スクリプトを使用して更新します。

このビデオでは説明のために macOS を使用しています。Windows／Linux 版の同等のコマンドを使用すれば、同様の結果を得ることができます。

AEM プロジェクトアーキタイプを使用して以前に AEM プロジェクトを作成し、ベースラインの Apache 設定と Dispatcher 設定が最新であったと仮定します。これらのベースライン設定を使用して、dispatcher/src/conf.d フォルダーと dispatcher/src/conf.dispatcher.d フォルダーから *.vhost、*.conf、*.farm、*.any などのファイルを再利用およびコピーすることでプロジェクト固有の設定が作成されました。ローカルの Dispatcher 検証と Cloud Manager のパイプラインは正常に動作していました。

一方、ベースラインの Apache 設定と Dispatcher 設定は、新機能、セキュリティ修正、最適化など、様々な理由で強化されました。それらは、AEM as a Cloud Service のリリースの一環として、Dispatcher ツールの新しいバージョンを通じてリリースされます。

これで、プロジェクト固有の Dispatcher 設定を最新バージョンの Dispatcher ツールに対して検証すると、失敗するようになります。これを解決するには、以下の手順に従ってベースライン設定を更新する必要があります。

$ ./bin/validate.sh ${YOUR-AEM-PROJECT}/dispatcher/src

...
checking 'conf.dispatcher.d/renders/default_renders.any' immutability (if present)
checking existing 'conf.dispatcher.d/renders/default_renders.any' for changes
checking 'conf.dispatcher.d/virtualhosts/default_virtualhosts.any' immutability (if present)
checking existing 'conf.dispatcher.d/virtualhosts/default_virtualhosts.any' for changes
no immutable file has been changed - check is SUCCESSFUL
Phase 3 finished

トラブルシューティング

docker_run を実行すると、「host.docker.internal が使用可能になるまで待機中」というメッセージが表示されます troubleshooting-host-docker-internal

host.docker.internal は Docker コンテナに指定されるホスト名であり、ホストに解決されます。docs.docker.com によれば、次のとおりです（macOS、Windows）。

Docker 18.03 以降のレコメンデーションは、特別な DNS 名 host.docker.internal に接続することです。この DNS 名は、ホストが使用する内部 IP アドレスに解決されます。

bin/docker_run src host.docker.internal:4503 8080 の結果、Waiting until host.docker.internal is available（host.docker.internal が使用可能になるまで待機中）というメッセージが表示された場合は、以下を実行します。

エラー例

$ docker_run src host.docker.internal:4503 8080

Running script /docker_entrypoint.d/10-check-environment.sh
Running script /docker_entrypoint.d/20-create-docroots.sh
Running script /docker_entrypoint.d/30-wait-for-backend.sh
Waiting until host.docker.internal is available

その他のリソース