Impostare strumenti Dispatcher locali

Dispatcher di Adobe Experience Manager (AEM) è un modulo server web Apache HTTP che fornisce una protezione e prestazioni tra il livello CDN e AEM Publish. Dispatcher è parte integrante dell’architettura Experience Manager complessiva e deve far parte della configurazione dello sviluppo locale.

L’SDK di AEM come Cloud Service include la versione consigliata degli strumenti di Dispatcher, che facilita la configurazione, la convalida e la simulazione locale di Dispatcher. Gli strumenti di Dispatcher sono formati da:

• un set di base di file di configurazione del server web Apache HTTP e del Dispatcher, situato in .../dispatcher-sdk-x.x.x/src
• uno strumento CLI di convalida della configurazione, situato in .../dispatcher-sdk-x.x.x/bin/validate
• uno strumento CLI di generazione della configurazione, situato in .../dispatcher-sdk-x.x.x/bin/validator
• uno strumento CLI per la distribuzione della configurazione, situato in .../dispatcher-sdk-x.x.x/bin/docker_run
• un’immagine Docker che esegue il server Web Apache HTTP con il modulo Dispatcher

Tenere presente che ~ viene utilizzato come abbreviazione per la directory dell'utente. In Windows, è l’equivalente di %HOMEPATH%.

Prerequisiti

1. Gli utenti Windows devono utilizzare Windows 10 Professional (o una versione che supporti Docker)
2. Installa Experience Manager Publish Quickstart Jar sul computer di sviluppo locale.
   • Se necessario, installa l'ultimo sito Web di riferimento AEM sul servizio AEM Publish locale. Questo sito web viene utilizzato in questa esercitazione per visualizzare un’istanza di Dispatcher funzionante.
3. Installa e avvia la versione più recente di Docker (Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+) nel computer di sviluppo locale.

Download degli strumenti di Dispatcher (come parte dell’SDK AEM)

Il AEM come SDK di Cloud Service, o SDK AEM, contiene gli strumenti del Dispatcher utilizzati per eseguire il server Web Apache HTTP con il modulo Dispatcher locale per lo sviluppo, nonché il Jar QuickStart compatibile.

Se l'SDK di AEM come Cloud Service è già stato scaricato in setup the local AEM runtime, non è necessario scaricarlo nuovamente.

1. Accedi a [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.property.operation=equals&1_group.property.values.0_values=software-type%3Atooling&orderby=%40jcr%3Acontent%2Fjcr%3AlastModified&orderby.sort=desc&layout=list p.offset=0&p.limit=1) con il tuo Adobe ID
   • È necessario eseguire il provisioning della tua organizzazione Adobe per AEM come Cloud Service per scaricare l'AEM come Cloud Service SDK.
2. Fai clic sulla riga dei risultati dell'SDK AEM più recente da scaricare

Estrarre gli strumenti di Dispatcher dallo zip AEM SDK

La versione di Strumenti Dispatcher è diversa da quella dell’SDK AEM. Assicurati che la versione di Dispatcher Tools sia fornita tramite la versione SDK AEM che corrisponde al AEM come versione di Cloud Service.

1. Decomprimi il file aem-sdk-xxx.zip scaricato
2. Estrai gli strumenti del Dispatcher in ~/aem-sdk/dispatcher
   • Windows: Decomprimere aem-sdk-dispatcher-tools-x.x.x-windows.zip in C:\Users\<My User>\aem-sdk\dispatcher (creando le cartelle mancanti in base alle esigenze)
   • macOS / Linux: Esegui lo script shell associato aem-sdk-dispatcher-tools-x.x.x-unix.sh per decomprimere gli strumenti di Dispatcher
     • chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh && ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

Tutti i comandi emessi di seguito presuppongono che la directory di lavoro corrente contenga il contenuto degli strumenti Dispatcher in espansione.

Questo video utilizza macOS a scopo illustrativo. I comandi Windows/Linux equivalenti possono essere utilizzati per ottenere risultati simili

Comprendere i file di configurazione del Dispatcher

Gli strumenti Dispatcher forniscono un set di file di configurazione del server Web Apache HTTP e del Dispatcher che definiscono il comportamento per tutti gli ambienti, incluso lo sviluppo locale.

Questi file devono essere copiati in un progetto Experience Manager Maven nella cartella dispatcher/src , se non sono già presenti nel progetto Experience Manager Maven.

Una descrizione completa dei file di configurazione è disponibile in Strumenti Dispatcher decompressi come dispatcher-sdk-x.x.x/docs/Config.html.

Convalidare le configurazioni

