Cloud Manager의 빌드 환경 build-environment

Cloud Manager의 빌드 환경과 코드 빌드 및 테스트 방법에 대해 알아봅니다.

TIP
이 문서에서는 AEM as a Cloud Service 프로젝트 개발을 위한 Cloud Manager의 빌드 환경에 대해 설명합니다. AEM as a Cloud Service에서 콘텐츠 작성을 위해 지원하는 클라이언트 플랫폼에 대한 자세한 내용은 지원되는 클라이언트 플랫폼을 참조하십시오.

빌드 환경 세부 정보 build-environment-details

Cloud Manager는 특수 빌드 환경을 사용하여 코드를 빌드하고 테스트합니다.

  • 빌드 환경은 Linux 기반이며 Ubuntu 22.04에서 파생되었습니다.

  • Apache Maven 3.9.4가 설치되어 있습니다.

  • 설치된 Java 버전은 Oracle JDK 11.0.22, Oracle JDK 17.0.10, Oracle JDK 21.0.4 및 Oracle JDK 25.0.2입니다.

  • 중요: 기본적으로 JAVA_HOME 환경 변수는 Oracle JDK 8u401을 포함하는 /usr/lib/jvm/jdk1.8.0_401(으)로 설정됩니다. Maven JDK 버전을 설정하여 AEM Cloud Service 프로젝트에 대한 이 기본값을 재정의합니다.

  • 몇 가지 추가 필수 시스템 패키지가 설치되어 있습니다.

    • bzip2
    • unzip
    • libpng
    • imagemagick
    • graphicsmagick
  • 추가 시스템 패키지 설치 섹션에 설명된 대로 빌드 시 다른 패키지가 설치됩니다.

  • 각 빌드는 새 환경에서 실행되며, 빌드 컨테이너는 실행 간에 데이터를 유지하지 않습니다.

  • Maven은 항상 다음 세 가지 명령을 사용하여 실행됩니다.

    • mvn --batch-mode org.apache.maven.plugins:maven-dependency-plugin:3.1.2:resolve-plugins
    • mvn --batch-mode org.apache.maven.plugins:maven-clean-plugin:3.1.0:clean -Dmaven.clean.failOnError=false
    • mvn --batch-mode org.jacoco:jacoco-maven-plugin:prepare-agent package
  • Maven은 adobe-public이라는 프로필을 사용하여 자동으로 공개 Adobe 아티팩트 저장소를 포함하는 settings.xml 파일로 시스템 수준에서 구성됩니다. 자세한 내용은 Adobe 공개 Maven 저장소를 참조하십시오.

NOTE
Cloud Manager에서 jacoco-maven-plugin의 버전을 지정하지 않습니다. 빌드 JDK 및 컴파일된 코드를 지원하는 버전을 구성합니다. 빌드 요구 사항을 참조하세요.

HTTPS Maven 저장소 https-maven

Maven 저장소 및 미러에 HTTPS URL을 사용합니다. Maven 기본적으로 외부 HTTP 저장소를 차단합니다. 이로 인해 종속성 또는 플러그인 다운로드가 실패할 수 있습니다. 빌드가 HTTP 저장소를 참조하는 경우 HTTPS 끝점을 사용하도록 저장소 또는 미러 구성을 업데이트합니다.

특정 Java 버전 사용 using-java-support

Cloud Manager 빌드 프로세스는 Oracle 8 JDK를 사용하여 기본적으로 프로젝트를 빌드하지만 AEM Cloud Service 고객은 Maven 실행 JDK 버전을 25, 21, 17 또는 11로 설정해야 합니다.

빌드 JDK는 Maven을 실행하고, 컴파일러 대상은 코드에서 타깃팅된 Java 릴리스를 결정하고, AEM 런타임은 배포된 응용 프로그램을 실행합니다. 서로 다른 설정입니다. 아래 섹션에서는 빌드 구성 및 업그레이드 사전 요구 사항을 다룹니다. Java 25별 요구 사항 및 옵트인 옵션에 대해서는 Java 25 지원을 참조하십시오.

Maven JDK 버전 설정 alternate-maven-jdk-version

