Konfigurera lokala Dispatcher-verktyg

Senaste uppdatering: 2024-01-26
  • Skapat för:
  • Beginner
    Developer

Adobe Experience Manager (AEM) Dispatcher är en Apache HTTP-webbservermodul som tillhandahåller ett säkerhets- och prestandalager mellan CDN- och AEM-publiceringsskiktet. Dispatcher är en viktig del av den övergripande Experience Manager-arkitekturen och bör ingå i den lokala utvecklingsmiljön.

AEM as a Cloud Service SDK innehåller den rekommenderade versionen av Dispatcher Tools som gör det lättare att konfigurera validering och simulera Dispatcher lokalt. Dispatcher Tools består av:

  • en basuppsättning med konfigurationsfiler för Apache HTTP-webbserver och Dispatcher, som finns på .../dispatcher-sdk-x.x.x/src
  • en konfigurationsvaliderare för CLI-verktyg, som finns på .../dispatcher-sdk-x.x.x/bin/validate
  • ett CLI-verktyg för konfigurationsgenerering som finns på .../dispatcher-sdk-x.x.x/bin/validator
  • ett CLI-verktyg för konfigurationsdistribution, som finns på .../dispatcher-sdk-x.x.x/bin/docker_run
  • en oföränderlig konfigurationsfil som skriver över CLI-verktyget, finns på .../dispatcher-sdk-x.x.x/bin/update_maven
  • en Docker-bild som kör Apache HTTP Web Server med modulen Dispatcher

Observera att ~ används som kortskrift för användarkatalogen. I Windows motsvarar detta %HOMEPATH%.

OBSERVERA

Videorna på den här sidan spelades in på macOS. Windows-användare kan följa med, men använda motsvarande Dispatcher Tools Windows-kommandon som finns i varje video.

Förutsättningar

  1. Windows-användare måste använda Windows 10 Professional (eller en version som stöder Docker)
  2. Installera Experience Manager Publish Quickstart JAR på den lokala utvecklingsdatorn.
  • Du kan också installera den senaste AEM webbplats på den lokala AEM. Den här webbplatsen används i den här självstudiekursen för att visualisera en fungerande Dispatcher.
  1. Installera och starta den senaste versionen av Docker (Docker Desktop 2.2.0.5+ / Docker Engine v19.03.9+) på den lokala utvecklingsdatorn.

Ladda ned Dispatcher Tools (som en del av AEM SDK)

Den AEM as a Cloud Service SDK, eller AEM SDK, innehåller Dispatcher-verktygen som används för att köra Apache HTTP-webbservern med Dispatcher-modulen lokalt för utveckling, och den kompatibla QuickStart Jar.

Om AEM as a Cloud Service SDK redan har hämtats till konfigurera lokal AEMbehöver den inte laddas ned på nytt.

  1. Logga in på [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=software-type%3Atooling&orderby=%40jcr%3Acontent%2Fjcr%3AlastModified&order.sort=desc&layout=list&list p.offset=0&p.limit=1) med din Adobe ID
    • Din Adobe-organisation måste etableras för AEM as a Cloud Service för att ladda ned AEM as a Cloud Service SDK
  2. Klicka på den senaste AEM SDK resultatrad som ska hämtas

Extrahera Dispatcher-verktygen från AEM SDK

TIPS

Windows-användare kan inte ha blanksteg eller specialtecken i sökvägen till mappen som innehåller Lokala Dispatcher-verktyg. Om det finns blanksteg i sökvägen docker_run.cmd misslyckas.

Versionen av Dispatcher Tools skiljer sig från AEM SDK. Kontrollera att versionen av Dispatcher Tools finns i den AEM SDK-version som matchar den AEM as a Cloud Service versionen.

  1. Zippa upp det nedladdade aem-sdk-xxx.zip fil
  2. Packa upp Dispatcher Tools i ~/aem-sdk/dispatcher
$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

Zippa upp aem-sdk-dispatcher-tools-x.x.x-windows.zip till C:\Users\<My User>\aem-sdk\dispatcher (skapar saknade mappar efter behov).

$ chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh
$ ./aem-sdk-dispatcher-tools-x.x.x-unix.sh

Alla kommandon som anges nedan förutsätter att den aktuella arbetskatalogen innehåller det expanderande Dispatcher-verktygsinnehållet.

