ローカル 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 ツールは、以下の要素で構成されています。

  • Apache HTTP web サーバーと Dispatcher 設定ファイルのベースラインセット(.../dispatcher-sdk-x.x.x/src にあります)
  • .../dispatcher-sdk-x.x.x/bin/validate に置かれた設定バリデーター CLI ツール
  • .../dispatcher-sdk-x.x.x/bin/validator に置かれた設定生成 CLI ツール
  • .../dispatcher-sdk-x.x.x/bin/docker_run に置かれた設定デプロイメント CLI ツール
  • CLI ツールを上書きする不変の設定ファイル(.../dispatcher-sdk-x.x.x/bin/update_maven にあります)
  • Dispatcher モジュールで Apache HTTP web サーバーを実行する Docker 画像

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

NOTE
このページのビデオは macOS で録画されました。Windows ユーザーはこれに従うことができますが、各ビデオで提供されている同等の Dispatcher ツール Windows コマンドを使用します。

前提条件

  1. Windows ユーザーは、Windows 10 Professional(または Docker をサポートするバージョン)を使用する必要があります。
  2. Experience Manager パブリッシュクイックスタート JAR を、ローカルの開発マシン上にインストールします。
  • オプションとして、ローカルの AEM Publish サービスに最新の AEM リファレンス web サイトをインストールします。この web サイトは、作業中の Dispatcher を視覚化するために、このチュートリアルで使用されます。
  1. Docker(Docker Desktop 2.2.0.5 以降および Docker Engine v19.03.9以降)の最新バージョンをローカル開発マシンにインストールして起動します。

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 ランタイムをセットアップしてある場合は、再度ダウンロードする必要はありません。

  1. Adobe ID を使用して、experience.adobe.com/#/downloads にログインします。
    • AEM as a Cloud Service SDK をダウンロードするには、Adobe 組織が AEM as a Cloud Service 用にプロビジョニングされている​ 必要があります
  2. 最新の AEM SDK 結果レコードをクリックしてダウンロードします。

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

TIP
Windows ユーザーは、ローカル Dispatcher ツールを含むフォルダーへのパスに、スペースや特殊文字を含めることはできません。 パスにスペースが存在する場合、docker_run.cmd は失敗します。

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

  1. ダウンロードした aem-sdk-xxx.zip ファイルを解凍します。
  2. Dispatcher ツールを ~/aem-sdk/dispatcher に解凍します。
macOS
code language-shell
$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh
Windows
aem-sdk-dispatcher-tools-x.x.x-windows.zipC:\Users\<My User>\aem-sdk\dispatcher に解凍します(必要に応じて、欠落しているフォルダーを作成します)。
Linux®
code language-shell
$ 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 設定ファイルについて

TIP
AEM Project Maven アーキタイプで作成された Experience Manager プロジェクトは、この一連の Dispatcher 設定ファイルに事前に設定されているので、Dispatcher ツールの src フォルダーからコピーする必要はありません。

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 スクリプトは、validator3 つのフェーズの実行に便利です。

macOS
code language-shell
$ ./bin/validate.sh ./src
Windows
code language-shell
$ bin\validate src
Linux®
code language-shell
$ ./bin/validate.sh ./src

Dispatcher のローカルでの実行

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

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

docker_run_hot_reload 実行可能ファイルは、docker_run を手動で終了して再起動する必要がなく、設定ファイルを変更するとリロードするので、docker_run よりも推奨されます。または、docker_run を使用することができますが、設定ファイルを変更した際は、docker_run を手動で終了して再起動する必要があります。

Windows
code language-shell
$ bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>
Linux®
code language-shell
$ ./bin/docker_run_hot_reload.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

docker_run_hot_reload 実行可能ファイルは、docker_run を手動で終了して再起動する必要がなく、設定ファイルを変更するとリロードするので、docker_run よりも推奨されます。または、docker_run を使用することができますが、設定ファイルを変更した際は、docker_run を手動で終了して再起動する必要があります。

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

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

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