Maven 실행 JDK를 설정하려면 파이프라인에서 사용하는 Git 저장소 분기에 .cloudmanager/java-version(이)라는 파일을 만드십시오. 파일에는 주 버전 번호 25, 21, 17 또는 11만 포함되어야 합니다. Cloud Manager은 해당 Oracle JDK를 사용합니다. Cloud Manager에서도 8을(를) 허용하지만 이 버전은 더 이상 AEM Cloud Service 프로젝트에 지원되지 않습니다. 다른 값은 무시됩니다.

이 파일은 컴파일러 대상이 아닌 Maven을 실행하는 JDK를 선택합니다. 기본 AEM 런타임은 현재 Java 21입니다. JDK 25를 사용하여 빌드하면 컴파일러 대상에 관계없이 대상 환경을 Java 25 런타임으로 옵트인합니다. 25을(를) 선택하기 전에 Java 25 지원을 검토하십시오.

최신 Java 버전으로 마이그레이션하기 위한 사전 요구 사항 prereq-for-building

Java 21 또는 Java 17로 빌드하기 위해 Cloud Manager은 이제 이러한 Java 버전과 호환되는 SonarQube 9.9를 사용합니다. 이 변경 사항은 Cloud Manager 릴리스 2025.1.0에 도입되었습니다. SonarQube를 업그레이드하기 위해 고객 작업이 필요하지 않습니다. 자세한 내용을 보고 변경 내용을 이해하려면 Cloud Manager 2025.1.0용 릴리스 노트를 참조하십시오.

빌드 JDK 변경의 경우 대상 버전에 대한 빌드 시간 요구 사항을 검토하십시오. 런타임 전용 변경의 경우 대상 런타임에 대한 요구 사항을 검토하십시오. 빌드 JDK는 변경할 필요가 없습니다. 응용 프로그램을 새 Java 빌드 버전 또는 런타임 버전으로 마이그레이션할 때 프로덕션에 배포하기 전에 개발 및 스테이지 환경에서 철저하게 테스트하십시오.

Adobe은 다음 배포 전략을 권장합니다.

  1. 의도한 Java 런타임을 지원하는 AEM Cloud Service SDK 버전을 다운로드합니다. 해당 런타임으로 SDK을 실행하고, 애플리케이션을 배포하고, 기능을 확인합니다. 로그에서 클래스 로드 또는 바이트코드 연결 오류를 확인합니다.
  2. 빌드 JDK 변경의 경우 Cloud Manager 저장소의 분기에서 Maven JDK을(를) 구성하고, 이 분기를 사용하도록 DEV 파이프라인을 구성한 다음 파이프라인을 실행합니다. 런타임 전용 변경의 경우 런타임 구성을 적용하고 환경 업데이트를 기다립니다. 응용 프로그램을 재구축할 필요는 없습니다. 유효성 검사 테스트를 실행합니다.
  3. 개발에서 결과가 만족스러우면 프로덕션으로 진행하기 전에 동일한 변경 사항을 단계에 적용하고 유효성을 검사하십시오.

런타임 요구 사항 runtime-requirements

다음 요구 사항은 Java 21 런타임​에 적용됩니다. Java 25의 경우 별도의 Java 25 런타임 요구 사항을 사용하십시오.

  • ASM의 최소 버전:
    org.ow2.asm.* 아티팩트에 번들로 제공되는 Java 패키지 org.objectweb.asm의 사용을 버전 9.8 이상으로 업데이트하여 최신 JVM 런타임 지원을 보장합니다.

  • Groovy의 최소 버전:
    최신 JVM 런타임 지원을 위해 Java 패키지 org.apache.groovy 또는 org.codehaus.groovy의 사용을 버전 4.0.22 이상으로 업데이트합니다.

    이 번들은 AEM Groovy Console과 같은 서드파티 종속성을 추가함으로써 간접적으로 포함될 수 있습니다.

  • Aries SPIFly의 최소 버전:
    최신 JVM 런타임 지원을 위해 Java 패키지 org.apache.aries.spifly.dynamic.bundle의 사용을 버전 1.3.6 이상으로 업데이트합니다.

빌드 시간 요구 사항 build-time-reqs

