로컬 Dispatcher 도구 설정 set-up-local-dispatcher-tools

Adobe Experience Manager(AEM)의 Dispatcher은 CDN과 AEM Publish 계층 간에 보안 및 성능 계층을 제공하는 Apache HTTP 웹 서버 모듈입니다. Dispatcher은 전체 Experience Manager 아키텍처의 필수적인 부분이며 로컬 개발 설정의 일부여야 합니다.

AEM as a Cloud Service SDK에는 Dispatcher을 로컬에서 구성 및 시뮬레이트할 수 있도록 해주는 권장 Dispatcher 도구 버전이 포함되어 있습니다. Dispatcher 도구는 다음과 같이 구성됩니다.

~은(는) 사용자 디렉터리의 약어로 사용됩니다. Windows에서는 %HOMEPATH%에 해당합니다.

사전 요구 사항

AEM SDK의 일부로 Dispatcher 도구 다운로드

AEM as a Cloud Service SDK 또는 AEM SDK에는 개발을 위해 로컬에서 Dispatcher 모듈을 사용하여 Apache HTTP 웹 서버를 실행하는 데 사용되는 Dispatcher 도구와 호환되는 QuickStart Jar가 포함되어 있습니다.

AEM as a Cloud Service SDK가 로컬 AEM 런타임을 설정에 이미 다운로드된 경우 다시 다운로드할 필요가 없습니다.

AEM SDK zip에서 Dispatcher 도구 추출

Dispatcher 도구 버전은 AEM SDK의 버전과 다릅니다. Dispatcher Tools 버전이 AEM as a Cloud Service 버전과 일치하는 AEM SDK 버전을 통해 제공되는지 확인하십시오.

$ 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

아래에 실행된 모든 명령은 현재 작업 디렉터리에 확장 중인 Dispatcher 도구 내용이 포함되어 있다고 가정합니다.

이 비디오에서는 설명 목적으로 macOS을 사용합니다. 동일한 Windows/Linux 명령을 사용하여 유사한 결과를 얻을 수 있습니다.

Dispatcher 구성 파일 이해

Dispatcher 도구는 로컬 개발을 포함하여 모든 환경에 대한 동작을 정의하는 일련의 Apache HTTP 웹 서버 및 Dispatcher 구성 파일을 제공합니다.

이러한 파일은 Experience Manager Maven 프로젝트에 없는 경우 dispatcher/src 폴더로 Experience Manager Maven 프로젝트에 복사됩니다.

구성 파일에 대한 자세한 설명은 압축을 푼 Dispatcher 도구에서 dispatcher-sdk-x.x.x/docs/Config.html(으)로 사용할 수 있습니다.

구성 유효성 검사

선택적으로 httpd -t을(를) 통해 Dispatcher 및 Apache 웹 서버 구성을 validate 스크립트를 사용하여 확인할 수 있습니다(validator 실행 파일과 혼동하지 않도록 함). validate 스크립트는 validator의 3단계를 편리하게 실행할 수 있는 방법을 제공합니다.

$ ./bin/validate.sh ./src

$ bin\validate src

$ ./bin/validate.sh ./src

로컬에서 Dispatcher 실행

AEM Dispatcher은 src Dispatcher 및 Apache 웹 서버 구성 파일에 대해 Docker를 사용하여 로컬로 실행됩니다.

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

<aem-publish-host>을(를) host.docker.internal(으)로 설정할 수 있습니다. 특수 DNS 이름 Docker는 호스트 컴퓨터의 IP로 확인되는 컨테이너에 제공됩니다. host.docker.internal이(가) 해결되지 않으면 아래의 문제 해결 섹션을 참조하십시오.

예를 들어 Dispatcher 도구에서 제공하는 기본 구성 파일을 사용하여 Dispatcher Docker 컨테이너를 시작하려면 다음을 수행하십시오.

Dispatcher 구성 src 폴더의 경로를 제공하는 Dispatcher Docker 컨테이너를 시작합니다.

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

포트 4503에서 로컬로 실행되는 AEM as a Cloud Service SDK의 Publish 서비스는 http://localhost:8080의 Dispatcher을 통해 사용할 수 있습니다.

