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

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

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

  • un conjunto de línea de base de archivos de configuración del servidor web HTTP Apache y Dispatcher, ubicado en .../dispatcher-sdk-x.x.x/src
  • una herramienta CLI de validación de configuración, ubicada en .../dispatcher-sdk-x.x.x/bin/validate
  • una herramienta CLI de generación de configuración, ubicada en .../dispatcher-sdk-x.x.x/bin/validator
  • una herramienta CLI de implementación de configuración, que se encuentra en .../dispatcher-sdk-x.x.x/bin/docker_run
  • archivos de configuración inmutables que sobrescriben la herramienta CLI, ubicada en .../dispatcher-sdk-x.x.x/bin/update_maven
  • una imagen Docker que ejecuta el servidor web HTTP Apache con el módulo Dispatcher

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

NOTE
Los vídeos de esta página se han grabado en macOS. Los usuarios de Windows pueden seguir, pero utilizar los comandos equivalentes de Windows de las herramientas de Dispatcher que se proporcionan con cada vídeo.

Requisitos previos

  1. Los usuarios de Windows deben utilizar Windows 10 Professional (o una versión compatible con Docker)
  2. Instalar Jar de inicio rápido de publicación de Experience Manager en la máquina de desarrollo local.
  • Si lo desea, instale la última versión AEM sitio web de referencia de AEM en el servicio local de publicación de la. Este sitio web se utiliza en este tutorial para visualizar una instancia de Dispatcher en funcionamiento.
  1. Instale e inicie la última versión de Docker (Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+) en la máquina de desarrollo local.

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

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

AEM Si el SDK as a Cloud Service de la ya se ha descargado en AEM configuración del tiempo de ejecución de la local, no es necesario volver a descargarla.

  1. Iniciar sesión en experience.adobe.com/#/downloads con su Adobe ID
    • Su organización de Adobe debe AEM se debe aprovisionar para que los as a Cloud Service AEM descarguen el SDK as a Cloud Service de la
  2. Haga clic en la última AEM SDK de fila de resultados para descargar

AEM Extraiga las herramientas de Dispatcher del zip del SDK de la

TIP
Los usuarios de Windows no pueden tener espacios ni caracteres especiales en la ruta de acceso a la carpeta que contiene las herramientas de Dispatcher locales. Si existen espacios en la ruta, la variable docker_run.cmd falla.

AEM La versión de las herramientas de Dispatcher es diferente a la del SDK de la. AEM AEM Asegúrese de que la versión de las herramientas de Dispatcher se proporciona a través de la versión del SDK de la que coincida con la versión as a Cloud Service.

  1. Descomprima el archivo descargado aem-sdk-xxx.zip archivo
  2. Desempaquetar las herramientas de Dispatcher en ~/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
Descomprimir aem-sdk-dispatcher-tools-x.x.x-windows.zip en C:\Users\<My User>\aem-sdk\dispatcher (creando las carpetas que faltan según sea necesario).
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

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 utilizar para lograr resultados similares.

Comprender los archivos de configuración de Dispatcher

TIP
Proyectos del Experience Manager creados a partir de AEM Arquetipo del proyecto Maven están rellenados previamente en este conjunto de archivos de configuración de Dispatcher, por lo que no es necesario copiar desde la carpeta src de herramientas de Dispatcher.

Las herramientas de Dispatcher proporcionan un conjunto de archivos de configuración de Apache HTTP Web Server y Dispatcher 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 a dispatcher/src , si no existen en el proyecto de Experience Manager Maven.

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

Validar configuraciones

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

macOS
code language-shell
$ ./bin/validate.sh ./src
Windows
code language-shell
$ bin\validate src
Linux®
code language-shell
$ ./bin/validate.sh ./src

Ejecutar Dispatcher localmente

AEM Dispatcher se ejecuta localmente mediante Docker en el src Archivos de configuración de Dispatcher y del servidor web Apache.

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

El docker_run_hot_reload se prefiere el ejecutable sobre docker_run ya que vuelve a cargar los archivos de configuración a medida que se modifican, sin tener que terminar ni reiniciar manualmente docker_run. Alternativamente, docker_run se puede utilizar, pero requiere finalizar y reiniciar manualmente docker_run cuando se cambian los archivos de configuración.

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>

