Ambiente di build di Cloud Manager build-environment

Scopri l’ambiente di build di Cloud Manager e come genera e verifica il codice.

TIP
Questo documento descrive l’ambiente di build di Cloud Manager per lo sviluppo del progetto AEM as a Cloud Service. Per informazioni dettagliate sulle piattaforme client supportate da AEM as a Cloud Service per l'authoring dei contenuti, vedere Piattaforme client supportate.

Dettagli dell’ambiente di build build-environment-details

Cloud Manager genera e verifica il codice mediante un ambiente di build specializzato.

  • L’ambiente di build è basato su Linux, derivato da Ubuntu 22.04.

  • Apache Maven 3.9.4 è installato.

  • Le versioni Java installate sono Oracle JDK 11.0.22, Oracle JDK 17.0.10, Oracle JDK 21.0.4 e Oracle JDK 25.0.2.

  • IMPORTANTE: Per impostazione predefinita, la variabile di ambiente JAVA_HOME è impostata su /usr/lib/jvm/jdk1.8.0_401, che contiene Oracle JDK 8u401. Ignora questa impostazione predefinita per i progetti AEM Cloud Service impostando la versione JDK di Maven.

  • Sono installati alcuni pacchetti di sistema aggiuntivi necessari.

    • bzip2
    • unzip
    • libpng
    • imagemagick
    • graphicsmagick
  • Altri pacchetti vengono installati in fase di compilazione come descritto nella sezione Installazione di pacchetti di sistema aggiuntivi.

  • Ogni build viene eseguita in un nuovo ambiente; il contenitore di build non mantiene i dati tra le esecuzioni.

  • Maven viene sempre eseguito con i tre comandi riportati di seguito.

    • 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 è configurato a livello di sistema con un file settings.xml, che include automaticamente l’archivio di artefatti pubblico di Adobe utilizzando un profilo denominato adobe-public. Per ulteriori informazioni, consulta Archivio Maven pubblico di Adobe.

NOTE
Cloud Manager non specifica una versione di jacoco-maven-plugin. Configura una versione che supporti il JDK della build e il codice compilato. Consulta Requisiti di compilazione.

Archivi Maven HTTPS https-maven

Utilizza gli URL HTTPS per gli archivi e i mirror Maven. Maven blocca gli archivi HTTP esterni per impostazione predefinita, causando il mancato download di plugin o dipendenze. Se la build fa riferimento a un archivio HTTP, aggiorna il repository o la configurazione mirror per utilizzare il relativo endpoint HTTPS.

Utilizza una versione Java specifica using-java-support

Il processo di build di Cloud Manager utilizza il JDK di Oracle 8 per generare i progetti per impostazione predefinita, ma i clienti di AEM Cloud Service devono impostare la versione JDK di esecuzione Maven su 25, 21, 17 o 11.

Il JDK della build esegue Maven; la destinazione del compilatore determina la versione Java di destinazione dal codice; il runtime di AEM esegue l’applicazione implementata. Si tratta di impostazioni distinte. Le sezioni seguenti descrivono i prerequisiti per la configurazione della build e l’aggiornamento. Per i requisiti specifici di Java 25 e le opzioni di consenso, vedere Supporto Java 25.

Impostare la versione JDK di Maven alternate-maven-jdk-version

Per impostare il JDK di esecuzione Maven, crea un file denominato .cloudmanager/java-version nel ramo dell’archivio Git utilizzato dalla pipeline. Il file deve contenere solo il numero di versione principale: 25, 21, 17 o 11. Cloud Manager utilizza il JDK di Oracle corrispondente. Anche se Cloud Manager accetta 8, questa versione non è più supportata per i progetti AEM Cloud Service. Gli altri valori vengono ignorati.

Il file seleziona il JDK che esegue Maven, non la destinazione del compilatore. Il runtime predefinito di AEM è attualmente Java 21. La generazione con JDK 25 consente inoltre di scegliere l’ambiente di destinazione nel runtime Java 25, indipendentemente dalla destinazione del compilatore. Rivedi Supporto Java 25 prima di selezionare 25.

Prerequisiti per la migrazione a una versione Java più recente prereq-for-building

