AEM Project Structure

This article outlines the changes required to Adobe Experience Manager Maven projects to be AEM as a Cloud Service compatible by ensuring that they respect the split of mutable and immutable content. Also, dependencies are established to create non-conflicting, deterministic deployments, and they are packaged in a deployable structure.

AEM application deployments must be composed of a single AEM package. This package should in turn contain subpackages that comprise everything required by the application to function, including code, configuration, and any supporting baseline content.

AEM requires a separation of content and code, which means a single content package cannot deploy to both /apps and runtime-writable areas (for example, /content, /conf, /home, or anything not /apps) of the repository. Instead, the application must separate code and content into discrete packages for deployment into AEM.

The package structure outlined in this document is compatible with both local development deployments and AEM Cloud Service deployments.

Mutable versus Immutable Areas of the Repository mutable-vs-immutable

The /apps and /libs areas of AEM are considered immutable because they cannot be changed (create, update, delete) after AEM starts (that is, at runtime). Any attempt to change an immutable area at runtime fails.

Everything else in the repository, /content, /conf, /var, /etc, /oak:index, /system, /tmp, and so on, are all mutable areas, meaning they can be changed at runtime.

Oak Indexes oak-indexes

Oak indexes (/oak:index) are managed by the AEM as a Cloud Service deployment process. The reason is because the Cloud Manager must wait until any new index is deployed and fully reindexed before switching over to the new code image.

For this reason, although Oak indexes are mutable at run time, they must be deployed as code so that they can be installed before any mutable packages are installed. Therefore /oak:index configurations are part of the Code Package and not part of the Content Package as described below.

Recommended Package Structure recommended-package-structure

This diagram provides an overview of the recommended project structure and package deployment artifacts.

The recommended application deployment structure is as follows:

Code Packages / OSGi Bundles

Content Packages

Container Packages

Extra Application Packages extra-application-packages

If other AEM Projects – which are themselves comprised of their own code and content packages – are used by the AEM deployment, their container packages should be embedded in the project’s all package.

For example, an AEM project that includes two vendor AEM applications might look like:

Package Types package-types

Packages are to be marked with their declared package type. Package types help clarify the purpose and deployment of a package.

For more information see Apache Jackrabbit FileVault - Package Maven Plugin documentation, Apache Jackrabbit Package Types, and the FileVault Maven configuration snippet below.

Marking Packages for Deployment by Adobe Cloud Manager marking-packages-for-deployment-by-adoube-cloud-manager

By default, Adobe Cloud Manager harvests all packages produced by the Maven build. However, because the container (all) package is the singular deployment artifact that contains all code and content packages, you must ensure only the container (all) package is deployed. To ensure this, other Packages the Maven build generates must be marked with the FileVault Content Package Maven Plug-In configuration of <properties><cloudManagerTarget>none</cloudManageTarget></properties>.

Repo Init repo-init

Repo Init provides instructions, or scripts, that define JCR structures, ranging from common node structures like folder trees, to users, service user, groups, and ACL definition.

The key benefits of Repo Init are they have implicit permissions to perform all actions defined by their scripts. And, such scripts are invoked early in the deployment lifecycle ensuring that all requisite JCR structures exist by the time code is run.

While Repo Init scripts themselves live in the ui.config project as scripts, they can, and should, be used to define the following mutable structures:

Repo Init scripts are stored as scripts entries of RepositoryInitializer OSGi factory configurations. As such, they can be implicitly targeted by run mode, allowing for differences between AEM Author and AEM Publish Services’ Repo Init scripts, or even between environments (Dev, Stage, and Prod).

Repo Init OSGi configs are best written in the .config OSGi configuration format as they support multi-lines, which is an exception to the best practices of using .cfg.json to define OSGi configurations.

When defining Users, and Groups, only groups are considered part of the application, and integral to its function. You still define Organization Users and Groups at runtime in AEM. For example, if a custom workflow assigns work to a named Group, define that Group by way of Repo Init in the AEM application. However, if the Grouping is merely organizational, such as “Wendy’s Team” and “Sean’s Team”, these groups are best defined and managed at runtime in AEM.

The full vocabulary for Repo Init scripts is available on the Apache Sling Repo Init documentation.

Repository Structure Package repository-structure-package

Code Packages require configuring the FileVault Maven plug-in’s configuration to reference a <repositoryStructurePackage> that enforces correctness of structural dependencies (to ensure that one code package does not install over another). You can create your own repository structure package for your project.

Only required for Code packages, meaning any Package marked with <packageType>application</packageType>.

To learn how to create a repository structure package for your application, see Develop a Repository Structure Package.

Content packages (<packageType>content</packageType>) do not require this repository structure Package.

Embedding Subpackages in the Container Package embeddeds

Content or code packages are placed in a special “side-car” folder and can be targeted for installation on either AEM author, AEM publish, or both, using the FileVault Maven plug-in’s <embeddeds> configuration. Do not use the <subPackages> configuration.

Common use-cases include:

To target AEM author, AEM publishes, or both, the package is embedded in the all container package in a special folder-location, in the following format:

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

Breaking down this folder structure:

For example, a deployment that contains AEM author and publish specific packages may look like the following:

Container Package’s Filter Definition container-package-filter-definition

