Configurare strumenti Dispatcher locali set-up-local-dispatcher-tools

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

L’SDK di AEM as a Cloud Service include la versione consigliata degli strumenti Dispatcher che facilita la configurazione della convalida e la simulazione locale di Dispatcher. Strumenti di Dispatcher è composto da:

~ viene utilizzato come abbreviazione per la directory dell'utente. In Windows equivale a %HOMEPATH%.

Prerequisiti

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

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

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

Estrarre gli strumenti Dispatcher dallo zip dell’SDK 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 AEM corrispondente alla versione di AEM as a Cloud Service.

$ 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. È possibile utilizzare i comandi Windows/Linux equivalenti 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 di Dispatcher che definiscono il comportamento per tutti gli ambienti, incluso lo sviluppo locale.

Questi file devono essere copiati in un progetto Maven di Experience Manager nella cartella dispatcher/src, se non esistono nel progetto Maven di Experience Manager.

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

Convalida configurazioni

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

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

Eseguire Dispatcher localmente

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

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

È possibile impostare <aem-publish-host> su host.docker.internal, un nome DNS speciale fornito da Docker nel contenitore che viene risolto nell'IP del computer host. Se host.docker.internal non si risolve, vedere la sezione risoluzione dei problemi di seguito.

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 Publish dell'SDK AEM as a Cloud Service, in esecuzione localmente sulla porta 4503, è disponibile tramite Dispatcher all'indirizzo http://localhost:8080.

Per eseguire gli strumenti di Dispatcher in base alla configurazione Dispatcher di un progetto Experience Manager, posizionare il puntatore del mouse sulla cartella dispatcher/src del progetto.

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

I registri di 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 dell'ambiente.

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

I parametri utili per il debug di Dispatcher includono:

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

Quando aggiornare gli strumenti Dispatcher dispatcher-tools-version

Le versioni di Dispatcher Tools aumentano meno frequentemente rispetto all’Experience Manager, pertanto Dispatcher Tools richiede meno aggiornamenti nell’ambiente di sviluppo locale.

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

La versione degli strumenti di Dispatcher non corrisponde alla versione dell'Experience Manager.

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

Il set di base della configurazione di Apache e Dispatcher viene regolarmente migliorato e rilasciato con la versione SDK di AEM as a Cloud Service. È consigliabile incorporare i miglioramenti alla configurazione di base nel progetto AEM ed evitare la convalida locale e gli errori della pipeline Cloud Manager. Aggiornarli utilizzando lo script update_maven.sh della cartella .../dispatcher-sdk-x.x.x/bin.

Questo video utilizza macOS a scopo illustrativo. È possibile utilizzare i comandi Windows/Linux equivalenti 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 file come *.vhost, *.conf, *.farm e *.any dalle cartelle dispatcher/src/conf.d e dispatcher/src/conf.dispatcher.d. La convalida Dispatcher locale e le pipeline 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 di Dispatcher Tools come parte del rilascio di AEM as a Cloud Service.

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

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

Risoluzione dei problemi

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

host.docker.internal è un nome host fornito al Docker che viene risolto nell'host. Secondo 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 restituisce il messaggio In attesa che host.docker.internal sia disponibile, allora:

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