Per la generazione con Java 21 o Java 17, Cloud Manager ora utilizza SonarQube 9.9, compatibile con queste versioni Java. Questa modifica è stata introdotta nella versione 2025.1.0 di Cloud Manager. Per aggiornare SonarQube non è necessaria alcuna azione da parte del cliente. Per ulteriori dettagli e per comprendere la modifica, consulta le Note sulla versione di Cloud Manager 2025.1.0.

Per una modifica JDK della build, controlla i requisiti di tempo della build per la versione di destinazione. Per una modifica solo in fase di runtime, controlla i requisiti per il runtime di destinazione; non è necessario modificare il JDK della build. Durante la migrazione dell’applicazione a una nuova versione di build Java o di runtime, esegui un test completo negli ambienti di sviluppo e staging prima di implementarla nell’ambiente di produzione.

Adobe consiglia la seguente strategia di implementazione:

  1. Scarica una versione di AEM Cloud Service SDK che supporta il runtime Java previsto. Esegui SDK con tale runtime, distribuisci l’applicazione e convalidane la funzionalità. Controllare i registri per verificare la presenza di errori di caricamento di classi o di creazione di bytecode.
  2. Per una modifica JDK della build, configura il JDK Maven in un ramo nell’archivio Cloud Manager, configura una pipeline DEV per utilizzare questo ramo ed esegui la pipeline. Per una modifica solo in fase di runtime, applica la configurazione di runtime e attendi l’aggiornamento dell’ambiente; non è necessario ricompilare l’applicazione. Eseguire i test di convalida.
  3. Se lo sviluppo dei risultati è soddisfacente, applicare la stessa modifica allo stadio e convalidarla prima di procedere alla produzione.

Requisiti di runtime runtime-requirements

I seguenti requisiti si applicano al runtime Java 21. Per Java 25, utilizzare i requisiti runtime Java 25 separati.

  • Versione minima di ASM:
    Aggiornare l’utilizzo del pacchetto Java org.objectweb.asm, spesso incluso in org.ow2.asm.* artefatti, alla versione 9.8 o successiva per garantire il supporto per i runtime JVM più recenti.

  • Versione minima di Groovy:
    Aggiornare l’utilizzo dei pacchetti Java org.apache.groovy o org.codehaus.groovy alla versione 4.0.22 o successiva per garantire il supporto dei runtime JVM più recenti.

    Questo bundle può essere incluso indirettamente aggiungendo dipendenze di terze parti come Groovy Console di AEM.

  • Versione minima di Aries SPIFly:
    Aggiornare l’utilizzo del pacchetto Java org.apache.aries.spifly.dynamic.bundle alla versione 1.3.6 o successiva per garantire il supporto per i runtime JVM più recenti.

Requisiti di tempo di creazione build-time-reqs

Per consentire la creazione del progetto con Java 21 e Java 17 sono necessari i seguenti adeguamenti. Possono essere aggiornati anche prima di eseguire Java 21 e Java 17 perché sono compatibili con le versioni Java precedenti.

Per le build Java 25, segui anche i requisiti di build Java 25. Le versioni minime riportate di seguito non garantiscono di per sé la compatibilità con Java 25. Aggiorna solo i plug-in utilizzati dal progetto.

  • Versione minima di bnd-maven-plugin:
    Aggiornare l’utilizzo di bnd-maven-plugin alla versione 6.4.0 per garantire il supporto dei runtime JVM più recenti.

    Le versioni 7 o successive non sono compatibili con Java 11 o versioni precedenti, pertanto non è consigliabile effettuare un aggiornamento a tale versione.

  • Versione minima di aemanalyser-maven-plugin:
    Aggiornare l’utilizzo di aemanalyser-maven-plugin alla versione 1.6.16 o successiva per garantire il supporto dei runtime JVM più recenti.

  • Versione minima di maven-bundle-plugin:
    Aggiornare l’utilizzo di maven-bundle-plugin alla versione 5.1.5 o successiva per garantire il supporto dei runtime JVM più recenti.

    Le versioni 6 o successive non sono compatibili con Java 11 o versioni precedenti, pertanto non è consigliabile effettuare un aggiornamento a tale versione.

  • Aggiorna dipendenze in maven-scr-plugin:
    maven-scr-plugin non è direttamente compatibile con Java versione 17 o successiva. Tuttavia, i file descrittori possono essere generati aggiornando la versione della dipendenza ASM nella configurazione del plug-in, come illustrato nell’esempio seguente:

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

