Einrichten lokaler Dispatcher-Tools set-up-local-dispatcher-tools

Der Dispatcher von Adobe Experience Manager (AEM) ist ein Apache-HTTP-Webservermodul, das eine Sicherheits- und Leistungsschicht zwischen dem CDN und der AEM-Veröffentlichungsebene bildet. Dispatcher ist ein integraler Bestandteil der Gesamtarchitektur von Experience Manager und sollte auch in der lokalen Entwicklungsumgebung vorhanden sein.

Das AEM as a Cloud Service SDK enthält die empfohlene Version der Dispatcher Tools, die die Konfiguration der Validierung und Simulation des Dispatchers lokal erleichtert. Die Dispatcher Tools bestehen aus:

Beachten Sie, dass ~ als Abkürzung für das Benutzerverzeichnis verwendet wird. Unter Windows entspricht dies %HOMEPATH%.

Voraussetzungen

Herunterladen der Dispatcher-Tools (als Teil des AEM SDK)

Das AEM as a Cloud Service-SDK oder AEM SDK enthält die Dispatcher-Tools, die zum lokalen Ausführen des Apache-HTTP-Webservers mit dem Dispatcher-Modul für die Entwicklung verwendet werden, und das kompatible Schnellstart-JAR.

Wenn das AEM as a Cloud Service-SDK bereits heruntergeladen wurde, um die lokale AEM-Laufzeitumgebung einzurichten, muss es nicht erneut heruntergeladen werden.

Extrahieren Sie die Dispatcher-Tools aus der AEM SDK-ZIP-Datei

Die Version der Dispatcher-Tools unterscheidet sich von der des AEM SDK. Stellen Sie sicher, dass die Version der Dispatcher-Tools über die AEM SDK-Version bereitgestellt wird, die der AEM as a Cloud Service-Version entspricht.

$ 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

Bei allen unten angegebenen Befehlen wird davon ausgegangen, dass das aktuelle Arbeitsverzeichnis die erweiterten Inhalte der Dispatcher-Tools enthält.

In diesem Video wird macOS zur Veranschaulichung verwendet. Mit den entsprechenden Windows-/Linux-Befehlen werden ähnliche Ergebnisse erzielt.

Grundlegendes zu den Dispatcher-Konfigurationsdateien

Die Dispatcher-Tools bieten eine Reihe von Apache-HTTP-Webserver- und Dispatcher-Konfigurationsdateien, die das Verhalten für alle Umgebungen, einschließlich der lokalen Entwicklung, definieren.

Diese Dateien sollen in ein Experience Manager-Maven-Projekt in die dispatcher/src -Ordner, wenn sie nicht im Experience Manager-Maven-Projekt vorhanden sind.

Eine vollständige Beschreibung der Konfigurationsdateien ist in den entpackten Dispatcher-Tools als dispatcher-sdk-x.x.x/docs/Config.html verfügbar.

Überprüfen der Konfigurationen

Optional können die Konfigurationen des Dispatchers und des Apache-Webservers (über httpd -t) mit dem Skript validate (nicht zu verwechseln mit der ausführbaren Datei validator) validiert werden. Das validate-Skript bietet eine bequeme Möglichkeit, die drei Phasen des validator auszuführen.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Lokales Ausführen des Dispatchers

Der AEM Dispatcher wird lokal mit Docker für die src-Dispatcher- und Apache-Webserver-Konfigurationsdateien ausgeführt.

$ ./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>

Das <aem-publish-host> kann auf host.docker.internal gesetzt werden, einen speziellen DNS-Namen, den Docker im Container bereitstellt und der in die IP des Host-Rechners aufgelöst wird. Wenn host.docker.internal nicht aufgelöst werden kann, lesen Sie bitte den Abschnitt Fehlerbehebung weiter unten.

Um beispielsweise den Dispatcher-Docker-Container mit den Standardkonfigurationsdateien zu starten, die von den Dispatcher-Tools bereitgestellt werden:

Starten Sie den Dispatcher-Docker-Container, indem Sie den Pfad zum src-Ordner der Dispatcher-Konfiguration angeben:

$ ./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

Der Publish-Service des AEM as a Cloud Service-SDK, der lokal auf Port 4503 ausgeführt wird, ist über den Dispatcher unter http://localhost:8080 verfügbar.

Um die Dispatcher Tools für die Dispatcher-Konfiguration eines Experience Manager-Projekts auszuführen, verweisen Sie auf den dispatcher/src-Ordner Ihres Projekts.

