Structure de projet AEM

Cet article décrit les modifications requises pour que les projets Maven Adobe Experience Manager soient compatibles avec AEM as a Cloud Service, en veillant à ce qu’ils respectent la division entre contenu modifiable et non modifiable. En outre, les dépendances sont établies pour créer des déploiements déterministes non conflictuels. Elles sont regroupées dans une structure déployable.

Les déploiements d’applications AEM doivent être constitués d’un seul package AEM. Ce package doit, à son tour, contenir des sous-packages qui comprennent tout ce dont l’application a besoin pour fonctionner, y compris le code, la configuration et tout contenu de référence nécessaire.

AEM requiert une séparation du contenu et du code, ce qui signifie qu’un même package de contenu ne peut pas être déployé à la fois dans les zones /apps et dans les zones accessibles en écriture au moment de l’exécution (/content, /conf, /home ou toute zone autre que /apps) du référentiel. L’application doit séparer le code et le contenu dans des packages distincts en vue du déploiement dans AEM.

La structure de package décrite dans ce document est compatible avec les déploiements de développement en local et les déploiements d’AEM Cloud Service.

Zones modifiables et non modifiables du référentiel mutable-vs-immutable

Les zones /apps et /libs d’AEM sont considérées comme non modifiables, car elles ne peuvent pas être changées (créees, mises à jour ou supprimées) une fois AEM démarré (c’est-à-dire au moment de l’exécution). Toute tentative de modification d’une zone non modifiable au moment de l’exécution échoue.

Toutes les autres zones du référentiel (par exemple, /content, /conf, /var, /etc, /oak:index, /system, /tmp, etc.) sont toutes modifiables, ce qui signifie qu’elles peuvent être changées au moment de l’exécution.

Index Oak oak-indexes

Les index Oak (/oak:index) sont gérés spécifiquement par le processus de déploiement d’AEM as a Cloud Service. En effet, Cloud Manager doit attendre le déploiement d’un nouvel index et sa réindexation complète avant de passer à la nouvelle image de code.

Ainsi, bien que les index Oak soient modifiables au moment de l’exécution, ils doivent être déployés sous forme de code pour pouvoir être installés avant les packages modifiables. Les configurations /oak:index font donc partie du package de code, mais pas du package de contenu, comme décrit ci-dessous.

Structure de package recommandée recommended-package-structure

Ce diagramme présente un aperçu de la structure de projet recommandée et des artefacts de déploiement du package.

La structure de déploiement d’application recommandée est la suivante :

Packages de code/Bundles OSGi

Packages de contenu

Packages conteneurs

Packages d’applications supplémentaires extra-application-packages

Si d’autres projets AEM, eux-mêmes composés de leur propre packages de contenu et de code, sont utilisés par le déploiement AEM, leurs packages conteneurs doivent être incorporés dans le package all du projet.

Par exemple, un projet AEM incluant deux applications AEM de fournisseurs peut se présenter comme suit :

Types de packages package-types

Les packages doivent être marqués avec le type déclaré. Les types de packages permettent de clarifier l’objectif et le déploiement d’un package.

Pour plus d’informations, consultez la documentation d’Apache Jackrabbit FileVault - Plug-in Maven pour les packages, les Types de packages Apache Jackrabbit et le Fragment de code de configuration FileVault Maven ci-dessous.

Marquage de packages en vue du déploiement par Adobe Cloud Manager marking-packages-for-deployment-by-adoube-cloud-manager

Par défaut, Adobe Cloud Manager récupère tous les packages générés par la version Maven. Cependant, étant donné que le package de conteneur (all) est l’artefact de déploiement unique qui contient tous les packages de code et de contenu, vous devez vous assurer que seul le conteneur (all) est déployé. Pour ce faire, les autres modules générés par la version Maven doivent être marqués avec la configuration suivante du plug-in Maven FileVault Content Package : <properties><cloudManagerTarget>none</cloudManageTarget></properties>.

Repo Init repo-init

Repo Init fournit des instructions, ou scripts, qui définissent les structures JCR, allant des structures de nœud courantes comme les arborescences de dossiers, aux personnes utilisatrices, aux personnes utilisatrices de service, aux groupes et à la définition d’ACL.

Repo Init a l’avantage de disposer d’autorisations implicites pour effectuer toutes les actions définies par les scripts. De plus, ces scripts sont appelés plus tôt au cours du cycle de vie du déploiement, ce qui garantit que toutes les structures JCR requises existent au moment de l’exécution du code temporel.

Bien que les scripts Repo Init résident eux-mêmes dans le projet ui.config en tant que scripts, ils peuvent et doivent être utilisés pour définir les structures mutables suivantes :

Les scripts Repo Init sont stockés sous la forme d’entrées scripts de configurations d’usine OSGi RepositoryInitializer. Ils peuvent donc être implicitement ciblés par le mode d’exécution, ce qui permet d’établir des différences entre les scripts Repo Init des services de création et de publication AEM, voire entre les environnements (développement, évaluation et production).