Java 21 및 Java 17을 사용하여 프로젝트를 작성할 수 있으려면 다음 조정이 필요합니다. 이전 Java 버전과 호환되므로 Java 21 및 Java 17을 실행하기 전이라도 업데이트할 수 있습니다.

Java 25 빌드의 경우 Java 25 빌드 요구 사항도 따르십시오. 아래의 최소 버전만으로는 Java 25 호환성을 보장할 수 없습니다. 프로젝트에서 사용하는 플러그인만 업데이트합니다.

  • bnd-maven-plugin의 최소 버전:
    최신 JVM 실행 시간을 지원하려면 bnd-maven-plugin의 사용을 버전 6.4.0으로 업데이트하십시오.

    버전 7 이상은 Java 11 이하와 호환되지 않으므로 해당 버전으로 업그레이드하는 것은 권장되지 않습니다.

  • aemanalyser-maven-plugin의 최소 버전:
    aemanalyser-maven-plugin의 사용을 버전 1.6.16 이상으로 업데이트하여 최신 JVM 실행 시간을 지원합니다.

  • maven-bundle-plugin의 최소 버전:
    maven-bundle-plugin의 사용을 버전 5.1.5 이상으로 업데이트하여 최신 JVM 실행 시간을 지원합니다.

    버전 6 이상은 Java 11 이하와 호환되지 않으므로 해당 버전으로 업그레이드하는 것은 권장되지 않습니다.

  • maven-scr-plugin의 종속성 업데이트:
    maven-scr-plugin은(는) Java 버전 17 이상과 직접 호환되지 않습니다. 그러나 다음 예와 같이 플러그인 구성에서 ASM 종속성 버전을 업데이트하여 설명자 파일을 생성할 수 있습니다.

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-scr-plugin</artifactId>
        <version>1.26.4</version>
        <executions>
          <execution>
            <id>generate-scr-scrdescriptor</id>
            <goals>
              <goal>scr</goal>
            </goals>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.ow2.asm</groupId>
            <artifactId>asm-analysis</artifactId>
            <version>9.8</version>
            <scope>compile</scope>
          </dependency>
        </dependencies>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Java 25 지원 java-25-support

Adobe은 AEM Cloud Service 프로젝트를 빌드하기 위해 Java 25를 권장합니다. 빌드 JDK를 변경하지 않고 Java 25 런타임에서 기존 애플리케이션의 유효성을 검사할 수도 있습니다. 두 옵션 중 하나를 사용하려면 위의 배포 전략을 따르십시오.

런타임 업그레이드 타임라인 java-25-runtime-upgrade-timeline

Adobe은 Java 25 런타임 업그레이드 전에 테스트 및 유효성 검사를 계획하는 데 도움이 되는 다음 대상 날짜를 제공합니다. 이 타임라인에 대한 모든 변경 사항은 AEM as a Cloud Service 릴리스 노트를 통해 전달됩니다.

시간 프레임
마일스톤
2026년 10월 29일
AEM Cloud Service SDK은 Java 25 런타임을 지원합니다. Java 25 JDK는 Adobe 소프트웨어 배포 포털에서 다운로드할 수 있습니다.
2026년 11월 20일
고객은 비헤이비어의 유효성을 확인하기 위해 클라우드 환경에서 Java 25 런타임을 선택적으로 활성화하는 것이 좋습니다. 조기 채택을 통해 문제를 파악하고 해결할 수 있는 시간을 극대화할 수 있습니다.
2027년 1월 - 4월
Adobe은 샌드박스 및 하위 환경(RDE, Dev)을 점차적으로 Java 25 런타임으로 마이그레이션합니다. 고객은 동작을 검증하고 예상치 못한 문제를 보고해야 하며 스테이징 및 프로덕션 환경도 활성화하는 것이 좋습니다. 문제를 해결하는 동안 Java 21로 임시 롤백을 사용할 수 있습니다.
2027년 5월
모든 환경 런타임(스테이징 및 프로덕션 포함)은 Java 25로 마이그레이션됩니다. Java 21 런타임이 사용 중지되었습니다. AEM Cloud Service SDK은 더 이상 Java 21을 지원하지 않습니다.
Java 25 런타임 요구 사항 java-25-runtime-requirements
IMPORTANT
두 옵트인 옵션 모두 각 환경에서 AEM 릴리스 28386 이상​이(가) 필요합니다.

