Configurar ferramentas locais do Dispatcher set-up-local-dispatcher-tools

O Dispatcher AEM do Adobe Experience Manager (AEM) é um módulo de servidor Web Apache HTTP que fornece uma camada de segurança e desempenho entre o nível do CDN e do Publish. O Dispatcher é parte integrante da arquitetura geral de Experience Manager e deve fazer parte da configuração de desenvolvimento local.

O SDK do AEM as a Cloud Service inclui a versão recomendada das Ferramentas do Dispatcher, que facilita a configuração, validação e simulação do Dispatcher localmente. O Dispatcher Tools é composto por:

  • um conjunto de linhas de base de arquivos de configuração do Apache HTTP Web Server e do Dispatcher, localizado em .../dispatcher-sdk-x.x.x/src
  • uma ferramenta CLI do validador de configuração, localizada em .../dispatcher-sdk-x.x.x/bin/validate
  • uma ferramenta de CLI de geração de configuração, localizada em .../dispatcher-sdk-x.x.x/bin/validator
  • uma ferramenta de CLI de implantação de configuração, localizada em .../dispatcher-sdk-x.x.x/bin/docker_run
  • arquivos de configuração imutáveis substituindo a ferramenta CLI, localizados em .../dispatcher-sdk-x.x.x/bin/update_maven
  • uma imagem Docker que executa o Apache HTTP Web Server com o módulo Dispatcher

Observe que ~ é usado como abreviação para o Diretório do Usuário. No Windows, é equivalente a %HOMEPATH%.

NOTE
Os vídeos desta página foram gravados no macOS. Os usuários do Windows podem seguir, mas usar os comandos equivalentes do Windows Ferramentas do Dispatcher, fornecidos com cada vídeo.

Pré-requisitos

  1. Os usuários do Windows devem usar o Windows 10 Professional (ou uma versão que ofereça suporte ao Docker)
  2. Instale o Experience Manager Publish Quickstart Jar na máquina de desenvolvimento local.
  • Opcionalmente, instale o site de referência do AEM mais recente no serviço AEM Publish local. Este site é usado neste tutorial para visualizar um Dispatcher funcional.
  1. Instale e inicie a versão mais recente do Docker (Docker Desktop 2.2.0.5+/Docker Engine v19.03.9+) na máquina de desenvolvimento local.

Baixe as Ferramentas do Dispatcher (como parte do AEM SDK)

O SDK do AEM as a Cloud Service, ou AEM SDK, contém as Ferramentas do Dispatcher usadas para executar o Apache HTTP Web Server com o módulo do Dispatcher localmente para desenvolvimento e o QuickStart Jar compatível.

Se o SDK do AEM as a Cloud Service já tiver sido baixado para configurar o tempo de execução do AEM local, ele não precisará ser baixado novamente.

  1. Faça logon em experience.adobe.com/#/downloads com sua Adobe ID
    • Sua Organização Adobe deve ser provisionada para que o AEM as a Cloud Service baixe o SDK da AEM as a Cloud Service
  2. Clique na linha de resultado AEM SDK mais recente para baixar

Extraia as ferramentas do Dispatcher do zip do SDK AEM

TIP
Os usuários do Windows não podem ter espaços ou caracteres especiais no caminho para a pasta que contém as Ferramentas locais do Dispatcher. Se houver espaços no caminho, docker_run.cmd falhará.

A versão das Ferramentas do Dispatcher é diferente da do AEM SDK. Verifique se a versão das Ferramentas do Dispatcher é fornecida por meio da versão do AEM SDK correspondente à versão do AEM as a Cloud Service.

  1. Descompacte o arquivo aem-sdk-xxx.zip baixado
  2. Descompactar as Ferramentas do Dispatcher em ~/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
Descompacte aem-sdk-dispatcher-tools-x.x.x-windows.zip em C:\Users\<My User>\aem-sdk\dispatcher (criando pastas ausentes conforme necessário).
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 os comandos emitidos abaixo pressupõem que o diretório de trabalho atual contém o conteúdo de expansão das Ferramentas do Dispatcher.

Este vídeo usa o macOS para fins ilustrativos. Os comandos equivalentes do Windows/Linux podem ser usados para obter resultados semelhantes.