Supporto Java 25 java-25-support

Adobe consiglia Java 25 per la creazione di progetti AEM Cloud Service. Puoi anche convalidare un’applicazione esistente nel runtime Java 25 senza modificarne la build JDK. Segui la strategia di distribuzione descritta sopra per entrambe le opzioni.

Timeline di aggiornamento runtime java-25-runtime-upgrade-timeline

Adobe fornisce le seguenti date di destinazione per aiutarti a pianificare i test e la convalida prima dell’aggiornamento runtime di Java 25. Eventuali modifiche a questa timeline verranno comunicate tramite le note sulla versione di AEM as a Cloud Service.

Arco temporale
Milestone
29 ottobre 2026
AEM Cloud Service SDK supporta il runtime Java 25. Java 25 JDK è disponibile per il download dal portale di distribuzione software Adobe.
20 novembre 2026
Se lo desideri, i clienti sono invitati ad abilitare il runtime Java 25 nei loro ambienti Cloud per convalidare il comportamento. L’adozione anticipata ottimizza il tempo necessario per emergere e risolvere i problemi.
Gennaio - Aprile 2027
Adobe eseguirà gradualmente la migrazione delle sandbox e degli ambienti inferiori (RDE, Dev) al runtime Java 25. I clienti devono convalidare il comportamento e segnalare problemi imprevisti e sono invitati ad abilitare anche gli ambienti di staging e produzione. È disponibile un rollback temporaneo a Java 21 per la risoluzione di eventuali problemi.
Maggio 2027
Tutti i runtime dell’ambiente (inclusi staging e produzione) eseguono la migrazione a Java 25. Il runtime Java 21 è disattivato. AEM Cloud Service SDK non supporterà più Java 21.
Requisiti di runtime Java 25 java-25-runtime-requirements
IMPORTANT
Entrambe le opzioni di consenso richiedono AEM versione 28386 o successiva in ogni ambiente.

Se l’applicazione raggruppa le seguenti librerie, direttamente o tramite dipendenze di terze parti come AEM Groovy Console, aggiornale alle versioni con supporto per codici a 25 byte Java prima di dare il consenso:

Le librerie di elaborazione dei bytecode meno recenti possono avere esito negativo in Java 25 anche se il codice è destinato a una versione precedente di Java. Mantenere gli artefatti ASM correlati nella stessa versione e rispettare le versioni delle dipendenze richieste dalle librerie, ad esempio SPI Fly. Convalida l’applicazione completa, inclusi i bundle di terze parti.

Requisiti della build Java 25 java-25-build-requirements

Questi requisiti si applicano solo quando si crea con JDK 25, non a un consenso solo runtime. Oltre ai requisiti di tempo di compilazione, utilizza JaCoCo 0.8.14 o versioni successive e i plug-in di compilazione per l’elaborazione del bytecode che supportano Java 25. Se utilizzi maven-scr-plugin, imposta la relativa dipendenza asm-analysis su 9.8 o versione successiva nell’esempio precedente. Convalida l’intera pipeline di Cloud Manager, non solo la compilazione locale.

Imposta .cloudmanager/java-version su 25 per la build con JDK 25 e scegli l’ambiente di destinazione nel runtime Java 25. Si applicano anche i requisiti runtime; AEM_JAVA_25_OPT_IN non è necessario. Per utilizzare le funzioni e le API del linguaggio Java 25, configurare il compilatore in modo che esegua il targeting di Java 25. Per mantenere la compatibilità con Java 21, impostare maven.compiler.release su 21 e utilizzare dipendenze compatibili con Java 21. Questa destinazione del compilatore inferiore non impedisce il consenso del runtime Java 25.

Consenso runtime Java 25 java-25-runtime-opt-in