애플리케이션이 직접 또는 AEM Groovy Console과 같은 타사 종속성을 통해 다음 라이브러리를 번들로 제공하는 경우 옵트인하기 전에 Java 25 바이트코드 지원 버전으로 업데이트합니다.

  • ASM(org.objectweb.asm, 일반적으로 org.ow2.asm.* 아티팩트에 의해 제공됨): 9.8 이상
  • Groovy(org.apache.groovy개 아티팩트): 4.0 릴리스 라인의 4.0.27 이상.
  • Aries SPI 전송(org.apache.aries.spifly.dynamic.bundle): 1.3.8 이상.

코드가 이전 Java 릴리스를 타깃팅하는 경우에도 이전 바이트코드 처리 라이브러리가 Java 25에서 실패할 수 있습니다. 관련 ASM 객체를 동일한 버전으로 유지하고 SPI Fly와 같은 라이브러리에서 요구하는 종속성 버전을 따릅니다. 서드파티 번들을 포함한 전체 애플리케이션의 유효성을 검사합니다.

Java 25 빌드 요구 사항 java-25-build-requirements

이러한 요구 사항은 런타임 전용 옵트인이 아닌 JDK 25로 빌드할 때만 적용됩니다. 빌드 시간 요구 사항 외에 JaCoCo 0.8.14 이상 및 Java 25를 지원하는 바이트코드 처리 빌드 플러그인을 사용합니다. maven-scr-plugin을(를) 사용하는 경우 위의 예에서 해당 asm-analysis 종속성을 9.8 이상​(으)로 설정하십시오. 로컬 컴파일뿐만 아니라 전체 Cloud Manager 파이프라인의 유효성을 검사합니다.

JDK 25를 사용하여 빌드하고 대상 환경을 Java 25 런타임으로 옵트인하려면 .cloudmanager/java-version을(를) 25(으)로 설정하십시오. 런타임 요구 사항도 적용됩니다. AEM_JAVA_25_OPT_IN은(는) 필요하지 않습니다. Java 25 언어 기능 및 API를 사용하려면 컴파일러를 Java 25를 타깃팅하도록 구성합니다. Java 21 호환성을 유지하려면 maven.compiler.release을(를) 21(으)로 설정하고 Java 21과 호환되는 종속성을 사용하십시오. 이 하위 컴파일러 대상으로 인해 Java 25 런타임 옵트인이 금지되지는 않습니다.

Java 25 런타임 옵트인 java-25-runtime-opt-in

Java 25 런타임만 활성화하려면 런타임 요구 사항을 검토한 다음 아래 환경 변수를 사용하십시오. 기존 빌드 JDK 및 컴파일러 설정을 유지합니다. Java 25 빌드 요구 사항은 이 옵션에 적용되지 않습니다.

  1. Cloud Manager에서 활성화할 환경을 선택합니다.

  2. 다음 구성으로 환경 변수를 추가합니다.

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
    필드 값
    이름 AEM_JAVA_25_OPT_IN
    값 true(소문자)
    단계 적용됨 모두
    유형 보통(비밀 아님)
  3. 구성을 저장하고 환경 업데이트가 완료될 때까지 기다립니다.

  4. 업데이트된 환경에서 애플리케이션 동작의 유효성을 검사합니다. 이 런타임 전용 변경에는 응용 프로그램을 다시 빌드할 필요가 없습니다.

NOTE
이 옵션을 사용하여 활성화할 각 환경에서 변수를 설정합니다. 동일한 프로덕션 파이프라인을 사용하더라도 스테이징 및 프로덕션 환경은 개별적으로 활성화되어야 합니다. 프로덕션을 활성화하기 전에 개발 및 단계에서 유효성 검사

롤백하기 전에 배포된 응용 프로그램 및 해당 종속성이 이전 Java 버전을 지원하는지 확인하십시오. 필요한 경우 호환되는 버전을 다시 배포하십시오. 컴파일러가 Java 21을 타깃팅하는 경우에도 변수를 삭제해도 JDK 25로 빌드하여 발생하는 옵트인은 실행 취소되지 않습니다.

