Estrutura de projetos do AEM

Este artigo descreve as alterações necessárias para que os projetos do Adobe Experience Manager Maven sejam compatíveis com o AEM as a Cloud Service, garantindo que eles respeitem a divisão de conteúdo mutável e imutável. Além disso, as dependências são estabelecidas para criar implantações determinísticas e não conflitantes e são agrupadas em uma estrutura implantável.

As implantações de aplicativos do AEM devem ser compostas por um único pacote do AEM. Este pacote deve, por sua vez, conter subpacotes que incluem tudo o que o aplicativo exige para funcionar, incluindo código, configuração e qualquer conteúdo de linha de base de suporte.

O AEM requer uma separação de conteúdo e código, o que significa que um único pacote de conteúdo não pode ser implantado em ambas /apps e áreas graváveis em tempo de execução (por exemplo, /content, /conf, /home ou qualquer coisa que não seja /apps) do repositório. Em vez disso, o aplicativo deve separar código e conteúdo em pacotes separados para implantação no AEM.

A estrutura do pacote descrita neste documento é compatível com ambas as implantações de desenvolvimento locais e implantações do serviço da AEM Cloud.

Áreas mutáveis versus imutáveis do repositório mutable-vs-immutable

As áreas /apps e /libs do AEM são consideradas imutáveis porque não podem ser alteradas (criar, atualizar, excluir) após o AEM ser iniciado (isto é, no tempo de execução). Qualquer tentativa de alterar uma área imutável no tempo de execução falha.

Todo o restante no repositório, /content, /conf, /var, /etc, /oak:index, /system, /tmp e assim por diante, são áreas mutáveis, o que significa que podem ser alteradas em tempo de execução.

Índices Oak oak-indexes

Os índices Oak (/oak:index) são gerenciados pelo processo de implantação do AEM as a Cloud Service. O motivo é que o Cloud Manager deve aguardar até que qualquer novo índice seja implantado e totalmente reindexado antes de alternar para a nova imagem de código.

Por isso, embora os índices Oak sejam mutáveis no tempo de execução, eles devem ser implantados como código para que possam ser instalados antes que qualquer pacote mutável seja instalado. Portanto, as configurações de /oak:index fazem parte do Pacote de Código e não do Pacote de Conteúdo conforme descrito abaixo.

Estrutura de pacotes recomendada recommended-package-structure

Este diagrama fornece uma visão geral da estrutura de projeto recomendada e dos artefatos de implantação de pacote.

A estrutura de implantação de aplicativo recomendada é a seguinte:

Pacotes de código / pacotes OSGi

Pacotes de conteúdo

Pacotes de contêineres

Pacotes de Aplicativos Adicionais extra-application-packages

Se outros Projetos do AEM - que são eles mesmos compostos de seus próprios pacotes de código e conteúdo - forem usados pela implantação do AEM, seus pacotes de contêiner deverão ser incorporados ao pacote all do projeto.

Por exemplo, um projeto do AEM que inclui aplicativos AEM de dois fornecedores pode ser semelhante a:

Tipos de encapsulamento package-types

Os pacotes devem ser marcados com o tipo de pacote declarado. Os tipos de pacote ajudam a esclarecer a finalidade e a implantação de um pacote.

Para obter mais informações, consulte Apache Jackrabbit FileVault - documentação do plug-in Package Maven, Tipos de pacote Apache Jackrabbit e o trecho de configuração FileVault Maven abaixo.

Marcação de pacotes para implantação pelo Adobe Cloud Manager marking-packages-for-deployment-by-adoube-cloud-manager

Por padrão, o Adobe Cloud Manager coleta todos os pacotes produzidos pela compilação Maven. No entanto, como o pacote do contêiner (all) é o artefato de implantação singular que contém todos os pacotes de código e conteúdo, você deve garantir que somente o pacote do contêiner (all) seja implantado. Para garantir isso, outros pacotes gerados pela compilação Maven devem ser marcados com a configuração do Plug-in FileVault Content Package Maven do <properties><cloudManagerTarget>none</cloudManageTarget></properties>.

Inicialização do repositório repo-init

A Inicialização do repositório fornece instruções, ou scripts, que definem estruturas JCR, que variam de estruturas de nó comuns, como árvores de pastas, a usuários, usuários de serviço, grupos e definição de ACL.

Os principais benefícios do Repo Init são que eles têm permissões implícitas para executar todas as ações definidas por seus scripts. E esses scripts são chamados no início do ciclo de vida da implantação, garantindo que todas as estruturas JCR necessárias existam até o código ser executado.

Embora os scripts de Inicialização de repositório estejam no projeto ui.config como scripts, eles podem e devem ser usados para definir as seguintes estruturas mutáveis:

Os scripts de Inicialização de repositório são armazenados como scripts entradas de RepositoryInitializer configurações de fábrica OSGi. Dessa forma, eles podem ser direcionados implicitamente pelo modo de execução, permitindo diferenças entre o Autor do AEM e os scripts de Inicialização de repositório do AEM Publish Services ou até mesmo entre ambientes (Desenvolvimento, Preparo e Produção).

As configurações OSGi de Inicialização de repositório são escritas com êxito no .config formato de configuração OSGi, pois oferecem suporte a várias linhas, o que é uma exceção às práticas recomendadas de uso do .cfg.json para definir configurações OSGi.

Ao definir Usuários e Grupos, somente os grupos são considerados parte do aplicativo e parte integrante de sua função. Você ainda define Usuários e grupos da organização no tempo de execução no AEM. Por exemplo, se um fluxo de trabalho personalizado atribuir trabalho a um Grupo nomeado, defina esse Grupo por meio da Inicialização de repositório no aplicativo do AEM. No entanto, se o Agrupamento é meramente organizacional, como "Wendy's Team" e "Sean's Team", esses grupos são melhor definidos e gerenciados no tempo de execução no AEM.

O vocabulário completo para scripts de inicialização de repositório está disponível na documentação de inicialização de repositório do Apache Sling.

Pacote de estrutura do repositório repository-structure-package

Os pacotes de código exigem a configuração do plug-in FileVault Maven para referenciar um <repositoryStructurePackage> que imponha a correção de dependências estruturais (para garantir que um pacote de código não seja instalado sobre outro). Você pode criar seu próprio pacote de estrutura de repositório para o projeto.

Necessário somente para pacotes de código, ou seja, qualquer pacote marcado com <packageType>application</packageType>.

Para saber como criar um pacote de estrutura de repositório para seu aplicativo, consulte Desenvolver um Pacote de Estrutura de Repositório.

Os pacotes de conteúdo (<packageType>content</packageType>) não exigem esse Pacote de estrutura de repositório.

Incorporação de subpacotes no pacote de container embeddeds

O conteúdo ou os pacotes de código são colocados em uma pasta especial de "carro lateral" e podem ser direcionados para instalação no autor do AEM, na publicação do AEM ou em ambos, usando a configuração <embeddeds> do plug-in FileVault Maven. Não use a configuração <subPackages>.

Casos de uso comuns incluem:

Para direcionar o autor do AEM, o AEM publica ou ambos, o pacote é incorporado no pacote de contêiner all em um local de pasta especial, no seguinte formato:

/apps/<app-name>-packages/(content|application|container)/install(.author|.publish)?

Analisando a estrutura desta pasta:

Por exemplo, uma implantação que contém pacotes específicos do autor e da publicação do AEM pode ser semelhante ao seguinte:

Definição de filtro do pacote de contêiner container-package-filter-definition

Devido à incorporação dos subpacotes de código e conteúdo no pacote de contêiner, os caminhos de destino incorporados devem ser adicionados ao filter.xml do projeto do contêiner. Isso garante que os pacotes incorporados sejam incluídos no pacote de contêiner quando criados.

Basta adicionar as <filter root="/apps/<my-app>-packages"/> entradas para qualquer pasta de segundo nível que contenha subpacotes para implantar.

Incorporação de pacotes de terceiros embedding-3rd-party-packages

Todos os pacotes devem estar disponíveis por meio do repositório público de artefatos Maven da Adobe ou de um repositório de artefatos Maven de terceiros referenciável e público acessível.

Se os pacotes de terceiros estiverem no repositório público de artefatos Maven da Adobe, nenhuma configuração adicional será necessária para o Adobe Cloud Manager resolver os artefatos.

Se os pacotes de terceiros estiverem em um repositório público de artefatos Maven de terceiros, esse repositório deverá ser registrado no pom.xml do projeto e incorporado de acordo com o método descrito acima.

Aplicativo/conectores de terceiros devem ser incorporados usando seu pacote all como um contêiner no pacote do contêiner do projeto (all).

A adição de dependências do Maven segue as práticas padrão do Maven. A incorporação de artefatos de terceiros (pacotes de código e conteúdo) está descrita acima.

Dependências de Pacote entre o ui.apps de ui.content Pacotes package-dependencies

Para garantir a instalação adequada dos pacotes, é recomendável que as dependências entre pacotes sejam estabelecidas.

A regra geral é que os pacotes com conteúdo mutável (ui.content) devem depender do código imutável (ui.apps) que dá suporte à renderização e ao uso do conteúdo mutável.

