Configuration des outils Dispatcher locaux

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

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

• un ensemble de base de fichiers de configuration du serveur web Apache HTTP et du Dispatcher, situé dans .../dispatcher-sdk-x.x.x/src
• un outil d’interface de ligne de commande du validateur de configuration situé à l’adresse .../dispatcher-sdk-x.x.x/bin/validate
• un outil d’interface de ligne de commande pour la génération de la configuration situé à l’adresse .../dispatcher-sdk-x.x.x/bin/validator
• un outil d’interface de ligne de commande pour le déploiement des configurations situé à l’adresse .../dispatcher-sdk-x.x.x/bin/docker_run
• une image Docker qui exécute le serveur web Apache HTTP avec le module Dispatcher ;

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

Prérequis

1. Les utilisateurs de Windows doivent utiliser Windows 10 Professional (ou une version prenant en charge Docker)
2. Installez Experience Manager Publish Quickstart Jar sur la machine de développement locale.
   • Vous pouvez éventuellement installer le dernier site web de référence d’AEM sur le service AEM Publish local. Ce site web est utilisé dans ce tutoriel pour visualiser un Dispatcher fonctionnel.
3. Installez et démarrez la dernière version de Docker (Docker Desktop 2.2.0.5+/Docker Engine v19.03.9+) sur l’ordinateur de développement local.

Téléchargement des outils de Dispatcher (dans le cadre du SDK AEM)

Le SDK AEM as a Cloud Service, ou SDK AEM, contient les outils 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 QuickStart compatible.

Si le SDK AEM as a Cloud Service a déjà été téléchargé vers configuration du runtime AEM local, il n’est pas nécessaire de le retélécharger.

1. Connectez-vous à [experience.adobe.com/#/downloads] (https://experience.adobe.com/#/downloads/content/software-distribution/en/aemcloud.html?fulltext=AEM*+SDK*&1_group.propertyvalues.property=.%2Fjcr%3Acontent%2Fmetadata%2Fdc%3AsoftwareType&1_group.properties.operation=equals&1_group.properties.0_values=software-type%3Atooling&orderby=%40jcr%3Acontent%2Fjcr%3AlastModified&orderby.sort=desc&layout list&p.offset=0&p.limit=1) avec votre Adobe ID
   • Votre organisation Adobe doit être configurée pour AEM en tant que Cloud Service pour télécharger AEM en tant que SDK Cloud Service
2. Cliquez sur la dernière ligne de résultat AEM SDK à télécharger.

Extrayez les outils Dispatcher du fichier zip du SDK AEM

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

1. Décompressez le fichier aem-sdk-xxx.zip téléchargé.
2. Décompressez les outils Dispatcher dans ~/aem-sdk/dispatcher
   • Windows : Décompressez aem-sdk-dispatcher-tools-x.x.x-windows.zip dans C:\Users\<My User>\aem-sdk\dispatcher (créez les dossiers manquants selon les besoins).
   • macOS / Linux : Exécutez le script shell suivant aem-sdk-dispatcher-tools-x.x.x-unix.sh pour décompresser les outils de Dispatcher.
     • chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh && ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

Notez que toutes les commandes émises ci-dessous supposent que le répertoire de travail actuel contient le contenu des outils Dispatcher en extension.

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

Présentation des fichiers de configuration de Dispatcher

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

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

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

Validation des configurations

En option, les configurations du serveur web Dispatcher et Apache (via httpd -t) peuvent être validées à l’aide du script validate (à ne pas confondre avec le fichier exécutable validator). Le script validate permet d’exécuter facilement les 3 phases de validator.

• Utilisation:
  • Windows : bin\validate src
  • macOS / Linux : ./bin/validate.sh ./src

Exécution locale de Dispatcher

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

• Utilisation:
  • 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> 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 la host.docker.internal ne se résout pas, 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 Dispatcher :

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

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

Le service de publication de l’AEM as a Cloud Service SDK s’exécutant localement sur le port 4503 sera disponible via Dispatcher à l’adresse http://localhost:8080.

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

• 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
  

Journaux des outils 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 journal 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 de Dispatcher sont émis en sortie standard lorsque docker_run est exécuté.

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

• DISP_LOG_LEVEL=Debug définit la journalisation du module Dispatcher sur le niveau de débogage.
  • La valeur par défaut est: Warn
• REWRITE_LOG_LEVEL=Debug définit la journalisation du module de réécriture du serveur web Apache HTTP au niveau de débogage.
  • La valeur par défaut est: Warn
• DISP_RUN_MODE définit le "mode d’exécution" de l’environnement de Dispatcher, en chargeant les fichiers de configuration de Dispatcher des modes d’exécution correspondants.
  • La valeur par défaut est dev
• Valeurs valides : dev, stage ou prod

Un ou plusieurs paramètres peuvent être transmis à docker_run

• 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
  

Accès aux fichiers journaux

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

• Accès aux journaux dans le conteneur Docker
• Copie des journaux Docker vers le système de fichiers local

Quand mettre à jour les outils de Dispatcher

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

La version recommandée des outils de Dispatcher est celle qui est fournie avec l’AEM en tant que SDK de Cloud Service correspondant au Experience Manager en tant que version de Cloud Service. Vous trouverez la version d’AEM en tant que Cloud Service via Cloud Manager.

• Cloud Manager > Environnements, par environnement spécifié par le ____ Libellé d’AEM

Notez que la version des outils de Dispatcher elle-même ne correspond pas à la version du Experience Manager.

Résolution des problèmes

docker_run se traduit par un message "En attente jusqu’à ce que host.docker.internal soit disponible".

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

À partir de la version 18.03 de Docker, nous vous recommandons de vous connecter au nom DNS spécial host.docker.internal, qui correspond à l’adresse IP interne utilisée par l’hôte.

Si, lorsque bin/docker_run src host.docker.internal:4503 8080 renvoie le message En attendant que host.docker.internal soit disponible, alors :

1. Assurez-vous que la version installée de Docker est 18.03 ou supérieure.
2. Vous pouvez configurer un ordinateur local qui empêche l’enregistrement/la résolution du nom host.docker.internal. Utilisez plutôt votre adresse IP locale.
   • Windows :

     • Dans l’invite de commande, exécutez ipconfig et enregistrez l’adresse IPv4 de l’ordinateur hôte.

     • Exécutez ensuite docker_run à l’aide de cette adresse IP :

       bin\docker_run src <HOST IP>:4503 8080

   • macOS / Linux :

     • Depuis le terminal, exécutez ifconfig et enregistrez l’adresse IP de l’hôte inet, généralement le périphérique en0.

     • Exécutez ensuite docker_run à l’aide de l’adresse IP de l’hôte :

       bin/docker_run.sh src <HOST IP>:4503 8080

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

échec du démarrage de docker_run sous Windows

L’exécution de docker_run sous Windows peut entraîner l’erreur suivante, ce qui empêche Dispatcher de démarrer. Il s’agit d’un problème signalé avec Dispatcher sous Windows qui sera corrigé dans une version ultérieure.

Exemple d’erreur

$ \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

Ressources supplémentaires

• Télécharger AEM SDK
• Adobe Cloud Manager
• Télécharger Docker
• Téléchargez le site de référence d’AEM (WKND)
• Documentation du Dispatcher Experience Manager