I den här videon används macOS för illustrativa ändamål. Motsvarande Windows/Linux-kommandon kan användas för att uppnå liknande resultat.

Förstå Dispatcher-konfigurationsfilerna

TIPS

Experience Manager-projekt skapade från AEM Project Maven Archetype är förifyllda i den här uppsättningen Dispatcher-konfigurationsfiler, så du behöver inte kopiera över från Src-mappen Dispatcher Tools.

Dispatcher Tools innehåller en uppsättning konfigurationsfiler för Apache HTTP Web Server och Dispatcher som definierar beteendet för alla miljöer, inklusive lokal utveckling.

Filerna ska kopieras till ett Experience Manager Maven-projekt till dispatcher/src om de inte finns i Experience Manager Maven-projektet.

En fullständig beskrivning av konfigurationsfilerna finns i de opackade Dispatcher-verktygen som dispatcher-sdk-x.x.x/docs/Config.html.

Validera konfigurationer

Alternativt kan du konfigurera webbservern Dispatcher och Apache (via httpd -t) kan valideras med validate skript (ska inte blandas ihop med validator körbar). The validate är ett praktiskt sätt att köra tre faser i validator.

$ ./bin/validate.sh ./src
$ bin\validate src
$ ./bin/validate.sh ./src

Kör Dispatcher lokalt

AEM Dispatcher körs lokalt med Docker mot src Dispatcher och konfigurationsfiler för webbservern Apache.

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

The docker_run_hot_reload körbar fil föredras framför docker_run när konfigurationsfiler läses in igen när de ändras, utan att du behöver avsluta och starta om manuellt docker_run. Alternativt docker_run kan användas, men manuell avslutning och omstart krävs docker_run när konfigurationsfiler ändras.

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

The docker_run_hot_reload körbar fil föredras framför docker_run när konfigurationsfiler läses in igen när de ändras, utan att du behöver avsluta och starta om manuellt docker_run. Alternativt docker_run kan användas, men manuell avslutning och omstart krävs docker_run när konfigurationsfiler ändras.

The <aem-publish-host> kan anges till host.docker.internal, innehåller en särskild DNS-namnDocker i behållaren som matchar värddatorns IP-adress. Om host.docker.internal inte går att lösa, se felsökning nedan.

Om du till exempel vill starta Dispatcher Docker-behållaren med de standardkonfigurationsfiler som finns i Dispatcher-verktygen:

Starta Dispatcher Docker-behållaren med sökvägen till Dispatcher-konfigurationens src-mapp:

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

Den AEM as a Cloud Service SDK:s publiceringstjänst som körs lokalt på port 4503 är tillgänglig via Dispatcher på http://localhost:8080.

Om du vill köra Dispatcher Tools mot Dispatcher-konfigurationen för ett Experience Manager-projekt pekar du på projektets dispatcher/src mapp.

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

Loggar för Dispatcher Tools

Distributionsloggar är användbara under lokal utveckling för att förstå om och varför HTTP-begäranden blockeras. Loggnivån kan ställas in genom att prefix för körningen av docker_run med miljöparametrar.

Loggar för utskicksverktyg skickas till standard-out när docker_run är körd.

Användbara parametrar för felsökning av Dispatcher är:

  • DISP_LOG_LEVEL=Debug anger att inloggning i modulen Dispatcher ska vara felsökningsnivå
    • Standardvärdet är: Warn
  • REWRITE_LOG_LEVEL=Debug anger Apache HTTP Web server rewrite module loggning till Felsökningsnivå
    • Standardvärdet är: Warn
  • DISP_RUN_MODE anger körningsläget för Dispatcher-miljön och läser in motsvarande körningslägen Dispatcher-konfigurationsfiler.
    • Standardvärdet är dev
  • Giltiga värden: dev, stage, eller prod

En eller flera parametrar kan skickas till 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

Loggfilsåtkomst

Du kan komma åt Apache-webbservern och AEM Dispatcher-loggarna direkt i Docker-behållaren:

När Dispatcher Tools ska uppdateras

Dispatcher Tools-versionerna ökar inte lika ofta som Experience Manager och Dispatcher Tools kräver därför färre uppdateringar i den lokala utvecklingsmiljön.