옵트인 기간 동안 롤백하려면 AEM_JAVA_25_OPT_IN을(를) 삭제하고 구성을 저장하십시오. 환경 업데이트가 완료되면 환경은 이전 Java 버전으로 돌아갑니다. 롤백하려는 각 환경에 대해 이 절차를 반복합니다.

환경 변수 - 표준 environment-variables

프로그램 또는 파이프라인에 대한 정보를 기반으로 빌드 프로세스를 구성합니다.

예를 들어 gulp와 같은 도구를 사용하여 빌드 시 JavaScript 축소가 발생하는 경우 다양한 환경에 대해 다른 축소 수준이 선호됩니다. 개발 빌드는 스테이징 및 프로덕션에 비해 더 가벼운 축소 수준을 사용합니다.

이를 지원하기 위해 Cloud Manager는 모든 실행 시 빌드 컨테이너에 이러한 표준 환경 변수를 추가합니다.

변수 이름
정의
CM_BUILD
항상 true로 설정
BRANCH
실행에 대해 구성된 분기
CM_PIPELINE_ID
숫자 파이프라인 식별자
CM_PIPELINE_NAME
파이프라인 이름
CM_PROGRAM_ID
숫자 프로그램 식별자
CM_PROGRAM_NAME
프로그램 이름
ARTIFACTS_VERSION
스테이지 또는 프로덕션 파이프라인의 경우 Cloud Manager에서 생성된 통합 버전
CM_AEM_PRODUCT_VERSION
릴리스 버전

환경 변수 - 파이프라인 pipeline-variables

빌드 프로세스에는 Git 저장소에 저장되지 않은 특정 구성 변수가 필요합니다. 또한 동일한 분기를 사용하는 파이프라인 실행 간에 이러한 변수를 조정해야 합니다.

자세한 내용은 파이프라인 변수 구성도 참조하십시오.

추가 시스템 패키지 설치 installing-additional-system-packages

일부 빌드가 완전히 작동하려면 추가 시스템 패키지가 필요합니다. 예를 들어 빌드는 Python 또는 Ruby 스크립트를 호출하며 적절한 언어 인터프리터가 설치되어 있어야 합니다. APT를 호출하기 위해 pom.xml에서 exec-maven-plugin을(를) 호출하여 이 설치 프로세스를 관리할 수 있습니다. 이 실행은 Cloud Manager 전용 Maven 프로필로 래핑됩니다. 이 예에서는 Python을 설치합니다.

        <profile>
            <id>install-python</id>
            <activation>
                <property>
                        <name>env.CM_BUILD</name>
                </property>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.codehaus.mojo</groupId>
                        <artifactId>exec-maven-plugin</artifactId>
                        <version>1.6.0</version>
                        <executions>
                            <execution>
                                <id>apt-get-update</id>
                                <phase>validate</phase>
                                <goals>
                                    <goal>exec</goal>
                                </goals>
                                <configuration>
                                    <executable>apt-get</executable>
                                    <arguments>
                                        <argument>update</argument>
                                    </arguments>
                                </configuration>
                            </execution>
                            <execution>
                                <id>install-python</id>
                                <phase>validate</phase>
                                <goals>
                                    <goal>exec</goal>
                                </goals>
                                <configuration>
                                    <executable>apt-get</executable>
                                    <arguments>
                                        <argument>install</argument>
                                        <argument>-y</argument>
                                        <argument>--no-install-recommends</argument>
                                        <argument>python</argument>
                                    </arguments>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

이와 동일한 기술을 사용하여 언어별 패키지를 설치할 수 있습니다. 예를 들어 RubyGems의 경우 gem 또는 Python 패키지의 경우 pip를 사용할 수 있습니다.

NOTE
이 방법으로 시스템 패키지를 설치하면 Adobe Experience Manager 실행에 사용되는 런타임 환경에 설치되지 않습니다. AEM 환경에 시스템 패키지를 설치해야 하는 경우 Adobe 담당자에게 문의하십시오.
TIP
프론트엔드 빌드 환경에 대한 자세한 내용은 프론트엔드 파이프라인으로 Sites 개발을 참조하십시오.
recommendation-more-help
experience-manager-cloud-service-help-main-toc