El docker_run_hot_reload se prefiere el ejecutable sobre docker_run ya que vuelve a cargar los archivos de configuración a medida que se modifican, sin tener que terminar ni reiniciar manualmente docker_run. Alternativamente, docker_run se puede utilizar, pero requiere finalizar y reiniciar manualmente docker_run cuando se cambian los archivos de configuración.

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 IP del equipo host. Si la variable host.docker.internal no resuelve, consulte la solución de problemas más abajo.

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

Inicie el contenedor de Docker de Dispatcher y proporcione la ruta a la carpeta src de configuración de Dispatcher:

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

AEM El servicio de publicación del SDK as a Cloud Service, 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 del proyecto dispatcher/src carpeta.

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

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 las herramientas de Dispatcher se emiten a la salida estándar cuando docker_run se ejecuta.

Los parámetros útiles para depurar Dispatcher incluyen:

  • DISP_LOG_LEVEL=Debug establece el registro del módulo de Dispatcher en el nivel de depuración
    • El valor predeterminado es: Warn
  • REWRITE_LOG_LEVEL=Debug establece el registro del módulo de reescritura del servidor web HTTP Apache en el nivel de depuración
    • El valor predeterminado es: Warn
  • DISP_RUN_MODE establece el "modo de ejecución" del entorno de Dispatcher, cargando los modos de ejecución correspondientes y los archivos de configuración de Dispatcher.
    • El valor predeterminado es dev
  • Valores válidos: dev, stage, o prod

Se pueden pasar uno o varios parámetros a docker_run

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

Acceso a archivo de registro

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

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

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

AEM La versión recomendada de las herramientas de Dispatcher es la que está empaquetada con el SDK as a Cloud Service de que coincide con la versión as a Cloud Service de Experience Manager. AEM La versión de as a Cloud Service se encuentra en Cloud Manager.

  • Cloud Manager > Entornos, por entorno especificado por el AEM Versión de etiqueta

Versión del Experience Manager

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

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

AEM 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 del SDK as a Cloud Service de la. AEM Se recomienda incorporar las mejoras de configuración de línea de base en el proyecto de y evitar validación local Errores en la canalización de y Cloud Manager. Actualícelos con el update_maven.sh desde el .../dispatcher-sdk-x.x.x/bin carpeta.

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

AEM Supongamos que ha creado un proyecto en el pasado con el que se ha creado un proyecto de. AEM Tipo de archivo del proyecto, las configuraciones de línea base de Apache y Dispatcher estaban actualizadas. Con estas configuraciones de línea de base, las configuraciones específicas del proyecto se crearon reutilizando y copiando los archivos como *.vhost, *.conf, *.farm y *.any desde el dispatcher/src/conf.d y dispatcher/src/conf.dispatcher.d carpetas. La validación local de Dispatcher y las canalizaciones de Cloud Manager funcionaban correctamente.

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

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

  • Compruebe que la validación falle en la última versión de las herramientas de Dispatcher

    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!
    
  • Actualizar los archivos inmutables mediante la variable update_maven.sh script

    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
    
  • Verifique los archivos inmutables actualizados como dispatcher_vhost.conf, default.vhost, y default.farm y, si es necesario, realice los cambios relevantes en los archivos personalizados que se derivan de estos archivos.

  • Vuelva a validar la configuración y debería pasar.

$ ./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
  • Después de la verificación local de los cambios, confirme los archivos de configuración actualizados

Solución de problemas

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

El 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

Cuándo bin/docker_run src host.docker.internal:4503 8080 resultados en el mensaje Esperando hasta que host.docker.internal esté disponible y luego:

  1. Asegúrese de que la versión instalada de Docker sea 18.03 o superior
  2. Es posible que tenga configurado un equipo local que impida el registro/resolución del host.docker.internal nombre. En su lugar, utilice su IP local.
macOS
  • Desde el terminal, ejecute ifconfig y registrar el host inet Dirección IP, normalmente el en0 dispositivo.

  • A continuación, ejecutar docker_run uso de la dirección IP del host: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Windows
  • Desde el Símbolo del sistema, ejecute ipconfigy registre el del host. Dirección IPv4 del equipo host.

  • A continuación, ejecute docker_run con esta dirección IP: $ bin\docker_run src <HOST IP>:4503 8080

Linux®
  • Desde el terminal, ejecute ifconfig y registrar el host inet Dirección IP, normalmente el en0 dispositivo.

  • A continuación, ejecutar docker_run uso de la dirección IP del host: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

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

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