Configurer les outils du Dispatcher local set-up-local-dispatcher-tools

Le Dispatcher Adobe Experience Manager (AEM) est un module de serveur web HTTP Apache qui fournit une couche de sécurité et de performances entre le réseau CDN et le niveau de publication d’AEM. Il fait partie intégrante de l’architecture globale d’Experience Manager et doit faire partie de la configuration de développement local.

Le SDK AEM as a Cloud Service comprend la version recommandée des outils du Dispatcher qui facilite la configuration, la validation et la simulation locale du Dispatcher. Les outils du Dispatcher se composent des éléments suivants :

Notez que ~ est utilisé comme raccourci pour le répertoire de l’utilisateur ou de l’utilisatrice. Sous Windows, il s’agit de l’équivalent de %HOMEPATH%.

Conditions préalables

Télécharger les outils du Dispatcher (dans le cadre du SDK AEM)

Le SDK AEM as a Cloud Service, ou SDK AEM, contient les outils du Dispatcher utilisés pour exécuter le serveur web Apache HTTP avec le module Dispatcher localement pour le développement, ainsi que le fichier Jar de démarrage rapide compatible.

Si le SDK AEM as a Cloud Service a déjà été téléchargé vers la configuration de l’exécution d’AEM locale, il n’est pas nécessaire de le télécharger de nouveau.

Extrayez les outils du Dispatcher du fichier zip AEM SDK.

La version des outils du Dispatcher est différente de celle d’AEM SDK. Assurez-vous que la version des outils du Dispatcher est fournie via la version du SDK AEM correspondant à la version d’AEM as a Cloud Service.

$ 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

Toutes les commandes émises ci-dessous supposent que le répertoire de travail actuel contient le contenu des outils du Dispatcher en développement.

Cette vidéo utilise macOS à des fins d’illustration. Les commandes Windows/Linux équivalentes peuvent être utilisées pour obtenir des résultats similaires.

Comprendre les fichiers de configuration de Dispatcher

Les outils du Dispatcher fournissent un ensemble de fichiers de configuration du serveur web Apache HTTP et du Dispatcher qui définissent le comportement de tous les environnements, y compris du développement local.

Ces fichiers sont destinés à être copiés dans un projet Maven d’Experience Manager vers le dossier dispatcher/src s’ils n’existent pas déjà dans le projet Maven d’Experience Manager.

Une description complète des fichiers de configuration est disponible dans les outils du Dispatcher décompressés sous la forme dispatcher-sdk-x.x.x/docs/Config.html.

Valider les configurations

Facultativement, les configurations du serveur web du Dispatcher et Apache (via httpd -t) peuvent être validées à l’aide du script validate (à ne pas confondre avec l’exécutable validator). Le script validate constitue un moyen pratique d’exécuter les trois phases du validator.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Exécuter Dispatcher localement

AEM Dispatcher est exécuté localement à l’aide de Docker par rapport aux fichiers src de configuration de Dispatcher et du serveur web Apache.

$ ./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> peut être défini sur host.docker.internal, un nom DNS spécial que Docker fournit dans le conteneur qui résout l’adresse IP de l’ordinateur hôte. Si host.docker.internal ne résout rien, reportez-vous à la section dépannage ci-dessous.

Par exemple, pour démarrer le conteneur Docker de Dispatcher à l’aide des fichiers de configuration par défaut fournis par les outils du Dispatcher :

Démarrez le conteneur Docker de Dispatcher en indiquant le chemin d’accès au dossier src de configuration de Dispatcher :

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

Le service de publication du SDK d’AEM as a Cloud Service, s’exécutant localement sur le port 4503, est disponible via Dispatcher sur http://localhost:8080.

Pour exécuter les outils du Dispatcher par rapport à la configuration Dispatcher d’un projet d’Experience Manager, pointez sur le dossier dispatcher/src de votre projet.

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

Journaux des outils du Dispatcher

Les journaux de Dispatcher sont utiles lors du développement local pour comprendre si et pourquoi les requêtes HTTP sont bloquées. Le niveau de journalisation peut être défini en ajoutant un préfixe à l’exécution de docker_run avec les paramètres d’environnement.

Les journaux des outils du Dispatcher sont émis vers Standard Out lorsque docker_run est exécuté.

Les paramètres utiles pour le débogage de Dispatcher incluent :

Un ou plusieurs paramètres peuvent être transmis à 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

Accès aux fichiers journaux

Le serveur web Apache et les journaux de Dispatcher AEM sont directement accessibles dans le conteneur Docker :

Quand mettre à jour les outils du Dispatcher dispatcher-tools-version

Les versions des outils du Dispatcher s’incrémentent moins fréquemment qu’Experience Manager. Par conséquent, les outils du Dispatcher nécessitent moins de mises à jour dans l’environnement de développement local.

La version recommandée des outils du Dispatcher est celle qui est fournie avec le SDK AEM as a Cloud Service qui correspond à la version d’Experience Manager as a Cloud Service. La version d’AEM as a Cloud Service est disponible via Cloud Manager.

Notez que la version des outils du Dispatcher ne correspond pas à la version d’Experience Manager.

Comment mettre à jour les configurations de base Apache et de Dispatcher

La configuration de base Apache et de Dispatcher est améliorée régulièrement et publiée avec la version du SDK AEM as a Cloud Service. Il est recommandé d’incorporer des améliorations de configuration de base dans votre projet AEM et d’éviter la validation locale et les échecs du pipeline Cloud Manager. Mettez-les à jour à l’aide du script update_maven.sh du dossier .../dispatcher-sdk-x.x.x/bin.

Cette vidéo utilise macOS à des fins d’illustration. Les commandes Windows/Linux équivalentes peuvent être utilisées pour obtenir des résultats similaires.

Supposons que vous ayez créé un projet AEM dans le passé en utilisant l’archétype de projet AEM, et que les configurations de base Apache et de Dispatcher étaient à jour. En utilisant ces configurations de base, vos configurations spécifiques au projet ont été créées en réutilisant et en copiant des fichiers comme *.vhost, *.conf, *.farm et *.any des dossiers dispatcher/src/conf.d et dispatcher/src/conf.dispatcher.d. La validation de votre Dispatcher local et les pipelines Cloud Manager fonctionnaient correctement.

Pendant ce temps, les configurations de base Apache et de Dispatcher ont été améliorées pour diverses raisons, telles que de nouvelles fonctionnalités, des correctifs de sécurité et l’optimisation. Elles sont publiées par le biais d’une version plus récente des outils du Dispatcher dans le cadre de la version d’AEM as a Cloud Service.

Lors de la validation de vos configurations de Dispatcher spécifiques au projet par rapport à la dernière version des outils du Dispatcher, elles commencent à échouer. Pour résoudre ce problème, les configurations de base doivent être mises à jour en suivant les étapes ci-dessous :

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

Résolution des problèmes

docker_run renvoie un message « En attente jusqu’à ce que host.docker.internal soit disponible ». troubleshooting-host-docker-internal

host.docker.internal est un nom d’hôte fourni au conteneur Docker qui résout l’hôte. Pour docs.docker.com (macOS, Windows) :

À compter de la version 18.03 de Docker, il est recommandé de se connecter au nom DNS spécial host.docker.internal, qui correspond à l’adresse IP interne utilisée par l’hôte.

Lorsque bin/docker_run src host.docker.internal:4503 8080 renvoie le message En attente jusqu’à ce que host.docker.internal soit disponible  :

Exemple d’erreur

$ 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

Ressources supplémentaires