$ ./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-Tools-Protokolle

Dispatcher-Protokolle sind bei der lokalen Entwicklung hilfreich, um zu verstehen, ob und warum HTTP-Anfragen blockiert werden. Die Protokollebene kann festgelegt werden, indem bei der Ausführung von docker_run Umgebungsparameter vorangestellt werden.

Die Dispatcher-Tools-Protokolle werden an die Standardausgabe ausgegeben, wenn docker_run ausgeführt wird.

Nützliche Parameter zum Debuggen des Dispatchers sind:

Ein oder mehrere Parameter können an docker_run weitergegeben werden.

$ 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

Zugriff auf Protokolldateien

Auf Apache-Webserver- und AEM Dispatcher-Protokolle kann direkt im Docker-Container zugegriffen werden:

Zeitpunkt zur Aktualisierung der Dispatcher-Tools dispatcher-tools-version

Die Dispatcher-Tools erhalten im Gegensatz zu Experience Manager seltener Versionserhöhungen. Daher sind für die Dispatcher-Tools weniger Aktualisierungen in der lokalen Entwicklungsumgebung erforderlich.

Es wird die Dispatcher-Tools-Version aus dem Lieferumfang des AEM as a Cloud Service SDK empfohlen, das mit der Experience Manager as a Cloud Service-Version übereinstimmt. Die AEM as a Cloud Service-Version finden Sie über Cloud Manager.

Beachten Sie, dass die Dispatcher-Tools-Version nicht mit der Experience Manager-Version übereinstimmt.

Aktualisieren der Apache- und Dispatcher-Basiskonfigurationen

Die Apache- und Dispatcher-Basiskonfigurationen werden regelmäßig erweitert und mit der AEM as a Cloud Service SDK-Version veröffentlicht. Die Best Practise liegt darin, die erweiterten Basiskonfigurationen in Ihr AEM-Projekt zu integrieren, um lokale Validierungs- sowie Cloud Manager-Pipeline-Fehler zu vermeiden. Aktualisieren Sie sie mithilfe des update_maven.sh-Skripts aus dem Ordner .../dispatcher-sdk-x.x.x/bin.

Dieses Video verwendet macOS zu Illustrationszwecken. Mit den entsprechenden Windows-/Linux-Befehlen werden ähnliche Ergebnisse erzielt.

Angenommen, Sie haben früher ein AEM-Projekt über den AEM-Projektarchetyp mit zu dieser Zeit aktuellen Apache- und Dispatcher-Basiskonfigurationen erstellt. Mithilfe dieser Basiskonfigurationen wurden Ihre projektspezifischen Konfigurationen durch Wiederverwenden und Kopieren von Dateien wie *.vhost, *.conf, *.farm und *.any aus den Ordnern dispatcher/src/conf.d und dispatcher/src/conf.dispatcher.d erstellt. Ihre lokalen Dispatcher-Validierungs- und Cloud Manager-Pipelines haben einwandfrei funktioniert.

Unterdessen wurden die Apache- und Dispatcher-Basiskonfigurationen aus verschiedenen Gründen erweitert, z. B. mit neuen Funktionen, Sicherheitskorrekturen und Optimierungen. Sie werden über eine neuere Version der Dispatcher-Tools als Teil der AEM as a Cloud Service-Version veröffentlicht.

Wenn Sie nun Ihre projektspezifischen Dispatcher-Konfigurationen für die neueste Version der Dispatcher-Tools validieren, schlagen sie fehl. Um dies zu beheben, müssen die Basiskonfigurationen mithilfe der folgenden Schritte aktualisiert werden:

$ ./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

Fehlerbehebung

„docker_run“ führt zur Meldung „Warten, bis host.docker.internal verfügbar ist“ troubleshooting-host-docker-internal

host.docker.internal ist ein Host-Name für den Docker-Container, der zum Host aufgelöst wird. Per docs.docker.com (macOS, Windows):

Ab Docker 18.03 wird empfohlen, eine Verbindung zum speziellen DNS-Namen „host.docker.internal“ herzustellen, der zu der vom Host verwendeten internen IP-Adresse aufgelöst wird.

Gehen Sie wie folgt vor, wenn bin/docker_run src host.docker.internal:4503 8080 zur Meldung Warten, bis host.docker.internal verfügbar ist führt:

Beispiel für einen Fehler

$ 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

Zusätzliche Ressourcen