Due to the embedding of the code and content subpackages in the container package, the embedded target paths must be added to the container project’s filter.xml. Doing so ensures that the embedded packages are included in the container package when built.

Simply add the <filter root="/apps/<my-app>-packages"/> entries for any 2nd-level folders that contain subpackages to deploy.

Embedding 3rd-party Packages embedding-3rd-party-packages

All packages must be available via the Adobe’s public Maven artifact repository or an accessible public, referenceable third-party Maven artifact repository.

If the third-party packages are in Adobe’s public Maven artifact repository, no further configuration is needed for Adobe Cloud Manager to resolve the artifacts.

If the third-party packages are in a public third-party Maven artifact repository, this repository must be registered in the project’s pom.xml and embedded following the method outlined above.

Third-party application/connectors should be embedded using its all package as a container in your project’s container (all) package.

Adding Maven dependencies follow standard Maven practices, and embedding of third-party artifacts (code and content packages) are outlined above.

Package Dependencies between the ui.apps from ui.content Packages package-dependencies

To ensure proper installation of the packages, it is recommended inter-package dependencies are established.

The general rule is packages containing mutable content (ui.content) should depend on the immutable code (ui.apps) that supports the rendering and use of the mutable content.

A notable exception to this general rule is if the immutable code package (ui.apps or any other), only contains OSGi bundles. If so, no AEM package should declare a dependency on it. The reason is because immutable code packages that only contain OSGi bundles, are not registered with AEM Package Manager. Therefore, any AEM package that depends on it has an unsatisfied dependency and fail to install.

The common patterns for content package dependencies are:

Simple Deployment Package Dependencies simple-deployment-package-dependencies

The simple case sets the ui.content mutable content package to depend on the ui.apps immutable code package.

Complex Deployment Package Dependencies complex-deploxment-package-dependencies

Complex deployments expand on the simple case, and set dependencies between the corresponding mutable content and immutable code packages. As required, dependencies can be established between immutable code packages as well.

Local Development and Deployment local-development-and-deployment

The project structures and organization outlined in this article is fully compatible local development AEM instances.

POM XML Snippets pom-xml-snippets

The following are Maven pom.xml configuration snippets that can be added to Maven projects to align to the above recommendations.

Package Types xml-package-types

Code and content packages, which are deployed as subpackages, must declare a package type of application or content, depending on what they contain.

Container Package Types container-package-types

The container all/pom.xml project does not declare a <packageType>.

Code (Immutable) Package Types immutable-package-types

Code packages must set their packageType to application.

In the ui.apps/pom.xml, the <packageType>application</packageType> build configuration directives of the filevault-package-maven-plugin plugin declaration declares its package type.

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

Content (Mutable) Package Types mutable-package-types

Content packages must set their packageType to content.

In the ui.content/pom.xml, the <packageType>content</packageType> build configuration directive of the filevault-package-maven-plugin plugin declaration declares its package type.

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

Marking Packages for Adobe Cloud Manager Deployment cloud-manager-target

In every project generating a Package, except for the container (all) project, add <cloudManagerTarget>none</cloudManagerTarget> to the <properties> configuration of the filevault-package-maven-plugin plug-in declaration to ensure they are not deployed by Adobe Cloud Manager. The container (all) package should be the singular package deployed via Cloud Manager, which in turn embeds all required code and content packages.

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

Repo Init scripts which contain the Repo Init scripts are defined in the RepositoryInitializer OSGi factory configuration via the scripts property. Because these scripts defined within OSGi configurations, they can be easily scoped by run mode using the usual ../config.<runmode> folder semantics.

Because scripts are typically multi-line declaration, it is easier to define them in the .config file, than the JSON-based .cfg.json format.

/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
"]

The scripts OSGi property contains directives as defined by the Apache Sling’s Repo Init language.

Repository Structure Package xml-repository-structure-package

In the ui.apps/pom.xml and any other pom.xml that declares a code package (<packageType>application</packageType>), add the following repository structure package configuration to the FileVault Maven plug-in. You can create your own repository structure package for your project.

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

Embedding Subpackages in the Container Package xml-embeddeds

In the all/pom.xml, add the following <embeddeds> directives to the filevault-package-maven-plugin plugin declaration. Remember, do not use the <subPackages> configuration. The reason is because it includes the subpackages in /etc/packages rather than /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>
...

Container Package’s Filter Definition xml-container-package-filters

In the all project’s filter.xml (all/src/main/content/jcr_root/META-INF/vault/definition/filter.xml), include any -packages folders that contain subpackages to deploy:

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

If multiple /apps/*-packages are used in the embedded targets, then they all must be enumerated here.

Third-party Maven Repositories xml-3rd-party-maven-repositories

In the reactor project’s pom.xml, add any necessary third-party public Maven repository directives. The full <repository> configuration should be available from the third-party Repository Provider.

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

Package Dependencies between the ui.apps from ui.content Packages xml-package-dependencies

In the ui.content/pom.xml, add the following <dependencies> directives to the filevault-package-maven-plugin plugin declaration.

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

Cleaning the Container Project’s Target Folder xml-clean-container-package

In the all/pom.xml, add the maven-clean-plugin plug-in which cleans the target directory before a Maven build.

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

Additional Resources additional-resources