Configurare strumenti Dispatcher locali

Dispatcher di Adobe Experience Manager (AEM) è un modulo server web Apache HTTP che fornisce sicurezza e prestazioni tra il livello di CDN e di pubblicazione AEM. Dispatcher è parte integrante dell’architettura complessiva di Experience Manager e necessario nella configurazione di sviluppo locale.

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

• un set di base di file di configurazione del server web HTTP Apache e del Dispatcher, che si trova in .../dispatcher-sdk-x.x.x/src
• uno strumento CLI per la convalida della configurazione, disponibile all'indirizzo .../dispatcher-sdk-x.x.x/bin/validate
• uno strumento CLI per la generazione della configurazione, disponibile all'indirizzo .../dispatcher-sdk-x.x.x/bin/validator
• uno strumento CLI per la distribuzione della configurazione, disponibile all'indirizzo .../dispatcher-sdk-x.x.x/bin/docker_run
• un file di configurazione immutabile che sovrascrive lo strumento CLI, disponibile all'indirizzo .../dispatcher-sdk-x.x.x/bin/update_maven
• un’immagine Docker che esegue il server web Apache HTTP con il modulo Dispatcher

Tieni presente che ~ viene utilizzato come abbreviazione per la directory utente. In Windows, equivale a %HOMEPATH%.

Prerequisiti

1. Gli utenti di Windows devono utilizzare Windows 10 Professional (o una versione che supporta Docker)
2. Installa Experience Manager Publish Quickstart Jar sulla macchina di sviluppo locale.

• Se necessario, installa la versione più recente Sito web di riferimento AEM sul servizio di pubblicazione locale AEM. Questo sito web viene utilizzato in questa esercitazione per visualizzare un’istanza di Dispatcher funzionante.

1. Installa e avvia la versione più recente di Docker (Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+) sul computer di sviluppo locale.

Scaricare gli strumenti di Dispatcher (come parte dell’SDK per AEM)

L’SDK per AEM as a Cloud Service, o AEM SDK, contiene gli strumenti di Dispatcher utilizzati per eseguire il server web Apache HTTP con il modulo Dispatcher localmente per lo sviluppo e il Jar QuickStart compatibile.

Se l’SDK as a Cloud Service dall’AEM è già stato scaricato in configurare il runtime AEM locale, non è necessario scaricarlo di nuovo.

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.propertyvalues.operation=equals&1_group.propertyvalues.0_values=tipo di software%3Atooling&orderby=%40jcr%3Acontent%2Fjcr%3AlastModified&orderby.sort=desc&layout=list&p.offset=0&p.limit=1) con il tuo Adobe ID
   • La tua organizzazione Adobe deve essere predisposto per AEM as a Cloud Service a scaricare l'SDK AEM as a Cloud Service
2. Fai clic sull’ultima SDK AEM riga dei risultati da scaricare

Estrarre gli strumenti di Dispatcher dallo zip dell’SDK dell’AEM

La versione degli strumenti di Dispatcher è diversa da quella dell’SDK dell’AEM. Assicurati che la versione degli strumenti di Dispatcher sia fornita tramite la versione dell’SDK per AEM corrispondente alla versione as a Cloud Service per AEM.

1. Decomprimi il download aem-sdk-xxx.zip file
2. Decomprimere gli strumenti di Dispatcher in ~/aem-sdk/dispatcher

$ 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

Tutti i comandi emessi di seguito presuppongono che la directory di lavoro corrente contenga il contenuto degli strumenti di 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 di Dispatcher

Gli strumenti di 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 sono destinati a essere copiati in un progetto Maven di Experience Manager in dispatcher/src , se non esistono già nel progetto Maven di Experience Manager.

Una descrizione completa dei file di configurazione è disponibile nella sezione Strumenti di Dispatcher non compressi come dispatcher-sdk-x.x.x/docs/Config.html.

Convalida configurazioni

Facoltativamente, le configurazioni del server web Dispatcher e Apache (tramite httpd -t) può essere convalidato utilizzando validate script (da non confondere con il validator eseguibile). Il validate script offre un modo pratico di eseguire tre fasi del validator.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Eseguire Dispatcher localmente

AEM Dispatcher viene eseguito localmente utilizzando Docker rispetto al src File di configurazione del server web Dispatcher e 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>

Il <aem-publish-host> può essere impostato su host.docker.internal, un nome DNS speciale fornito da Docker nel contenitore che viene risolto nell’IP del computer host. Se il host.docker.internal non si risolve, consulta la risoluzione dei problemi sezione successiva.

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

Avvia il contenitore Docker di Dispatcher che fornisce il percorso della cartella src di configurazione 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