Uma exceção notável a essa regra geral é se o pacote de código imutável (ui.apps ou qualquer outro), somente contiver pacotes OSGi. Em caso afirmativo, nenhum pacote do AEM deve declarar uma dependência nele. O motivo é porque pacotes de código imutáveis que only contêm pacotes OSGi não estão registrados no Gerenciador de Pacotes do AEM. Portanto, qualquer pacote do AEM que dependa dele tem uma dependência insatisfeita e não é instalado.

Os padrões comuns para dependências de pacote de conteúdo são:

Dependências do Pacote de Implantação Simples simple-deployment-package-dependencies

O caso simples define o pacote de conteúdo mutável ui.content para depender do pacote de código imutável ui.apps.

Dependências complexas do pacote de implantação complex-deploxment-package-dependencies

Implantações complexas se expandem no caso simples e definem dependências entre o conteúdo mutável correspondente e pacotes de código imutáveis. Conforme necessário, as dependências também podem ser estabelecidas entre pacotes de código imutáveis.

Desenvolvimento e implantação local local-development-and-deployment

As estruturas e a organização do projeto descritas neste artigo são totalmente compatíveis com as instâncias de desenvolvimento locais do AEM.

Trechos XML POM pom-xml-snippets

A seguir estão trechos de configuração do Maven pom.xml que podem ser adicionados aos projetos do Maven para se alinharem às recomendações acima.

Tipos de encapsulamento xml-package-types

Os pacotes de código e conteúdo, que são implantados como subpacotes, devem declarar um tipo de pacote de aplicativo ou conteúdo, dependendo do que eles contêm.

Tipos de pacote de contêiner container-package-types

O contêiner all/pom.xml projeto não declara um <packageType>.

Tipos de pacote de código (imutável) immutable-package-types

Os pacotes de código devem definir seu packageType como application.

No ui.apps/pom.xml, as diretivas de configuração de compilação <packageType>application</packageType> da declaração de plug-in filevault-package-maven-plugin declaram seu tipo de pacote.

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        <group>${project.groupId}</group>
        <name>my-app.ui.apps</name>
        <packageType>application</packageType>
        <accessControlHandling>merge</accessControlHandling>
        <properties>
          <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
      </configuration>
    </plugin>
    ...

Tipos de encapsulamento de conteúdo (mutável) mutable-package-types

Os pacotes de conteúdo devem definir packageType como content.

No ui.content/pom.xml, a diretiva de configuração de compilação <packageType>content</packageType> da declaração de plug-in filevault-package-maven-plugin declara seu tipo de pacote.

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        <group>${project.groupId}</group>
        <name>my-app.ui.content</name>
        <packageType>content</packageType>
        <accessControlHandling>merge</accessControlHandling>
        <properties>
          <cloudManagerTarget>none</cloudManagerTarget>
        </properties>
      </configuration>
    </plugin>
    ...

Marcação de pacotes para implantação do Adobe Cloud Manager cloud-manager-target

Em todos os projetos que geram um pacote, exceto do projeto do contêiner (all), adicione <cloudManagerTarget>none</cloudManagerTarget> à configuração <properties> da declaração do plug-in filevault-package-maven-plugin para garantir que eles não sejam implantados pelo Adobe Cloud Manager. O pacote do contêiner (all) deve ser o único pacote implantado via Cloud Manager, que, por sua vez, incorpora todos os pacotes de código e conteúdo necessários.

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

Inicialização do repositório snippet-repo-init

Os scripts de Inicialização de repositório que contêm os scripts de Inicialização de repositório são definidos na configuração de fábrica OSGi RepositoryInitializer por meio da propriedade scripts. Como esses scripts são definidos nas configurações de OSGi, eles podem ser facilmente definidos pelo modo de execução usando a semântica de pasta ../config.<runmode> usual.

Como os scripts geralmente são declarações de várias linhas, é mais fácil defini-los no arquivo .config do que no formato .cfg.json baseado em JSON.

/apps/my-app/config.author/org.apache.sling.jcr.repoinit.RepositoryInitializer-author.config