Les configurations OSGi Repo Init sont mieux écrites dans le .configformat de configuration OSGi, car elles prennent en charge plusieurs lignes, ce qui est une exception aux bonnes pratiques d’utilisation de .cfg.json pour définir des configurations OSGi.

Lors de la définition des personnes utilisatrices et des groupes, seuls les groupes sont considérés comme faisant partie de l’application et comme faisant partie intégrante de sa fonction. Vous définissez toujours des personnes utilisatrices et des groupes d’organisation au moment de l’exécution dans AEM. Par exemple, si un workflow personnalisé affecte du travail à un groupe nommé, définissez ce groupe au moyen de Repo Init dans l’application AEM. Cependant, si le groupement est simplement organisationnel, comme « l’équipe de Wendy » et « l’équipe de Sean », ces groupes sont mieux définis et gérés au moment de l’exécution dans AEM.

Le vocabulaire complet des scripts Repo Init est disponible dans la documentation d’Apache Sling Repo Init.

Package de structure du référentiel repository-structure-package

Les packages de code exigent que la configuration du plug-in Maven FileVault fasse référence à un <repositoryStructurePackage>, qui s’assure que les dépendances structurelles sont correctes (pour qu’un package de code ne s’installe pas sur un autre). Vous pouvez créer votre propre package de structure de référentiel pour votre projet.

Cette exigence porte uniquement sur les packages de code, c’est-à-dire tout package marqué avec <packageType>application</packageType>.

Pour savoir comment créer un package de structure de référentiel pour votre application, voir Développement d’un package de structure de référentiel.

Notez que les packages de contenu (<packageType>content</packageType>) n’ont pas besoin de ce package de structure de référentiel.

Intégrer des sous-packages dans le package conteneur embeddeds

Les packages de contenu ou de code sont placés dans un dossier « sidecar » spécial et peuvent être ciblés en vue d’une installation sur l’instance de création ou l’instance de publication d’AEM, ou les deux, à l’aide de la configuration <embeddeds> du plug-in Maven FileVault. N’utilisez pas la configuration <subPackages>.

Scénarios d’utilisation courants :

Pour cibler l’instance de création AEM, l’instance de publication AEM ou les deux, le package est incorporé dans le package conteneur all dans un emplacement de dossier spécial, au format suivant :

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

Ventilation de cette structure de dossiers :

Par exemple, un déploiement qui contient des packages spécifiques à AEM Author et AEM Publish peut se présenter comme suit :

Définition du filtre du package conteneur container-package-filter-definition

En raison de l’incorporation des sous-packages de code et de contenu dans le package conteneur, les chemins d’accès cibles incorporés doivent être ajoutés au fichier filter.xml du projet de conteneur. Cela permet de s’assurer que les packages incorporés sont inclus dans le package conteneur lors de sa création.

Il vous suffit d’ajouter les entrées <filter root="/apps/<my-app>-packages"/> pour les dossiers de deuxième niveau contenant des sous-packages à déployer.

Incorporation de packages tiers embedding-3rd-party-packages

Tous les packages doivent être disponibles via le référentiel d’artefacts Maven public d’Adobe ou un référentiel d’artefacts Maven tiers accessible au public et pouvant être référencé.

Si les packages tiers se trouvent dans le référentiel d’artefacts Maven public d’Adobe, aucune configuration supplémentaire n’est nécessaire pour qu’Adobe Cloud Manager puisse résoudre les artefacts.

Si les packages tiers se trouvent dans un référentiel d’artefacts Maven tiers public, ce référentiel doit être enregistré dans le fichier pom.xml du projet et incorporé selon la méthode décrite ci-dessus.

Les applications/connecteurs tiers doivent être incorporés à l’aide du package all, en tant que conteneur dans le package (all) conteneur de votre projet.

L’ajout de dépendances Maven suivant les pratiques Maven standard et l’incorporation d’artefacts tiers (packages de code et contenu) sont décrits ci-dessus.

Dépendances entre les packages ui.apps et ui.content package-dependencies

Pour une installation correcte des packages, il est recommandé d’établir des dépendances entre les packages.

La règle est que les packages contenant du contenu modifiable (ui.content) doivent dépendre du code non modifiable (ui.apps) qui prend en charge le rendu et l’utilisation du contenu modifiable.

Une exception notable à cette règle générale est que le package de code non modifiable (ui.apps ou autre) contient uniquement des bundles OSGi. Si tel est le cas, aucun package AEM ne doit déclarer une dépendance à son égard. En effet, les packages de code non modifiables, qui incluent uniquement des lots OSGi, ne sont pas enregistrés avec le Gestionnaire de modules AEM. Par conséquent, tout package AEM qui en dépend a une dépendance insatisfaite et ne peut pas être installé.