Entender os arquivos de configuração do Dispatcher

TIP
Os projetos Experience Manager criados a partir do Arquétipo Maven do projeto AEM são preenchidos previamente com esse conjunto de arquivos de configuração do Dispatcher, portanto, não há necessidade de copiar da pasta src das Ferramentas do Dispatcher.

As Ferramentas do Dispatcher fornecem um conjunto de arquivos de configuração do Apache HTTP Web Server e do Dispatcher que definem o comportamento de todos os ambientes, incluindo o desenvolvimento local.

Esses arquivos devem ser copiados em um projeto Maven Experience Manager para a pasta dispatcher/src, se não existirem no projeto Maven Experience Manager.

Uma descrição completa dos arquivos de configuração está disponível nas Ferramentas do Dispatcher descompactadas como dispatcher-sdk-x.x.x/docs/Config.html.

Validar configurações

Como opção, as configurações do servidor Web Dispatcher e Apache (via httpd -t) podem ser validadas usando o script validate (não deve ser confundido com o executável validator). O script validate fornece uma maneira conveniente de executar as três fases de validator.

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

Executar o Dispatcher localmente

O AEM Dispatcher é executado localmente usando o Docker em relação aos arquivos de configuração do Dispatcher e do Apache Web Server src.

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

O executável docker_run_hot_reload é preferível sobre docker_run, pois recarrega os arquivos de configuração à medida que são alterados, sem precisar encerrar e reiniciar manualmente o docker_run. Alternativamente, docker_run pode ser usado, mas requer o encerramento e a reinicialização manual de docker_run quando os arquivos de configuração forem alterados.

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>

O executável docker_run_hot_reload é preferível sobre docker_run, pois recarrega os arquivos de configuração à medida que são alterados, sem precisar encerrar e reiniciar manualmente o docker_run. Alternativamente, docker_run pode ser usado, mas requer o encerramento e a reinicialização manual de docker_run quando os arquivos de configuração forem alterados.

O <aem-publish-host> pode ser definido como host.docker.internal, um nome DNS especial que o Docker fornece no contêiner que é resolvido para o IP do computador host. Se o host.docker.internal não resolver, consulte a seção solução de problemas abaixo.

Por exemplo, para iniciar o contêiner do Dispatcher Docker usando os arquivos de configuração padrão fornecidos pelas Ferramentas do Dispatcher:

Inicie o contêiner do Dispatcher Docker fornecendo o caminho para a pasta src de configuração do 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

O serviço Publish do SDK do AEM as a Cloud Service, executado localmente na porta 4503, está disponível por meio do Dispatcher em http://localhost:8080.

Para executar as Ferramentas do Dispatcher em uma configuração Dispatcher do projeto Experience Manager, aponte para a pasta dispatcher/src do projeto.

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

Logs de ferramentas do Dispatcher

Os logs do Dispatcher são úteis durante o desenvolvimento local para entender se e por que as solicitações HTTP são bloqueadas. O nível de log pode ser definido prefixando a execução de docker_run com parâmetros de ambiente.

Os logs das Ferramentas do Dispatcher são emitidos para o padrão quando docker_run é executado.

Parâmetros úteis para depuração do Dispatcher incluem:

  • DISP_LOG_LEVEL=Debug define o log do módulo Dispatcher para o nível de Depuração
    • O valor padrão é: Warn
  • REWRITE_LOG_LEVEL=Debug define o log do módulo de regravação do Apache HTTP Web server para o nível de Depuração
    • O valor padrão é: Warn
  • O DISP_RUN_MODE define o "modo de execução" do ambiente Dispatcher, carregando os arquivos de configuração Dispatcher dos modos de execução correspondentes.
    • O padrão é dev
  • Valores válidos: dev, stage ou prod

Um ou vários parâmetros, podem ser passados para 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

Acesso ao arquivo de log

O servidor Web Apache e os logs do Dispatcher do AEM podem ser acessados diretamente no contêiner Docker:

Quando atualizar as Ferramentas do Dispatcher dispatcher-tools-version

As versões das Ferramentas do Dispatcher são incrementadas com menos frequência do que o Experience Manager e, portanto, as Ferramentas do Dispatcher exigem menos atualizações no ambiente de desenvolvimento local.

