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 Dispatcher-Tool-Version, die die lokale Konfiguration, Validierung und Simulation von Dispatcher vereinfacht. Die Dispatcher-Tools umfassen Folgendes:

  • einen Grundsatz von Apache HTTP-Webserver- und Dispatcher-Konfigurationsdateien, zu finden unter .../dispatcher-sdk-x.x.x/src
  • ein Konfigurations-Validator-CLI-Tool, zu finden unter .../dispatcher-sdk-x.x.x/bin/validate
  • ein CLI-Tool zur Konfigurationsgenerierung, zu finden unter .../dispatcher-sdk-x.x.x/bin/validator
  • ein CLI-Tool für die Konfigurationsbereitstellung, zu finden unter .../dispatcher-sdk-x.x.x/bin/docker_run
  • eine unveränderliche Konfigurationsdatei, die das CLI-Tool überschreibt, zu finden unter .../dispatcher-sdk-x.x.x/bin/update_maven
  • ein Docker-Bild, das den Apache-HTTP-Webserver mit dem Dispatcher-Modul ausführt

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

NOTE
Die Videos auf dieser Seite wurden mit macOS aufgezeichnet. Windows-Benutzende können dem Video folgen, müssen aber die entsprechenden Windows-Befehle der Dispatcher-Tools verwenden, die mit jedem Video mitgeliefert werden.

Voraussetzungen

  1. Windows-Benutzende müssen Windows 10 Professional (oder eine Version, die Docker unterstützt) verwenden
  2. Installieren Sie Experience Manager Veröffentlichungs-Schnellstart-JAR auf dem lokalen Entwicklungsrechner.
  • Installieren Sie optional die neueste AEM-Referenz-Website auf dem lokalen AEM-Veröffentlichungs-Service. Diese Website wird in diesem Tutorial zur Visualisierung eines funktionierenden Dispatchers verwendet.
  1. Installieren und starten Sie die neueste Version von Docker (Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+) auf dem lokalen Entwicklungsrechner.

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.

  1. Melden Sie sich unter experience.adobe.com/#/downloads mit Ihrer Adobe-ID an
    • Ihre Adobe-Organisation muss für AEM as a Cloud Service bereitgestellt werden, um das AEM as a Cloud Service-SDK herunterladen zu können
  2. Klicken Sie auf die neueste AEM SDK-Ergebniszeile zum Herunterladen

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

TIP
Windows-Benutzende dürfen keine Leerzeichen oder Sonderzeichen im Pfad zum Ordner haben, der die lokalen Dispatcher-Tools enthält. Wenn Leerzeichen im Pfad vorhanden sind, schlägt docker_run.cmd fehl.

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.

  1. Entpacken Sie die heruntergeladene Datei aem-sdk-xxx.zip
  2. Entpacken Sie die Dispatcher-Tools in ~/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
Entpacken Sie aem-sdk-dispatcher-tools-x.x.x-windows.zip in C:\Users\<My User>\aem-sdk\dispatcher (erstellen Sie fehlende Ordner nach Bedarf).
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

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

TIP
Experience Manager-Projekte, die mit dem AEM-Projekt-Maven-Archetyp erstellt wurden, sind mit diesem Satz von Dispatcher-Konfigurationsdateien vorausgefüllt, sodass ein Kopieren aus dem Dispatcher-Tools-Quellordner nicht erforderlich ist.

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 sollten in ein Experience Manager-Maven-Projekt in den Ordner dispatcher/src kopiert werden, 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.

macOS
code language-shell
$ ./bin/validate.sh ./src
Windows
code language-shell
$ bin\validate src
Linux®
code language-shell
$ ./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.

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

Die ausführbare Datei docker_run_hot_reload wird gegenüber docker_run bevorzugt, da sie Konfigurationsdateien neu lädt, wenn sie geändert werden, ohne dass docker_run manuell beendet und neu gestartet werden muss. Alternativ kann docker_run verwendet werden, es ist jedoch ein manuelles Beenden und Neustarten von docker_run erforderlich, wenn Konfigurationsdateien geändert werden.

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>

Die ausführbare Datei docker_run_hot_reload wird gegenüber docker_run bevorzugt, da sie Konfigurationsdateien neu lädt, wenn sie geändert werden, ohne dass docker_run manuell beendet und neu gestartet werden muss. Alternativ kann docker_run verwendet werden, es ist jedoch ein manuelles Beenden und Neustarten von docker_run erforderlich, wenn Konfigurationsdateien geändert werden.

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:

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

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.

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-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:

  • DISP_LOG_LEVEL=Debug setzt die Protokollierung des Dispatcher-Moduls auf die Debug-Ebene
    • Der Standardwert ist: Warn
  • REWRITE_LOG_LEVEL=Debug setzt die Protokollierung des Webserver-Neuschreibungsmoduls der Apache-HTTP auf die Debug-Ebene
    • Der Standardwert ist: Warn
  • DISP_RUN_MODE legt den „Ausführungsmodus“ der Dispatcher-Umgebung fest und lädt die entsprechenden Dispatcher-Konfigurationsdateien dazu.
    • Standardwert ist dev
  • Gültige Werte: dev, stage oder prod

Ein oder mehrere Parameter können an docker_run weitergegeben werden

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

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.

  • Cloud Manager > Umgebungen, pro Umgebung unter AEM-Version angegeben

Experience Manager-Version

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:

  • Überprüfen Sie, ob die Validierung für die neueste Version der Dispatcher-Tools fehlschlägt

    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!
    
  • Aktualisieren Sie die unveränderlichen Dateien mit dem Skript 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
    
  • Überprüfen Sie die aktualisierten unveränderlichen Dateien wie dispatcher_vhost.conf, default.vhost und default.farm und nehmen Sie bei Bedarf relevante Änderungen an Ihren benutzerdefinierten Dateien vor, die von diesen Dateien stammen.

  • Validieren Sie die Konfiguration erneut, Sie sollte nicht mehr fehlschlagen

$ ./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
  • Übergeben Sie nach der lokalen Überprüfung der Änderungen die aktualisierten Konfigurationsdateien

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:

  1. Stellen Sie sicher, dass die installierte Docker-Version 18.03 oder höher ist.
  2. Möglicherweise haben Sie einen lokalen Rechner eingerichtet, der die Registrierung/Auflösung des Namens host.docker.internal verhindert. Verwenden Sie stattdessen Ihre lokale IP.
macOS
  • Führen Sie ifconfig über das Terminal aus und notieren Sie sich die inet-Host-IP-Adresse (normalerweise das Gerät en0).

  • Führen Sie dann docker_run unter Verwendung dieser Host-IP-Adresse aus: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Windows
  • Führen Sie über die Eingabeaufforderung ipconfig aus und speichern Sie sich die IPv4-Adresse des Host-Computers ab.

  • Führen Sie dann docker_run unter Verwendung dieser IP-Adresse aus: $ bin\docker_run src <HOST IP>:4503 8080

Linux®
  • Führen Sie ifconfig über das Terminal aus und speichern Sie sich die inet-Host-IP-Adresse (normalerweise das Gerät en0) ab.

  • Führen Sie dann docker_run unter Verwendung dieser Host-IP-Adresse aus: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

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

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