Configuração do projeto

Saiba como configurar seu projeto para gerenciá-lo e implantá-lo com o Cloud Manager.

Modificação de projetos existentes

Os projetos AEM existentes precisam seguir algumas regras básicas para serem montados e implantados com sucesso com o Cloud Manager.

  • Os projetos devem ser criados usando o Apache Maven.
  • Deve haver um arquivo pom.xml na raiz do repositório Git.
    • Esse arquivo pom.xml pode se referir a quantos submódulos (que, por sua vez, podem ter outros módulos derivados) forem necessários.
    • Você pode adicionar referências a repositórios de artefatos Maven adicionais em seu arquivos pom.xml.
    • O acesso a repositórios de artefatos protegidos por senha é permitido quando configurado. No entanto, o acesso a repositórios de artefatos protegidos pela rede não é permitido.
  • Pacotes de conteúdo implantáveis são descobertos pela varredura de arquivos de pacote de conteúdo (.zip) contidos em um diretório chamado target.
    • Qualquer número de submódulos pode produzir pacotes de conteúdo.
  • Os artefatos do Dispatcher que podem ser implantados são descobertos ao verificar arquivos zip que continham subdiretórios de target nomeados como conf e conf.d.
  • Se houver mais de um pacote de conteúdo, a ordem de implantação dos pacotes não será garantida.
  • Se uma ordem específica for necessária, as dependências do pacote de conteúdo poderão ser usadas para definir a ordem.
  • Os pacotes podem ser ignorados na implantação.

Ativar perfis Maven no Cloud Manager

Em alguns casos limitados, pode ser necessário variar um pouco o processo de criação ao executar no Cloud Manager, comparado à quando ele é executado em estações de trabalho de desenvolvedor. Para estes casos, perfis Maven podem ser usados para definir como o processo de criação deve ser diferente em ambientes distintos, incluindo o Cloud Manager.

A ativação de um perfil Maven no ambiente de criação do Cloud Manager deve ser feita procurando pela variável de ambiente CM_BUILD. Por outro lado, um perfil destinado a ser usado somente fora do ambiente de criação do Cloud Manager deve ser ativado procurando a ausência dessa variável.

Por exemplo, se você quiser gerar uma mensagem simples apenas quando a build for executada no Cloud Manager, faça o seguinte:

        <profile>
            <id>cmBuild</id>
            <activation>
                  <property>
                        <name>env.CM_BUILD</name>
                  </property>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-antrun-plugin</artifactId>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>initialize</phase>
                                <configuration>
                                    <target>
                                        <echo>I'm running inside Cloud Manager!</echo>
                                    </target>
                                </configuration>
                                <goals>
                                    <goal>run</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
OBSERVAÇÃO

Para testar esse perfil em uma estação de trabalho de desenvolvedor, você pode habilitá-lo na linha de comando (com -PcmBuild) ou em um ambiente de desenvolvimento integrado (IDE).

E se você quiser gerar uma mensagem simples somente quando a build for executada fora do Cloud Manager, faça o seguinte:

        <profile>
            <id>notCMBuild</id>
            <activation>
                  <property>
                        <name>!env.CM_BUILD</name>
                  </property>
            </activation>
            <build>
                <plugins>
                    <plugin>
                        <artifactId>maven-antrun-plugin</artifactId>
                        <version>1.8</version>
                        <executions>
                            <execution>
                                <phase>initialize</phase>
                                <configuration>
                                    <target>
                                        <echo>I'm running outside Cloud Manager!</echo>
                                    </target>
                                </configuration>
                                <goals>
                                    <goal>run</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

Suporte ao repositório Maven protegido por senha

Os artefatos de um repositório Maven protegido por senha devem ser usados com muito cuidado, pois o código implantado por meio desse mecanismo não é executado por todas as regras de qualidade implementadas nas portas de qualidade do Cloud Manager. É recomendável também implantar as fontes Java, bem como todo o código-fonte do projeto junto com o binário.

DICA

Artefatos de repositórios Maven protegidos por senha devem ser usados somente em casos raros e para códigos não vinculados ao AEM.

Para usar um repositório Maven protegido por senha do Cloud Manager, especifique a senha (e, opcionalmente, o nome de usuário) como uma variável de pipeline secreta e depois faça referência a esse segredo dentro de um arquivo chamado .cloudmanager/maven/settings.xml no repositório Git. Esse arquivo segue o esquema do Arquivo de configurações Maven.