A versão recomendada das Ferramentas do Dispatcher é aquela fornecida com o SDK do AEM as a Cloud Service que corresponde à versão as a Cloud Service do Experience Manager. A versão do AEM as a Cloud Service pode ser encontrada via Cloud Manager.

  • Cloud Manager > Ambientes, por ambiente especificado pelo rótulo Versão do AEM

Versão do Experience Manager

Observe que a versão do Dispatcher Tools não corresponde à versão do Experience Manager.

Como atualizar o conjunto de linhas de base de configurações do Apache e Dispatcher

O conjunto de linhas de base de configuração do Apache e do Dispatcher é aprimorado regularmente e lançado com a versão do SDK do AEM as a Cloud Service. É uma prática recomendada incorporar as melhorias na configuração da linha de base ao seu projeto AEM e evitar validação local e falhas de pipeline do Cloud Manager. Atualize-os usando o script update_maven.sh da pasta .../dispatcher-sdk-x.x.x/bin.

Este vídeo usa o macOS para fins ilustrativos. Os comandos equivalentes do Windows/Linux podem ser usados para obter resultados semelhantes.

Suponhamos que você tenha criado um projeto AEM no passado usando o Arquétipo de projeto AEM, as configurações de linha de base do Apache e do Dispatcher eram atuais. Usando essas configurações de linha de base, as configurações específicas do seu projeto foram criadas com a reutilização e a cópia de arquivos como *.vhost, *.conf, *.farm e *.any das pastas dispatcher/src/conf.d e dispatcher/src/conf.dispatcher.d. A validação local do Dispatcher e os pipelines do Cloud Manager estavam funcionando bem.

Enquanto isso, as configurações de linha de base do Apache e Dispatcher foram aprimoradas por vários motivos, como novos recursos, correções de segurança e otimização. Eles são lançados com uma versão mais recente das Ferramentas do Dispatcher como parte da versão do AEM as a Cloud Service.

Agora, ao validar as configurações específicas do Dispatcher do projeto em relação à versão mais recente das Ferramentas do Dispatcher, elas começam a falhar. Para resolver isso, as configurações de linha de base precisam ser atualizadas usando as etapas abaixo:

  • Verifique se a validação está falhando em relação à versão mais recente das Ferramentas do 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!
    
  • Atualizar os arquivos imutáveis usando o script update_maven.sh

    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 os arquivos imutáveis atualizados, como dispatcher_vhost.conf, default.vhost e default.farm e, se necessário, faça alterações relevantes em seus arquivos personalizados derivados desses arquivos.

  • Revalidar a configuração, ela deve passar

$ ./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
  • Após a verificação local das alterações, confirme os arquivos de configuração atualizados

Resolução de problemas

docker_run resulta na mensagem 'Aguardando até que host.docker.internal esteja disponível' troubleshooting-host-docker-internal

O host.docker.internal é um nome de host fornecido para o Docker que é resolvido para o host. Por docs.docker.com (macOS, Windows):

A partir do Docker 18.03, a recomendação é se conectar ao nome DNS especial host.docker.internal, que é resolvido para o endereço IP interno usado pelo host

Quando bin/docker_run src host.docker.internal:4503 8080 resulta na mensagem Aguardando até que host.docker.internal esteja disponível, então:

  1. Verifique se a versão instalada do Docker é 18.03 ou superior
  2. Talvez você tenha um computador local configurado que esteja impedindo o registro/resolução do nome host.docker.internal. Em vez disso, use o IP local.
macOS
  • No Terminal, execute ifconfig e registre o endereço IP do Host inet, geralmente o dispositivo en0.

  • Em seguida, execute docker_run usando o endereço IP do host: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Windows
  • No Prompt de Comando, execute ipconfig e registre o Endereço IPv4 do host do computador host.

  • Em seguida, execute docker_run usando este endereço IP: $ bin\docker_run src <HOST IP>:4503 8080

Linux®
  • No Terminal, execute ifconfig e registre o endereço IP do Host inet, geralmente o dispositivo en0.

  • Em seguida, execute docker_run usando o endereço IP do host: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

Exemplo de erro

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

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