Configurar las herramientas locales de Dispatcher set-up-local-dispatcher-tools

Dispatcher de Adobe Experience Manager (AEM) es un módulo de servidor web HTTP Apache que proporciona una capa de seguridad y rendimiento entre el nivel de CDN y AEM Publish. Dispatcher es una parte integral de la arquitectura de Experience Manager general y debe formar parte de la configuración de desarrollo local.

AEM as a Cloud Service SDK incluye la versión de Dispatcher Tools recomendada que facilita la configuración, validación y simulación de Dispatcher localmente. Las herramientas de Dispatcher están compuestas por:

Tenga en cuenta que ~ se usa como abreviatura del directorio del usuario. En Windows, es el equivalente de %HOMEPATH%.

Requisitos previos

Descargar las herramientas de Dispatcher (como parte de AEM SDK)

AEM as a Cloud Service SDK, o AEM SDK, contiene las herramientas de Dispatcher utilizadas para ejecutar el servidor web HTTP Apache con el módulo de Dispatcher localmente para desarrollo y el Jar de inicio rápido compatible.

Si AEM as a Cloud Service SDK ya se ha descargado para configurar el tiempo de ejecución local de AEM, no es necesario volver a descargarlo.

Extraiga las herramientas de Dispatcher del zip de SDK de AEM

La versión de las herramientas de Dispatcher es diferente de la de AEM SDK. Asegúrese de que la versión de las herramientas de Dispatcher se proporciona a través de la versión de AEM SDK que coincide con la versión de 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

Todos los comandos que se emiten a continuación suponen que el directorio de trabajo actual contiene el contenido de herramientas de Dispatcher en expansión.

Este vídeo utiliza macOS con fines ilustrativos. Los comandos equivalentes de Windows/Linux se pueden usar para obtener resultados similares.

Comprender los archivos de configuración de Dispatcher

Las herramientas de Dispatcher proporcionan un conjunto de archivos de configuración de Dispatcher y del servidor web HTTP Apache que definen el comportamiento de todos los entornos, incluido el desarrollo local.

Estos archivos están pensados para copiarse en un proyecto Maven de Experience Manager en la carpeta dispatcher/src, si no existen en el proyecto Maven de Experience Manager.

Hay disponible una descripción completa de los archivos de configuración en las herramientas de Dispatcher desempaquetadas como dispatcher-sdk-x.x.x/docs/Config.html.

Validar configuraciones

Opcionalmente, las configuraciones del servidor web Dispatcher y Apache (a través de httpd -t) se pueden validar utilizando el script validate (no confundirlo con el ejecutable validator). El script validate proporciona una forma cómoda de ejecutar las tres fases de validator.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Ejecutar Dispatcher localmente

AEM Dispatcher se ejecuta localmente mediante Docker en los archivos de configuración de src servidor web Dispatcher y 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>

El <aem-publish-host> se puede establecer en host.docker.internal, un nombre DNS especial que Docker proporciona en el contenedor que se resuelve en la dirección IP del equipo host. Si host.docker.internal no se resuelve, consulte la sección solución de problemas a continuación.

Por ejemplo, para iniciar el contenedor de Dispatcher Docker utilizando los archivos de configuración predeterminados proporcionados por las herramientas de Dispatcher:

Inicie el contenedor de Dispatcher Docker que proporciona la ruta a la carpeta src de configuración 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

El servicio de publicación de AEM as a Cloud Service SDK que se ejecuta localmente en el puerto 4503 está disponible a través de Dispatcher en http://localhost:8080.

Para ejecutar las herramientas de Dispatcher en la configuración de Dispatcher de un proyecto de Experience Manager, elija la carpeta dispatcher/src del proyecto.

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

Registros de herramientas de Dispatcher

Los registros de Dispatcher son útiles durante el desarrollo local para comprender si las solicitudes HTTP están bloqueadas y por qué. El nivel de registro se puede establecer prefiriendo la ejecución de docker_run con parámetros de entorno.

Los registros de Dispatcher Tools se emiten al resultado estándar cuando se ejecuta docker_run.

Los parámetros útiles para depurar Dispatcher incluyen:

Se pueden pasar uno o varios parámetros a 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

Acceso a archivo de registro

Se puede acceder directamente al servidor web Apache y a los registros de AEM Dispatcher en el contenedor de Docker:

Cuándo actualizar las herramientas de Dispatcher dispatcher-tools-version

Las versiones de Dispatcher Tools aumentan con menos frecuencia que Experience Manager y, por lo tanto, Dispatcher Tools requiere menos actualizaciones en el entorno de desarrollo local.

La versión de Dispatcher Tools recomendada es la que está empaquetada con AEM as a Cloud Service SDK que coincide con la versión de Experience Manager as a Cloud Service. Se puede encontrar la versión de AEM as a Cloud Service a través de Cloud Manager.

Tenga en cuenta que la versión de Dispatcher Tools no coincide con la versión de Experience Manager.

Cómo actualizar el conjunto de líneas de base de las configuraciones de Apache y Dispatcher

El conjunto de línea de base de la configuración de Apache y Dispatcher se mejora regularmente y se lanza con la versión de AEM as a Cloud Service SDK. Se recomienda incorporar las mejoras de configuración de línea de base en el proyecto de AEM y evitar errores de validación local y de canalización de Cloud Manager. Actualícelos utilizando el script update_maven.sh de la carpeta .../dispatcher-sdk-x.x.x/bin.

Este vídeo utiliza macOS con fines ilustrativos. Los comandos equivalentes de Windows/Linux se pueden usar para obtener resultados similares.

Supongamos que ha creado un proyecto de AEM en el pasado utilizando AEM Project Archetype, las configuraciones de línea de base de Apache y Dispatcher eran actuales. Con estas configuraciones de línea de base, las configuraciones específicas del proyecto se crearon reutilizando y copiando archivos como *.vhost, *.conf, *.farm y *.any de las carpetas dispatcher/src/conf.d y dispatcher/src/conf.dispatcher.d. Su validación local de Dispatcher y sus canalizaciones de Cloud Manager funcionaban correctamente.

Mientras tanto, las configuraciones de línea base de Apache y Dispatcher se mejoraron por varias razones, como nuevas funciones, correcciones de seguridad y optimización. Se publican mediante una versión más reciente de las herramientas de Dispatcher como parte de la versión de AEM as a Cloud Service.

Ahora, al validar las configuraciones de Dispatcher específicas del proyecto con la última versión de Dispatcher Tools, comienzan a dar errores. Para resolver esto, es necesario actualizar las configuraciones de línea de base mediante los siguientes pasos:

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

Solución de problemas

docker_run da como resultado el mensaje "Esperando hasta que host.docker.internal esté disponible" troubleshooting-host-docker-internal

host.docker.internal es un nombre de host proporcionado al contenedor Docker que se resuelve en el host. Por docs.docker.com (macOS, Windows):

A partir de Docker 18.03, la recomendación es conectarse al nombre DNS especial host.docker.internal, que se resuelve en la dirección IP interna utilizada por el host

Cuando bin/docker_run src host.docker.internal:4503 8080 dé como resultado el mensaje Esperando a que host.docker.internal esté disponible, entonces:

Error de ejemplo

$ 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

Recursos adicionales