Il servizio di pubblicazione dell’SDK per AEM as a Cloud Service, in esecuzione a livello locale sulla porta 4503, è disponibile tramite Dispatcher all’indirizzo http://localhost:8080.

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

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

Registri degli strumenti di Dispatcher

I registri di Dispatcher sono utili durante lo sviluppo locale per capire se e perché le richieste HTTP sono bloccate. Il livello di registro può essere impostato inserendo come prefisso l’esecuzione di docker_run con parametri di ambiente.

I registri degli strumenti di Dispatcher vengono emessi in uscita standard quando docker_run viene eseguito.

I parametri utili per il debug di Dispatcher includono:

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

Uno o più parametri che possono essere trasmessi 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

Accesso al file di registro

È possibile accedere direttamente ai registri del server web Apache e del Dispatcher AEM nel contenitore Docker:

• Accesso ai registri nel contenitore Docker
• Copia dei registri Docker nel file system locale

Quando aggiornare gli strumenti di Dispatcher

Le versioni degli strumenti di Dispatcher aumentano meno frequentemente rispetto all’Experience Manager e pertanto gli strumenti di Dispatcher richiedono meno aggiornamenti nell’ambiente di sviluppo locale.

La versione consigliata degli strumenti di Dispatcher è quella fornita in bundle con l’SDK as a Cloud Service dell’AEM che corrisponde alla versione as a Cloud Service dell’Experience Manager. La versione dell’AEM as a Cloud Service è disponibile tramite Cloud Manager.

• Cloud Manager > Ambienti, per ambiente specificato da Versione AEM etichetta

La versione degli strumenti di Dispatcher non corrisponde a quella dell’Experience Manager.

Come aggiornare il set di base delle configurazioni di Apache e Dispatcher

Il set di base della configurazione di Apache e Dispatcher viene regolarmente migliorato e rilasciato con la versione dell’SDK as a Cloud Service per l’AEM. È consigliabile incorporare i miglioramenti della configurazione di base nel progetto AEM ed evitare convalida locale Errori di pipeline di e Cloud Manager. Aggiornali utilizzando update_maven.sh script da .../dispatcher-sdk-x.x.x/bin cartella.

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

Supponiamo che tu abbia creato un progetto AEM in passato utilizzando Archetipo progetto AEM, le configurazioni di base di Apache e Dispatcher erano correnti. Utilizzando queste configurazioni di base, le configurazioni specifiche del progetto sono state create riutilizzando e copiando i file come *.vhost, *.conf, *.farm e *.any dal dispatcher/src/conf.d e dispatcher/src/conf.dispatcher.d cartelle. La convalida del Dispatcher locale e le pipeline di Cloud Manager funzionavano correttamente.

Nel frattempo, le configurazioni di base di Apache e Dispatcher sono state migliorate per vari motivi, come nuove funzioni, correzioni di sicurezza e ottimizzazione. Vengono rilasciati tramite una versione più recente degli Strumenti di Dispatcher nell’ambito del rilascio as a Cloud Service dell’AEM.

Ora, quando si convalidano le configurazioni del Dispatcher specifiche per il progetto rispetto alla versione più recente degli strumenti di Dispatcher, si verifica un errore. Per risolvere questo problema, è necessario aggiornare le configurazioni della linea di base utilizzando i passaggi seguenti:

• Verifica che la convalida non riesca rispetto alla versione più recente degli strumenti di Dispatcher

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

• Aggiornare i file immutabili utilizzando update_maven.sh script

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

• Verifica i file immutabili aggiornati come dispatcher_vhost.conf, default.vhost, e default.farm e, se necessario, apportare modifiche rilevanti ai file personalizzati derivati da tali file.

• Convalida nuovamente le configurazioni, il test deve superare

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

• Dopo la verifica locale delle modifiche, esegui il commit dei file di configurazione aggiornati

Risoluzione dei problemi

docker_run restituisce il messaggio 'In attesa della disponibilità di host.docker.internal'

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

A partire da Docker 18.03 si consiglia di connettersi al nome DNS speciale host.docker.internal, che viene risolto nell'indirizzo IP interno utilizzato dall'host

Quando bin/docker_run src host.docker.internal:4503 8080 risultati nel messaggio In attesa che host.docker.internal sia disponibile, quindi:

1. Verificare che la versione installata di Docker sia 18.03 o successiva
2. È possibile che sia stato configurato un computer locale che impedisce la registrazione/risoluzione del host.docker.internal nome. Utilizza piuttosto l’IP locale.

Errore di esempio

$ 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

Risorse aggiuntive

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