Experience Manager 프로젝트의 Dispatcher 구성에 대해 Dispatcher 도구를 실행하려면 프로젝트의 dispatcher/src 폴더를 가리킵니다.

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

Dispatcher 도구 로그

Dispatcher 로그는 HTTP 요청이 차단되었는지 여부와 그 이유를 로컬 개발 중에 이해하는 데 유용합니다. 환경 매개 변수를 사용하여 docker_run의 실행을 접두사로 지정하여 로그 수준을 설정할 수 있습니다.

docker_run이(가) 실행되면 Dispatcher 도구 로그가 표준으로 내보내집니다.

Dispatcher 디버깅에 유용한 매개 변수는 다음과 같습니다.

하나 이상의 매개 변수를 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

로그 파일 액세스

Docker 컨테이너에서 Apache 웹 서버 및 AEM Dispatcher 로그에 직접 액세스할 수 있습니다.

Dispatcher 도구를 업데이트해야 하는 경우 dispatcher-tools-version

Dispatcher Tools 버전은 Experience Manager에 비해 덜 자주 증가하므로 Dispatcher Tools는 로컬 개발 환경에서 더 적은 업데이트를 필요로 합니다.

권장되는 Experience Manager 도구 버전은 Dispatcher as a Cloud Service 버전과 일치하는 AEM as a Cloud Service SDK와 번들로 제공되는 것입니다. AEM as a Cloud Service 버전은 Cloud Manager을 통해 찾을 수 있습니다.

Dispatcher 도구 버전이 Experience Manager 버전과 일치하지 않습니다.

Apache 및 Dispatcher 구성의 기본 세트를 업데이트하는 방법

Apache 및 Dispatcher 구성의 기본 세트가 정기적으로 향상되고 AEM as a Cloud Service SDK 버전과 함께 릴리스됩니다. 기본 구성 개선 사항을 AEM 프로젝트에 통합하고 로컬 유효성 검사 및 Cloud Manager 파이프라인 오류를 방지하는 것이 좋습니다. .../dispatcher-sdk-x.x.x/bin 폴더의 update_maven.sh 스크립트를 사용하여 업데이트합니다.

이 비디오에서는 설명 목적으로 macOS을 사용합니다. 동일한 Windows/Linux 명령을 사용하여 유사한 결과를 얻을 수 있습니다.

이전에 AEM Project Archetype을(를) 사용하여 AEM 프로젝트를 만들었다고 가정해 보겠습니다. 기본 Apache 및 Dispatcher 구성은 최신 버전입니다. 이러한 기준 구성을 사용하여 dispatcher/src/conf.d 및 dispatcher/src/conf.dispatcher.d 폴더에서 *.vhost, *.conf, *.farm 및 *.any과(와) 같은 파일을 다시 사용하고 복사하여 프로젝트별 구성을 만들었습니다. 로컬 Dispatcher 유효성 검사 및 Cloud Manager 파이프라인이 제대로 작동하고 있었습니다.

한편, 새로운 기능, 보안 수정 및 최적화와 같은 다양한 이유로 인해 기본 Apache 및 Dispatcher 구성이 개선되었습니다. AEM as a Cloud Service 릴리스의 일부로 Dispatcher Tools 의 최신 버전을 통해 릴리스됩니다.

이제, 최신 Dispatcher 도구 버전에 대해 프로젝트별 Dispatcher 구성의 유효성을 검사할 때 오류가 발생하기 시작합니다. 이 문제를 해결하려면 아래 단계를 사용하여 기준 구성을 업데이트해야 합니다.

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

문제 해결

docker_run 결과 'host.docker.internal을 사용할 수 있을 때까지 대기 중' 메시지 troubleshooting-host-docker-internal

host.docker.internal은(는) 호스트로 확인되는 Docker에 제공된 호스트 이름입니다. docs.docker.com에 따라(macOS, Windows):

Docker 18.03 이상에서는 특별 DNS 이름 host.docker.internal에 연결하는 것이 좋습니다. 이 이름은 호스트가 사용하는 내부 IP 주소로 확인됩니다

bin/docker_run src host.docker.internal:4503 8080에서 host.docker.internal을 사용할 수 있을 때까지 대기 중 ​이라는 메시지가 표시되면 다음을 수행합니다.

오류 예

$ 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

추가 리소스