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 per la convalida della configurazione, situato in .../dispatcher-sdk-x.x.x/bin/validate (Dispatcher SDK 2.0.29+)
• 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
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
   • Verifica che AEM strumenti Dispatcher dell’SDK v2.0.29+ sia indicato nella descrizione del download

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.

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

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

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

Eseguire il Dispatcher localmente

Per eseguire il Dispatcher localmente, i file di configurazione del Dispatcher devono essere generati utilizzando lo strumento CLI validator di Dispatcher Tools.

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

Questo comando trasforma le configurazioni in un set di file compatibile con il server Web Apache HTTP del contenitore Docker.

Una volta generate, le configurazioni trasmesse vengono utilizzate per eseguire Dispatcher localmente nel contenitore Docker. È importante assicurarsi che le configurazioni più recenti siano state convalidate utilizzando l'output validate e utilizzando l'opzione -d della convalida.

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

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:

1. Genera da zero deployment-folder, denominato out per convenzione, ogni volta che una configurazione cambia:

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

2. (Riavvia il contenitore Docker di Dispatcher fornendo il percorso della cartella di distribuzione:

   • Windows: bin\docker_run out host.docker.internal:4503 8080
   • macOS / Linux: ./bin/docker_run.sh ./out 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, è sufficiente generare il deployment-folder utilizzando la cartella dispatcher/src del progetto.

• 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
  

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

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:

  $ 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
  

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

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 Dispatcher Tools

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

Esempio di errore

$ 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 restituisce l'errore '**: Cartella di distribuzione non trovata

Quando si esegue docker_run.cmd, viene visualizzato un errore che indica ** errore: Cartella di distribuzione non trovata:. Ciò si verifica in genere perché nel percorso sono presenti spazi. Se possibile, rimuovere gli spazi nella cartella oppure spostare la cartella aem-sdk in un percorso che non contenga spazi.

Ad esempio, le cartelle utente di Windows sono spesso <First name> <Last name>, con uno spazio intermedio. Nell’esempio seguente la cartella ...\My User\... contiene uno spazio che interrompe l’esecuzione degli strumenti Dispatcher locali docker_run. Se gli spazi si trovano in una cartella utente di Windows, non tentare di rinominare questa cartella in quanto interromperà Windows, ma spostare la cartella aem-sdk in una nuova posizione in cui l'utente dispone delle autorizzazioni per la modifica completa. Le istruzioni che presuppongono che la cartella aem-sdk si trovi nella home directory dell'utente devono essere regolate in base alla nuova posizione.

Esempio di errore

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

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

Risorse aggiuntive

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