Den rekommenderade versionen av Dispatcher Tools är den som medföljer AEM as a Cloud Service SDK som överensstämmer med den as a Cloud Service Experience Manager-versionen. Versionen av AEM as a Cloud Service finns via Cloud Manager.

  • Cloud Manager > Miljöer, per miljö som anges av AEM label

Experience Manager version

Observera att Dispatcher Tools-versionen inte överensstämmer med Experience Manager.

Så här uppdaterar du baslinjeuppsättningen med Apache- och Dispatcher-konfigurationer

Baslinjeuppsättningen av konfigurationen för Apache och Dispatcher förbättras regelbundet och släpps med den AEM as a Cloud Service SDK-versionen. Det är bästa sättet att införliva förbättringarna av baslinjekonfigurationen i AEM projekt och undvika lokal validering och fel i molnhanterarens pipeline. Uppdatera dem med update_maven.sh skript .../dispatcher-sdk-x.x.x/bin mapp.

I den här videon används macOS för illustrativa ändamål. Motsvarande Windows/Linux-kommandon kan användas för att uppnå liknande resultat.

Låt oss anta att du tidigare har skapat ett AEM projekt med AEM Project Archettypevar de ursprungliga konfigurationerna för Apache och Dispatcher aktuella. Med hjälp av dessa baslinjekonfigurationer har dina projektspecifika konfigurationer skapats genom att återanvända och kopiera filer som *.vhost, *.conf, *.farm och *.any från dispatcher/src/conf.d och dispatcher/src/conf.dispatcher.d mappar. Din lokala Dispatcher-validering och Cloud Manager-pipelines fungerade som de ska.

Samtidigt har Apache- och Dispatcher-konfigurationerna förbättrats för baslinjen av olika skäl, till exempel nya funktioner, säkerhetskorrigeringar och optimering. De släpps via en nyare version av Dispatcher Tools som en del av den AEM as a Cloud Service versionen.

När du validerar projektspecifika Dispatcher-konfigurationer mot den senaste Dispatcher Tools-versionen börjar de nu misslyckas. För att lösa detta måste baslinjekonfigurationerna uppdateras genom att följa stegen nedan:

  • Verifiera att valideringen inte fungerar med den senaste versionen av Dispatcher Tools

    $ ./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!
    
  • Uppdatera oföränderliga filer med 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
    
  • Verifiera uppdaterade oföränderliga filer som dispatcher_vhost.conf, default.vhostoch default.farm och vid behov göra relevanta ändringar i dina anpassade filer som härleds från dessa filer.

  • Verifiera konfigurationen på nytt, det bör gå

$ ./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
  • Efter lokal verifiering av ändringar implementerar du de uppdaterade konfigurationsfilerna

Felsökning

docker_run resulterar i meddelandet"Väntar tills host.docker.internal är tillgänglig"

The host.docker.internal är ett värdnamn som tillhandahålls Docker-behållaren som löses till värden. Per docs.docker.com (macOS, Windows):

Från och med Docker 18.03 rekommenderar vi att du ansluter till det särskilda DNS-namnet host.docker.internal, som matchar den interna IP-adressen som används av värden

När bin/docker_run src host.docker.internal:4503 8080 i meddelandet Väntar tills host.docker.internal är tillgänglig och sedan:

  1. Kontrollera att den installerade versionen av Docker är 18.03 eller senare
  2. Det kan finnas en lokal dator som förhindrar registrering/upplösning av host.docker.internal namn. Använd i stället din lokala IP-adress.
  • Från Terminal, kör ifconfig och registrera värden inet IP-adress, vanligtvis en0 enhet.

  • Kör sedan docker_run med hjälp av värdens IP-adress: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

  • Kör från kommandotolken ipconfigoch registrera värddatorns IPv4-adress värddatorn.

  • Kör sedan docker_run med denna IP-adress: $ bin\docker_run src <HOST IP>:4503 8080

  • Från Terminal, kör ifconfig och registrera värden inet IP-adress, vanligtvis en0 enhet.

  • Kör sedan docker_run med hjälp av värdens IP-adress: $ bin/docker_run_hot_reload.sh src <HOST IP>:4503 8080

  • Exempel på fel

    $ 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
    

    Ytterligare resurser

    På denna sida