Quando o processo de criação do Cloud Manager é iniciado, o elemento <servers> neste arquivo é mesclado ao arquivo padrão settings.xml fornecido pelo Cloud Manager. IDs de servidor que começam com adobe e cloud-manager são consideradas reservadas e não devem ser usadas por servidores personalizados. IDs de servidor que não correspondem a um desses prefixos ou a ID padrão central nunca serão espelhados pelo Cloud Manager.

Com esse arquivo definido, a ID do servidor seria referenciada de dentro de um elemento <repository> e/ou <pluginRepository>, que está dentro do arquivo pom.xml. Geralmente, estes elementos <repository> e/ou <pluginRepository> ficariam contidos dentro de um perfil específico do Cloud Manager, embora isso não seja estritamente necessário.

Como exemplo, digamos que o repositório esteja em https://repository.myco.com/maven2, o nome de usuário que o Cloud Manager deve usar é cloudmanager e a senha é secretword.

Primeiro, defina a senha como um segredo no pipeline:

$ aio cloudmanager:set-pipeline-variables PIPELINEID --secret CUSTOM_MYCO_REPOSITORY_PASSWORD secretword

Em seguida, faça referência a isso no arquivo .cloudmanager/maven/settings.xml:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>myco-repository</id>
            <username>cloudmanager</username>
            <password>${env.CUSTOM_MYCO_REPOSITORY_PASSWORD}</password>
        </server>
    </servers>
</settings>

E, por fim, referencie a ID do servidor dentro do arquivo pom.xml:

<profiles>
    <profile>
        <id>cmBuild</id>
        <activation>
                <property>
                    <name>env.CM_BUILD</name>
                </property>
        </activation>
        <build>
            <repositories>
                <repository>
                    <id>myco-repository</id>
                    <name>MyCo Releases</name>
                    <url>https://repository.myco.com/maven2</url>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>myco-repository</id>
                    <name>MyCo Releases</name>
                    <url>https://repository.myco.com/maven2</url>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                </pluginRepository>
            </pluginRepositories>
        </build>
    </profile>
</profiles>

Implantação de fontes

É uma boa prática implantar as fontes Java junto com o binário em um repositório Maven.

Configure o maven-source-plugin no seu projeto:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-source-plugin</artifactId>
            <executions>
                <execution>
                    <id>attach-sources</id>
                    <goals>
                        <goal>jar-no-fork</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

Implantações de fontes de projeto

É uma boa prática implantar toda a origem do projeto junto com o binário em um repositório Maven. Dessa forma, é possível reconstruir o artefato exato.

Configure o maven-assembly-plugin no seu projeto:

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-assembly-plugin</artifactId>
            <executions>
                <execution>
                    <id>project-assembly</id>
                    <phase>package</phase>
                    <goals>
                        <goal>single</goal>
                    </goals>
                    <configuration>
                        <descriptorRefs>
                            <descriptorRef>project</descriptorRef>
                        </descriptorRefs>
                    </configuration>
                </execution>
            </executions>
        </plugin>

Ignorar pacotes de conteúdo

No Cloud Manager, as builds podem produzir qualquer número de pacotes de conteúdo. Por uma variedade de motivos, pode ser desejável produzir um pacote de conteúdo, mas não implantá-lo. Isso pode ser útil, por exemplo, ao criar pacotes de conteúdo usados apenas para teste ou que serão “reembalados” por outra etapa no processo de criação, ou seja, como um subpacote de outro pacote.

Para acomodar esses cenários, o Cloud Manager procurará uma propriedade chamada cloudManagerTarget nas propriedades dos pacotes de conteúdo incorporados. Se essa propriedade estiver definida como none, o pacote será ignorado e não será implantado. O mecanismo para definir essa propriedade depende da forma como a compilação está produzindo o pacote de conteúdo. Por exemplo, com o filevault-maven-plugin, você configuraria o plug-in da seguinte maneira:

        <plugin>
            <groupId>org.apache.jackrabbit</groupId>
            <artifactId>filevault-package-maven-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <properties>
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
        <!-- other configuration -->
            </configuration>
        </plugin>

Com o content-package-maven-plugin, o processo é semelhante:

        <plugin>
            <groupId>com.day.jcr.vault</groupId>
            <artifactId>content-package-maven-plugin</artifactId>
            <extensions>true</extensions>
            <configuration>
                <properties>
                    <cloudManagerTarget>none</cloudManagerTarget>
                </properties>
        <!-- other configuration -->
            </configuration>
        </plugin>

Reutilização de artefato de build

Em muitos casos, o mesmo código é implantado em vários ambientes do AEM. Quando possível, o Cloud Manager evitará reconstruir a base de código quando detectar que a mesma confirmação do Git é usada em várias execuções de pipeline de pilha completa.

