ローカルDispatcherツールの設定

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

AEM as a Dispatcher SDKには、Dispatcherをローカルで設定、検証、シミュレーションする、推奨されるDispatcherツールバージョンが含まれています。 Dispatcherツールは、次の要素で構成されます。

  • .../dispatcher-sdk-x.x.x/srcにある、Apache HTTP WebサーバーとDispatcher設定ファイルのベースラインセット
  • 設定バリデーターCLIツール(.../dispatcher-sdk-x.x.x/bin/validateにあります)
  • .../dispatcher-sdk-x.x.x/bin/validatorにある構成生成CLIツール
  • .../dispatcher-sdk-x.x.x/bin/docker_runにある構成導入CLIツール
  • Dispatcherモジュールを使用してApache HTTP Webサーバーを実行するDockerイメージ

~は、ユーザーのディレクトリの略記法として使用されます。 Windowsの場合、%HOMEPATH%と同じです。

メモ

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

前提条件

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

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

AEM as aCloud ServiceSDK(AEM SDK)には、開発用にApache HTTP WebサーバーをDispatcherモジュールと共にローカルで実行するためのDispatcherツールと、互換性のあるQuickStart Jarが含まれています。

AEM as aCloud ServiceSDKが既にローカルAEMランタイムを設定するためにダウンロードされている場合は、再度ダウンロードする必要はありません。

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

AEM SDK zipからDispatcherツールを抽出します。

ヒント

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

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

  1. ダウンロードしたaem-sdk-xxx.zipファイルを解凍します。
  2. Dispatcherツールを~/aem-sdk/dispatcherに解凍します。
    • Windowsの場合:aem-sdk-dispatcher-tools-x.x.x-windows.zipC:\Users\<My User>\aem-sdk\dispatcherに解凍します(必要に応じて、見つからないフォルダーを作成します)。
    • macOS/Linux:付属のシェルスクリプトaem-sdk-dispatcher-tools-x.x.x-unix.shを実行して、Dispatcherツールを解凍します。
      • 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設定ファイルについて

ヒント

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

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

これらのファイルは、Experience ManagerのMavenプロジェクト内にまだ存在しない場合、Experience ManagerのMavenプロジェクト内のdispatcher/srcフォルダーにコピーされることを意図しています。

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

設定の検証

必要に応じて、httpd -tを介したDispatcherおよびApache Webサーバーの設定の検証は、validateスクリプトを使用しておこなえます(validator実行可能ファイルと混同しないようにする必要があります)。 validateスクリプトは、validator3段階を実行する便利な方法を提供します。

  • 使用方法:
    • Windows:bin\validate src
    • macOS/Linux:./bin/validate.sh ./src

Dispatcherをローカルで実行する

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

  • 使用方法:
    • Windows:bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>
    • macOS/Linux:./bin/docker_run.sh <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

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

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

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

  • Windows:bin\docker_run src host.docker.internal:4503 8080
  • macOS/Linux:./bin/docker_run.sh ./src host.docker.internal:4503 8080

ポート4503でローカルに動作するAEM as a Publish SDKのパブリッシュサービスは、Dispatcherを通じてhttp://localhost:8080で使用できます。

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

  • Windows:

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

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

Dispatcherツールログ

Dispatcherログは、ローカル開発中にHTTP要求がブロックされるかどうかを把握するのに役立ちます。 ログレベルは、docker_runの実行前に環境パラメーターを付けて設定できます。

Dispatcherツールのログは、docker_runの実行時に標準に出力されます。

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

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

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

  • Windows:

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

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

ログファイルのアクセス

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

Dispatcherツールを更新するタイミング

Dispatcherツールのバージョンは、Experience Managerよりも頻繁に増分されないので、ローカル開発環境では、Dispatcherツールを使用する際に必要な更新の数が少なくなります。

推奨されるDispatcherツールのバージョンは、AEM as aCloud ServiceSDKにバンドルされ、Cloud ServiceのバージョンとしてのExperience Managerに一致します。 AEM as aCloud Serviceのバージョンは、Cloud Managerで確認できます。

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

Experience Managerのバージョン

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

トラブルシューティング

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

host.docker.internal は、ホストに解決されるを含むDockerに指定されたホスト名です。docs.docker.com(macOSWindows)ごとに、次の手順を実行します。

Docker 18.03以降では、ホストが使用する内部IPアドレスに解決される特別なDNS名host.docker.internalに接続することをお勧めします。

bin/docker_run src host.docker.internal:4503 8080の結果が「host.docker.internalが使用可能になるまで待機する」というメッセージになった場合は、次のようになります。

  1. インストールされているDockerのバージョンが18.03以降であることを確認します。
  2. host.docker.internal名の登録/解決を妨げるローカルマシンがセットアップされている可能性があります。 代わりに、ローカルIPを使用します。
    • Windows:
      • コマンドプロンプトでipconfigを実行し、ホストマシンの​IPv4アドレス​を記録します。

      • 次に、次のIPアドレスを使用してdocker_runを実行します。

        bin\docker_run src <HOST IP>:4503 8080

    • macOS/Linux:
      • ターミナルから、ifconfigを実行し、ホスト​inet​のIPアドレス(通常は​en0​デバイス)を記録します。

      • 次に、ホストのIPアドレスを使用してdocker_runを実行します。

        bin/docker_run.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

docker_runがWindowsで起動に失敗する

Windowsでdocker_runを実行すると、次のエラーが発生し、Dispatcherが起動できなくなる可能性があります。 これは、Windows上のDispatcherに関して報告された問題で、今後のリリースで修正される予定です。

エラーの例

$ \Users\MyUser\aem-sdk\dispatcher>bin\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
host.docker.internal resolves to 192.168.65.2
Running script /docker_entrypoint.d/40-generate-allowed-clients.sh
Running script /docker_entrypoint.d/50-check-expiration.sh
Running script /docker_entrypoint.d/60-check-loglevel.sh
Running script /docker_entrypoint.d/70-check-forwarded-host-secret.sh
Starting httpd server
[Sun Feb 09 17:32:22.256020 2020] [dispatcher:warn] [pid 1:tid 140080096570248] Unable to obtain parent directory of /etc/httpd/conf.dispatcher.d/enabled_farms/farms.any: No such file or directory
[Sun Feb 09 17:32:22.256069 2020] [dispatcher:alert] [pid 1:tid 140080096570248] Unable to import config file: /etc/httpd/conf.dispatcher.d/dispatcher.any
[Sun Feb 09 17:32:22.256074 2020] [dispatcher:alert] [pid 1:tid 140080096570248] Dispatcher initialization failed.
AH00016: Configuration Failed

その他のリソース

このページ