Per abilitare solo il runtime Java 25, controlla i requisiti di runtime, quindi utilizza la variabile di ambiente seguente. Mantenere le impostazioni JDK della build esistente e del compilatore; i requisiti di build Java 25 non si applicano a questa opzione.

  1. In Cloud Manager, seleziona l’ambiente da abilitare.

  2. Aggiungi una variabile di ambiente con la seguente configurazione:

    table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
    Campo Valore
    Nome AEM_JAVA_25_OPT_IN
    Valore true (minuscolo)
    Passaggio applicato Tutti
    Tipo Normale (non segreto)
  3. Salva la configurazione e attendi il completamento dell’aggiornamento dell’ambiente.

  4. Convalida il comportamento dell’applicazione nell’ambiente aggiornato. Per questa modifica di sola esecuzione non è necessario ricompilare l’applicazione.

NOTE
Con questa opzione, imposta la variabile in ogni ambiente che desideri abilitare. Gli ambienti di staging e produzione devono essere attivati separatamente, anche se utilizzano la stessa pipeline di produzione. Convalida in fase di sviluppo e staging prima di abilitare la produzione.

Prima di eseguire il rollback, accertati che l’applicazione distribuita e le relative dipendenze supportino la versione Java precedente; se necessario, ridistribuisci una versione compatibile. L’eliminazione della variabile non annulla un consenso causato dalla generazione con JDK 25, anche se il compilatore esegue il targeting di Java 21.

Per eseguire il rollback durante il periodo di consenso, elimina AEM_JAVA_25_OPT_IN e salva la configurazione. Al termine dell’aggiornamento dell’ambiente, viene ripristinata la versione Java precedente. Ripetere questa procedura per ogni ambiente che si desidera ripristinare.

Variabili di ambiente - standard environment-variables

Configura il processo di build in base alle informazioni sul programma o sulla pipeline.

Ad esempio, se la minimizzazione di JavaScript si verifica in fase di build utilizzando uno strumento come gulp, per vari ambienti sono preferiti livelli di minimizzazione diversi. Una build di sviluppo utilizza un livello di minimizzazione più leggero rispetto alla staging e alla produzione.

Per supportare la funzione, Cloud Manager aggiunge le variabili di ambiente standard al contenitore della build per ogni esecuzione.

Nome della variabile
Definizione
CM_BUILD
Sempre impostato su true
BRANCH
Ramo configurato per l’esecuzione
CM_PIPELINE_ID
Identificatore numerico della pipeline
CM_PIPELINE_NAME
Nome della pipeline
CM_PROGRAM_ID
Identificatore numerico del programma
CM_PROGRAM_NAME
Nome del programma
ARTIFACTS_VERSION
Per una pipeline di staging o di produzione, la versione sintetica generata da Cloud Manager
CM_AEM_PRODUCT_VERSION
Versione

Variabili di ambiente - pipeline pipeline-variables

Il processo di build richiede variabili di configurazione specifiche che non sono memorizzate nell’archivio Git. Inoltre, è necessario regolare queste variabili tra le esecuzioni della pipeline che utilizzano lo stesso ramo.

Per ulteriori informazioni, vedi anche Configurare le variabili di pipeline.

Installare pacchetti di sistema aggiuntivi installing-additional-system-packages

Alcune build richiedono pacchetti di sistema aggiuntivi per funzionare completamente. Ad esempio, una build richiama uno script Python o Ruby e deve avere installato un interprete del linguaggio appropriato. È possibile gestire questo processo di installazione chiamando exec-maven-plugin in pom.xml per richiamare APT. Questa esecuzione è racchiusa in un profilo Maven specifico per Cloud Manager. In questo esempio viene installato 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>

Questa stessa tecnica può essere utilizzata per installare pacchetti per uno specifico linguaggio, ad esempio utilizzando gem per RubyGems o pip per i pacchetti Python.

NOTE
Installando un pacchetto di sistema in questo modo, non lo si installa nell’ambiente di runtime utilizzato per l’esecuzione di Adobe Experience Manager. Se hai bisogno di installare un pacchetto di sistema nell’ambiente AEM, contatta il rappresentante Adobe.
TIP
Per informazioni dettagliate sull’ambiente di creazione front-end, consulta il documento Sviluppo di siti con la pipeline front-end.
recommendation-more-help
experience-manager-cloud-service-help-main-toc