Quando uma execução é iniciada, a confirmação HEAD atual do pipeline da ramificação é extraída. O hash de confirmação é visível na interface e por meio da API. Quando a etapa de criação é concluída com sucesso, os artefatos resultantes são armazenados com base nesse hash de confirmação e podem ser reutilizados em execuções de pipeline subsequentes.

Os pacotes são reutilizados em pipelines se estiverem no mesmo programa. Ao procurar pacotes que possam ser reutilizados, o AEM ignora ramificações e reutiliza artefatos entre ramificações.

Quando ocorre uma reutilização, as etapas de criação e qualidade do código são efetivamente substituídas pelos resultados da execução original. O arquivo de log da etapa de criação listará os artefatos e as informações de execução que foram usadas originalmente para criá-los.

Veja a seguir um exemplo desse resultado de log.

The following build artifacts were reused from the prior execution 4 of pipeline 1 which used commit f6ac5e6943ba8bce8804086241ba28bd94909aef:
build/aem-guides-wknd.all-2021.1216.1101633.0000884042.zip (content-package)
build/aem-guides-wknd.dispatcher.cloud-2021.1216.1101633.0000884042.zip (dispatcher-configuration)

O log da etapa de qualidade do código conterá informações semelhantes.

Exemplos

Exemplo 1

Considere que seu programa tem dois pipelines de desenvolvimento:

  • Pipeline 1 na ramificação foo
  • Pipeline 2 na ramificação bar

Ambas as ramificações estão na mesma ID de confirmação.

  1. A execução do pipeline 1 por primeiro criará os pacotes normalmente.
  2. Em seguida, a execução do pipeline 2 reutilizará os pacotes criados pelo pipeline 1.

Exemplo 2

Considere que seu programa tem duas ramificações:

  • Ramificação foo
  • Ramificação bar

Ambas as ramificações têm a mesma ID de confirmação.

  1. Um pipeline de desenvolvimento cria e executa foo.
  2. Posteriormente, um pipeline de produção cria e executa bar.

Nesse caso, o artefato de foo será reutilizado para o pipeline de produção desde que o mesmo hash de confirmação seja identificado.

Opção de desativação

Se desejar, o comportamento de reutilização pode ser desativado para pipelines específicos definindo a variável de pipeline CM_DISABLE_BUILD_REUSE como true. Se essa variável for definida, o hash de confirmação ainda será extraído e os artefatos resultantes serão armazenados para uso posterior, mas os artefatos armazenados anteriormente não serão reutilizados. Para entender esse comportamento, considere o seguinte cenário.

  1. Um novo pipeline é criado.
  2. O pipeline é executado (execução nº 1) e a confirmação HEAD atual é becdddb. A execução é bem-sucedida e os artefatos resultantes são armazenados.
  3. A variável CM_DISABLE_BUILD_REUSE é definida.
  4. O pipeline é executado novamente sem alterar o código. Embora haja artefatos armazenados associados a becdddb, eles não serão reutilizados devido à variável CM_DISABLE_BUILD_REUSE.
  5. O código é alterado e o pipeline é executado. A confirmação HEAD agora é f6ac5e6. A execução é bem-sucedida e os artefatos resultantes são armazenados.
  6. A variável CM_DISABLE_BUILD_REUSE é excluída.
  7. O pipeline é executado novamente sem alterar o código. Como há artefatos armazenados associados a f6ac5e6, esses artefatos são reutilizados.

Avisos

  • Os artefatos da build não são reutilizados em diferentes programas, independentemente de o hash de confirmação ser idêntico.
  • Os artefatos de build são reutilizados no mesmo programa mesmo se a ramificação e/ou o pipeline for diferente.
  • O manuseio de versão do Maven substitui a versão do projeto somente em pipelines de produção. Portanto, se a mesma confirmação for usada em uma execução de implantação de desenvolvimento e em uma execução de pipeline de produção e o pipeline de implantação de desenvolvimento for executado primeiro, as versões serão implantadas no estágio e na produção sem serem alteradas. No entanto, uma tag ainda será criada nesse caso.
  • Se a recuperação dos artefatos armazenados não for bem-sucedida, a etapa de criação será executada como se nenhum artefato tivesse sido armazenado.
  • Variáveis de pipeline diferentes de CM_DISABLE_BUILD_REUSE não são consideradas quando o Cloud Manager decide reutilizar artefatos de build criados anteriormente.

Desenvolver seu código com base nas práticas recomendadas

As equipes de engenharia e consultoria da Adobe desenvolveram um conjunto abrangente de práticas recomendadas para desenvolvedores do AEM.

Nesta página