scripts=["
    create service user my-data-reader-service

    set ACL on /var/my-data
        allow jcr:read for my-data-reader-service
    end

    create path (sling:Folder) /conf/my-app/settings
"]

A propriedade OSGi scripts contém diretivas conforme definidas pela linguagem de inicialização de repositório do Apache Sling.

Pacote de estrutura do repositório xml-repository-structure-package

No ui.apps/pom.xml e em qualquer outro pom.xml que declare um pacote de código (<packageType>application</packageType>), adicione a seguinte configuração de pacote de estrutura de repositório ao plug-in FileVault Maven. Você pode criar seu próprio pacote de estrutura de repositório para o projeto.

...
<build>
  <plugins>
    <plugin>
      <groupId>org.apache.jackrabbit</groupId>
      <artifactId>filevault-package-maven-plugin</artifactId>
      <extensions>true</extensions>
      <configuration>
        ...
        <repositoryStructurePackages>
          <repositoryStructurePackage>
              <groupId>${project.groupId}</groupId>
              <artifactId>ui.apps.structure</artifactId>
              <version>${project.version}</version>
          </repositoryStructurePackage>
        </repositoryStructurePackages>
      </configuration>
    </plugin>
    ...

Incorporação de subpacotes no pacote de container xml-embeddeds

Em all/pom.xml, adicione as seguintes diretivas <embeddeds> à declaração de plug-in filevault-package-maven-plugin. Lembre-se, não use a configuração <subPackages>. O motivo é porque inclui os subpacotes em /etc/packages em vez de /apps/my-app-packages/<application|content|container>/install(.author|.publish)?.

...
<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
      ...
      <embeddeds>

          <!-- Include the application's ui.apps and ui.content packages -->
          <!-- Ensure the artifactIds are correct -->

          <!-- OSGi Bundle Jar file that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.core</artifactId>
              <type>jar</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

          <!-- Code package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.apps</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

           <!-- OSGi configuration code package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.config</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install</target>
          </embedded>

          <!-- Code package that deploys ONLY to AEM Author -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.apps.author</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/application/install.author</target>
          </embedded>

          <!-- Content package that deploys to BOTH AEM Author and AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.content</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/content/install</target>
          </embedded>

          <!-- Content package that deploys ONLY to AEM Publish -->
          <embedded>
              <groupId>${project.groupId}</groupId>
              <artifactId>my-app.ui.content.publish-only</artifactId>
              <type>zip</type>
              <target>/apps/my-app-packages/content/install.publish</target>
          </embedded>

          <!-- Include any other extra packages  -->
          <embedded>
              <groupId>com.vendor.x</groupId>
              <artifactId>vendor.plug-in.all</artifactId>
              <type>zip</type>
              <target>/apps/vendor-packages/container/install</target>
          </embedded>
      <embeddeds>
  </configuration>
</plugin>
...

Definição de filtro do pacote de contêiner xml-container-package-filters

No all (filter.xml) do projeto all/src/main/content/jcr_root/META-INF/vault/definition/filter.xml, inclua qualquer pasta -packages que contenha subpacotes a serem implantados:

<filter root="/apps/my-app-packages"/>

Se vários /apps/*-packages forem usados nos destinos inseridos, todos eles deverão ser enumerados aqui.

Repositórios Maven de terceiros xml-3rd-party-maven-repositories

No pom.xml do projeto do reator, adicione quaisquer diretivas de repositório Maven públicas de terceiros necessárias. A configuração <repository> completa deve estar disponível no Provedor do Repositório de terceiros.

<repositories>
  ...
  <repository>
      <id>3rd-party-repository</id>
      <name>Public Third-Party Repository</name>
      <url>https://repo.3rdparty.example.com/...</url>
      <releases>
          <enabled>true</enabled>
          <updatePolicy>never</updatePolicy>
      </releases>
      <snapshots>
          <enabled>false</enabled>
      </snapshots>
  </repository>
  ...
</repositories>

Dependências de Pacote entre o ui.apps de ui.content Pacotes xml-package-dependencies

Em ui.content/pom.xml, adicione as seguintes diretivas <dependencies> à declaração de plug-in filevault-package-maven-plugin.

...
<plugin>
  <groupId>org.apache.jackrabbit</groupId>
  <artifactId>filevault-package-maven-plugin</artifactId>
  <extensions>true</extensions>
  <configuration>
      ...
      <dependencies>
        <!-- Declare the content package dependency in the ui.content/pom.xml on the ui.apps project -->
        <dependency>
            <groupId${project.groupId}</groupId>
            <artifactId>my-app.ui.apps</artifactId>
            <version>${project.version}</version>
        </dependency>
      </dependencies>
    ...
  </configuration>
</plugin>
...

Limpando a pasta de destino do projeto do contêiner xml-clean-container-package

No all/pom.xml, adicione o plug-in maven-clean-plugin, que limpa o diretório de destino antes de uma compilação Maven.

<plugins>
  ...
  <plugin>
    <artifactId>maven-clean-plugin</artifactId>
    <executions>
      <execution>
        <id>auto-clean</id>
        <!-- Run at the beginning of the build rather than the default, which is after the build is done -->
        <phase>initialize</phase>
        <goals>
          <goal>clean</goal>
        </goals>
      </execution>
    </executions>
  </plugin>
  ...
</plugins>

Recursos adicionais additional-resources