Les schémas courants applicables aux dépendances des packages de contenu sont les suivants :

Dépendances de packages dans un déploiement simple simple-deployment-package-dependencies

Dans ce scénario, le package de contenu modifiable ui.content est défini de telle sorte qu’il dépende du package de code non modifiable ui.apps.

Dépendances de packages dans un déploiement complexe complex-deploxment-package-dependencies

Les déploiements complexes étendent le scénario de déploiement simple et définissent les dépendances entre les packages de contenu modifiable et non modifiable correspondants. Suivant les besoins, des dépendances peuvent également être établies entre des packages de code non modifiable.

Développement et déploiement en local local-development-and-deployment

L’organisation et les structures de projet décrites dans cet article sont entièrement compatibles avec les instances AEM de développement en local.

Fragments de code XML POM pom-xml-snippets

Vous trouverez, ci-après, des fragments de code de configuration pom.xml Maven pouvant être ajoutés aux projets Maven pour respecter les recommandations ci-dessus.

Types de packages xml-package-types

Les packages de code et de contenu, qui sont déployés sous forme de sous-packages, doivent déclarer un type d’application ou de contenu, selon ce qu’ils contiennent.

Types de packages conteneur container-package-types

Le projet all/pom.xml du conteneur ne déclare pas de <packageType>.

Types de packages de code (non modifiable) immutable-package-types

Les packages de code doivent définir leur packageType sur application.

Dans le fichier ui.apps/pom.xml, la directive de configuration de version <packageType>application</packageType> de la déclaration du plug-in filevault-package-maven-plugin déclare son type de package.

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

Types de packages de contenu (modifiable) mutable-package-types

Les packages de contenu doivent définir leur packageType sur content.

Dans le fichier ui.content/pom.xml, la directive de configuration de version <packageType>content</packageType> de la déclaration du plug-in filevault-package-maven-plugin déclare son type de package.

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

Marquage de packages en vue d’un déploiement par Adobe Cloud Manager cloud-manager-target

Dans chaque projet générant un package, à l’exception du projet conteneur (all), ajoutez <cloudManagerTarget>none</cloudManagerTarget> à la configuration <properties> de la déclaration du plug-in filevault-package-maven-plugin pour vous assurer que le déploiement n’est pas effectué par Adobe Cloud Manager. Le package conteneur (all) doit être le package unique déployé via Cloud Manager qui, à son tour, incorpore tous les packages de code et de contenu requis.

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

Repo Init snippet-repo-init

Les scripts Repo Init sont définis dans la configuration d’usine OSGi RepositoryInitializer via la propriété scripts. Comme ces scripts sont définis dans les configurations OSGi, ils peuvent être facilement définis par le mode d’exécution à l’aide de la sémantique de dossier ../config.<runmode> habituelle.

Parce que les scripts sont généralement des déclarations multilignes, il est plus facile de les définir dans le fichier .config que dans le format .cfg.json basé sur 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
"]

La propriété OSGi scripts contient des directives définies par le langage Repo Init d’Apache Sling.

Package de structure du référentiel xml-repository-structure-package

Dans le fichier ui.apps/pom.xml, ainsi que dans tout autre fichier pom.xml qui déclare un package de code (<packageType>application</packageType>), ajoutez la configuration de package de structure de référentiel suivante au plug-in Maven FileVault. Vous pouvez créer votre propre package de structure de référentiel pour votre projet.

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

Intégrer des sous-packages dans le package conteneur xml-embeddeds

Dans le fichier all/pom.xml, ajoutez les directives <embeddeds> suivantes à la déclaration du plug-in filevault-package-maven-plugin. Souvenez-vous, n'utilisez pas la configuration <subPackages>. La raison en est qu’elle inclut les sous-packages dans /etc/packages plutôt que dans /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>
...

Définition du filtre du package conteneur xml-container-package-filters

Dans le fichier filter.xml du projet all (all/src/main/content/jcr_root/META-INF/vault/definition/filter.xml), incluez tout dossier -packages contenant des sous-packages à déployer :

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

Si plusieurs /apps/*-packages sont utilisés dans les cibles incorporées, ils doivent tous être énumérés ici.

Référentiels Maven tiers xml-3rd-party-maven-repositories

Dans le fichier pom.xml du projet Reactor, ajoutez toute directive de référentiel Maven public tierce qui s’avère nécessaire. La configuration <repository> complète doit être disponible auprès du fournisseur de référentiels tiers.

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

Dépendances entre les packages ui.apps et ui.content xml-package-dependencies

Dans le fichier ui.content/pom.xml, ajoutez les directives <dependencies> suivantes à la déclaration du 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>
...

Nettoyage du dossier cible du projet de conteneur xml-clean-container-package

Dans all/pom.xml, ajoutez le plug-in maven-clean-plugin qui nettoie le répertoire cible avant une version 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>

Ressources supplémentaires additional-resources