macOS
code language-shell
$ ./bin/docker_run_hot_reload.sh ./src host.docker.internal:4503 8080
Windows
code language-shell
$ bin\docker_run src host.docker.internal:4503 8080
Linux®
code language-shell
$ ./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 フォルダーを指定します。

macOS
code language-shell
$ ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
Windows
code language-shell
$ bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
Linux®
code language-shell
$ ./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 のデバッグに役立つパラメーターは以下のとおりです。

  • DISP_LOG_LEVEL=Debug は、Dispatcher モジュールのログをデバッグ レベルに設定します
    • デフォルト値:Warn
  • REWRITE_LOG_LEVEL=Debug は、Apache HTTP web サーバー書き換えモジュールのログ記録をデバッグ レベルに設定します
    • デフォルト値:Warn
  • DISP_RUN_MODE は Dispatcher 環境の「実行モード」を設定し、対応する実行モードの Dispatcher 設定ファイルを読み込みます。
    • デフォルトは dev
  • 有効な値: devstage または prod

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

macOS
code language-shell
$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug ./bin/docker_run_hot_reload.sh ~/code/my-project/dispatcher/src host.docker.internal:4503 8080
Windows
code language-shell
$ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug bin\docker_run <User Directory>/code/my-project/dispatcher/src host.docker.internal:4503 8080
Linux®
code language-shell
$ 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 で見つけることができます。

  • Cloud Manager/EnvironmentsAEM リリース ラベルで指定された環境ごとに

Experience 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 ツールに対して検証すると、失敗するようになります。これを解決するには、以下の手順に従ってベースライン設定を更新する必要があります。

  • 最新バージョンの Dispatcher ツールに対して検証が失敗するかどうかを確認します。

    code language-shell
    $ ./bin/validate.sh ${YOUR-AEM-PROJECT}/dispatcher/src
    
    ...
    Phase 3: Immutability check
    empty mode param, assuming mode = 'check'
    ...
    ** error: immutable file 'conf.d/available_vhosts/default.vhost' has been changed!
    
  • update_maven.sh スクリプトを使用して不変ファイルを更新します。

    code language-shell
    $ ./bin/update_maven.sh ${YOUR-AEM-PROJECT}/dispatcher/src
    
    ...
    Updating dispatcher configuration at folder
    running in 'extract' mode
    running in 'extract' mode
    reading immutable file list from /etc/httpd/immutable.files.txt
    preparing 'conf.d/available_vhosts/default.vhost' immutable file extraction
    ...
    immutable files extraction COMPLETE
    fd72f4521fa838daaaf006bb8c9c96ed33a142a2d63cc963ba4cc3dd228948fe
    Cloud manager validator 2.0.53
    
  • dispatcher_vhost.confdefault.vhostdefault.farm などの更新された不変ファイルを検証し、必要に応じて、これらのファイルから派生したカスタムファイルに、適切な変更を加えます。

  • 設定を再検証すると、合格するはずです。

$ ./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 によれば、次のとおりです(macOSWindows)。

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 が使用可能になるまで待機中)というメッセージが表示された場合は、以下を実行します。

  1. インストールされている Docker のバージョンが 18.03 以降であることを確認します。
  2. セットアップされているローカルマシンにより、host.docker.internal の名前の登録/解決が妨げられている可能性があります。代わりに、ローカル IP を使用します。
macOS
  • ターミナルから ifconfig を実行し、Host inet IPアドレス(通常は en0 デバイス)を記録します。

  • 次に、ホスト IP アドレスを使って docker_run を実行します:$ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Windows
  • コマンドプロンプトから ipconfig を実行し、ホストマシンの IPv4 アドレス ​を記録します。

  • そして、この IP アドレスを使用して docker_run を実行します。$ bin\docker_run src <HOST IP>:4503 8080

Linux®
  • ターミナルから ifconfig を実行し、Host inet IPアドレス(通常は en0 デバイス)を記録します。

  • 次に、ホスト IP アドレスを使って docker_run を実行します。$ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

エラー例

$ 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

その他のリソース

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69