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 (SDK Dispatcher 2.0.29+).
• 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
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.
   • Assurez-vous que les outils Dispatcher du SDK AEM v2.0.29+ sont indiqués dans la description du téléchargement.

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.

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

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).

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

Exécution locale de Dispatcher

Pour exécuter Dispatcher localement, les fichiers de configuration de Dispatcher doivent être générés à l’aide de l’outil d’interface de ligne de commande validator de Dispatcher.

• Utilisation:
  • Windows : bin\validator full -d out src
  • macOS / Linux : ./bin/validator full -d ./out ./src

Cette commande transforme les configurations en un ensemble de fichiers compatible avec le serveur web Apache HTTP du conteneur Docker.

Une fois générées, les configurations transposées sont utilisées pour exécuter Dispatcher localement dans le conteneur Docker. Il est important de s’assurer que les dernières configurations ont été validées à l’aide des sorties validate et à l’aide de l’option -d du programme de validation.

• Utilisation:
  • Windows : bin\docker_run <deployment-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>
  • macOS / Linux : ./bin/docker_run.sh <deployment-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 :

1. Générez à partir de zéro la deployment-folder, nommée out par convention, chaque fois qu’une configuration change :

   • Windows : del /Q out && bin\validator full -d out src
   • macOS / Linux : rm -rf ./out && ./bin/validator full -d ./out ./src

2. (Redémarrez) le conteneur Docker de Dispatcher en indiquant le chemin d’accès au dossier de déploiement :

   • Windows : bin\docker_run out host.docker.internal:4503 8080
   • macOS / Linux : ./bin/docker_run.sh ./out 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 du Dispatcher d’un projet de Experience Manager, il vous suffit de générer la balise deployment-folder à l’aide du dossier dispatcher/src du projet.

• Windows :

  $ del -/Q out && bin\validator full -d out <User Directory>/code/my-project/dispatcher/src
  $ bin\docker_run out host.docker.internal:4503 8080
  

• macOS / Linux :

  $ rm -rf ./out && ./bin/validator full -d ./out ~/code/my-project/dispatcher/src
  $ ./bin/docker_run.sh ./out host.docker.internal:4503 8080
  

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

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 :

  $ bin\validator full -d out <User Directory>/code/my-project/dispatcher/src
  $ DISP_LOG_LEVEL=Debug REWRITE_LOG_LEVEL=Debug bin\docker_run out host.docker.internal:4503 8080
  

• macOS / Linux :

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

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

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 "Attente jusqu’à ce que host.docker.internal soit disponible" message

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 out 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 out <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 out <HOST IP>:4503 8080

Exemple d’erreur

$ docker_run out 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 génère une erreur ** : Dossier de déploiement introuvable"

Lors de l’exécution de docker_run.cmd, une erreur s’affiche et indique ** erreur : Dossier de déploiement introuvable :. Cela se produit généralement car le chemin contient des espaces. Si possible, supprimez les espaces dans le dossier ou déplacez le dossier aem-sdk vers un chemin ne contenant pas d’espaces.

Par exemple, les dossiers d’utilisateurs Windows sont souvent <First name> <Last name>, avec un espace entre eux. Dans l’exemple ci-dessous, le dossier ...\My User\... contient un espace qui interrompt l’exécution docker_run locale des outils Dispatcher. Si les espaces se trouvent dans un dossier d’utilisateurs Windows, ne tentez pas de renommer ce dossier, car il va rompre Windows. Déplacez plutôt le dossier aem-sdk vers un nouvel emplacement que votre utilisateur est autorisé à modifier. Notez que les instructions qui supposent que le dossier aem-sdk se trouve dans le répertoire racine de l’utilisateur devront être ajustées au nouvel emplacement.

Exemple d’erreur

$ \Users\My User\aem-sdk\dispatcher>bin\docker_run.cmd out host.internal.docker:4503 8080

'User\aem-sdk\dispatcher\out\*' is not recognized as an internal or external command,
operable program or batch file.
** error: Deployment folder not found: c:\Users\My User\aem-sdk\dispatcher\out

é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 out 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