Facoltativamente, le configurazioni del Dispatcher e del server Web Apache (tramite httpd -t) possono essere convalidate utilizzando lo script validate (da non confondere con l'eseguibile validator). Lo script validate fornisce un modo pratico di eseguire le 3 fasi del validator.

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

Eseguire il Dispatcher localmente

AEM Dispatcher viene eseguito localmente utilizzando Docker nei file di configurazione src Dispatcher e Apache Web Server.

• Utilizzo:
  • 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>

Il <aem-publish-host> può essere impostato su host.docker.internal, un Docker di nome DNS speciale fornisce nel contenitore che viene risolto nell'IP del computer host. Se host.docker.internal non viene risolto, consulta la sezione risoluzione dei problemi di seguito.

Ad esempio, per avviare il contenitore Docker Dispatcher utilizzando i file di configurazione predefiniti forniti dagli strumenti Dispatcher:

Avvia il contenitore Docker del Dispatcher fornendo il percorso della cartella src di configurazione del Dispatcher:

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

Il servizio Publish dell’SDK di AEM come Cloud Service, eseguito localmente sulla porta 4503, sarà disponibile tramite Dispatcher all’indirizzo http://localhost:8080.

Per eseguire gli strumenti di Dispatcher rispetto alla configurazione del Dispatcher di un progetto di Experience Manager, fai clic sulla cartella dispatcher/src del progetto.

• 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
  

Registri degli strumenti di Dispatcher

I registri del Dispatcher sono utili durante lo sviluppo locale per capire se e perché le richieste HTTP sono bloccate. È possibile impostare il livello di registro prefissando l’esecuzione di docker_run con i parametri di ambiente.

I registri degli strumenti del Dispatcher vengono emessi all’uscita standard quando viene eseguito docker_run.

I parametri utili per il debug di Dispatcher includono:

• DISP_LOG_LEVEL=Debug imposta la registrazione del modulo Dispatcher a livello di debug
  • Il valore predefinito è: Warn
• REWRITE_LOG_LEVEL=Debug imposta la registrazione del modulo di riscrittura del server Web HTTP Apache a livello di debug
  • Il valore predefinito è: Warn
• DISP_RUN_MODE imposta la "modalità di esecuzione" dell’ambiente Dispatcher, caricando i file di configurazione del Dispatcher delle modalità di esecuzione corrispondenti.
  • Impostazione predefinita dev
• Valori validi: dev, stage o prod

Uno o più parametri possono essere passati a 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
  

Accesso ai file di registro

I registri del server web Apache e del Dispatcher AEM sono accessibili direttamente nel contenitore Docker:

• Accesso ai registri nel contenitore Docker
• Copiare i log Docker nel file system locale

Quando aggiornare gli strumenti di Dispatcher

Le versioni degli strumenti di Dispatcher incrementano meno frequentemente dell’Experience Manager, pertanto gli strumenti di Dispatcher richiedono meno aggiornamenti nell’ambiente di sviluppo locale.

La versione consigliata di Dispatcher Tools è quella fornita con l’SDK di AEM as a Cloud Service che corrisponde alla versione di Experience Manager as a Cloud Service. La versione di AEM come Cloud Service può essere trovata tramite Cloud Manager.

• Cloud Manager > Ambienti, per ambiente specificato da AEM Releaselable

La versione stessa di Dispatcher Tools non corrisponde alla versione di Experience Manager.

Risoluzione dei problemi

docker_run restituisce il messaggio 'In attesa che host.docker.internal sia disponibile'

host.docker.internal è un nome host fornito al Docker contenente che viene risolto nell'host. Per docs.docker.com (macOS, Windows):

A partire da Docker 18.03 il nostro consiglio è di connettersi al nome DNS speciale host.docker.internal, che si risolve all'indirizzo IP interno utilizzato dall'host

Se, quando bin/docker_run src host.docker.internal:4503 8080 restituisce il messaggio In attesa che host.docker.internal sia disponibile, allora:

1. Verificare che la versione installata di Docker sia 18.03 o successiva
2. È possibile che sia stata impostata una macchina locale che impedisce la registrazione/risoluzione del nome host.docker.internal. Utilizza invece il tuo IP locale.
   • Windows:

     • Dal prompt dei comandi, eseguire ipconfig e registrare l'indirizzo IPv4 dell'host del computer host.

     • Quindi, esegui docker_run utilizzando questo indirizzo IP:

       bin\docker_run src <HOST IP>:4503 8080

   • macOS / Linux:

     • Dal terminale, esegui ifconfig e registra l'indirizzo IP host inet, in genere il dispositivo en0.

     • Quindi esegui docker_run utilizzando l'indirizzo IP host:

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

Esempio di errore

$ 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

docker_run non si avvia su Windows

L’esecuzione di docker_run su Windows può causare il seguente errore, impedendo l’avvio di Dispatcher. Si tratta di un problema segnalato con Dispatcher su Windows e verrà risolto in una versione futura.

Esempio di errore

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

Risorse aggiuntive

• Scaricare AEM SDK
• Adobe Cloud Manager
• Download Docker
• Scarica il sito web di riferimento AEM (WKND)
• Documentazione di Experience Manager Dispatcher