AEM Project Structure
- Topics:
- Developing
CREATED FOR:
- Admin
- Developer
TIPThis 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.
TIPMutable versus Immutable Areas of the Repository
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.
WARNING/libs should not be modified. Only AEM product code may deploy to /libs.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.
TIPRecommended 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
-
The OSGi bundle Jar file is generated, and directly embedded in the all project.
-
The
ui.appspackage contains all the code to be deployed and only deploys to/apps. Common elements of theui.appspackage include, but are not limited to:- Component definitions and HTL scripts
/apps/my-app/components
- JavaScript and CSS (via Client Libraries)
/apps/my-app/clientlibs
- Overlays of
/libs/apps/cq,/apps/dam/, and so on.
- Fallback context-aware configurations
/apps/settings
- ACLs (permissions)
- Any
rep:policyfor any path under/apps
- Any
- Precompiled bundled scripts
- Component definitions and HTL scripts
NOTEContent Packages
-
The
ui.contentpackage contains all content and configuration. The Content Package contains all the node definitions not in theui.appsorui.configpackages, or in other words, anything not in/appsor/oak:index. Common elements of theui.contentpackage include, but are not limited to:- Context-aware configurations
/conf
- Required, complex content structures (that is, Content build-out that builds on and extends past Baseline content structures defined in Repo Init.)
/content,/content/dam, and so on.
- Governed tagging taxonomies
/content/cq:tags
- Legacy etc nodes (Ideally, migrate these nodes to non-/etc locations)
/etc
- Context-aware configurations
Container Packages
-
The
allpackage is a container package that ONLY includes deployable artifacts, the OSGI bundle Jar file,ui.apps,ui.config, andui.contentpackages as embeds. Theallpackage must not have any content or code of its own, but rather delegate all deployment to the repository to its subpackages or OSGi bundle Jar files.Packages are now included using the Maven FileVault Package Maven plugin’s embedded configuration, rather than the
<subPackages>configuration.For complex Experience Manager deployments, it may be desirable to create multiple
ui.apps,ui.config, andui.contentprojects/packages that represent specific sites or tenants in AEM. If this approach is done, ensure the split between mutable and immutable content is respected, and the required content packages and OSGi bundle Jar files are embedded as subpackages in theallcontainer content package.For example, a complex deployment content package structure might look like this:
-
allcontent package embeds the following packages, to create a singular deployment artifactcommon.ui.appsdeploys code required by both site A and site Bsite-a.coreOSGi bundle Jar required by site Asite-a.ui.appsdeploys code required by site Asite-a.ui.configdeploys OSGi configurations required by Site Asite-a.ui.contentdeploys content and configuration required by site Asite-b.coreOSGi bundle Jar required by site Bsite-b.ui.appsdeploys code required by site Bsite-b.ui.configdeploys OSGi configurations required by site Bsite-b.ui.contentdeploys content and configuration required by site B
-
-
The
ui.configpackage contains all OSGi configurations:-
Considered code and belongs to OSGi bundles but does not contain regular content nodes. Thus it is marked as a container package
-
Organizational folder containing run mode-specific OSGi config definitions
/apps/my-app/osgiconfig
-
Common OSGi configuration folder containing default OSGi configurations that apply to all target AEM as a Cloud Service deployment targets
/apps/my-app/osgiconfig/config
-
Run mode-specific OSGi configuration folders that contain default OSGi configurations that apply to all target AEM as a Cloud Service deployment targets
/apps/my-app/osgiconfig/config.<author|publish>.<dev|stage|prod>
-
Repo Init OSGi configuration scripts
-
Repo Init is the recommended way to deploy (mutable) content that is logically part of the AEM application. The Repo Init OSGi configurations should be places in the appropriate
config.<runmode>folder as outlined above, and be used to define:- Baseline content structures
- Users
- Service Users
- Groups
- ACLs (permissions)
-
-
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:
-
allcontent package embeds the following packages, to create a singular deployment artifactcoreOSGi bundle Jar required by the AEM applicationui.appsdeploys code required by the AEM applicationui.configdeploys OSGi configurations required by the AEM applicationui.contentdeploys content and configuration required by the AEM applicationvendor-x.alldeploys the everything (code and content) required by the vendor X applicationvendor-y.alldeploys the everything (code and content) required by the vendor Y application
Package Types
Packages are to be marked with their declared package type. Package types help clarify the purpose and deployment of a package.
- Container packages must set their
packageTypetocontainer. Container packages must not contain regular nodes. Only OSGi bundles, configurations, and sub packages are allowed. Containers in AEM as a Cloud Service are not allowed to use install hooks. - Code (immutable) packages must set their
packageTypetoapplication. - Content (mutable) packages must set their
packageTypetocontent.
For more information see Apache Jackrabbit FileVault - Package Maven Plugin documentation, Apache Jackrabbit Package Types, and the FileVault Maven configuration snippet below.
TIPMarking Packages for Deployment by Adobe 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>.
TIPRepo 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:
- Baseline content structures
- Service Users
- Users
- Groups
- ACLs
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.
TIPscripts field, or the references configuration does not work.The full vocabulary for Repo Init scripts is available on the Apache Sling Repo Init documentation.
TIPRepository 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.
TIPEmbedding Subpackages in the Container Package
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:
- ACLs/permissions that differ between AEM author users and AEM publish users
- Configurations that are used to support activities only on AEM author
- Code such as integrations with back-office systems, only required to run on AEM author
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:
-
The 1st-level folder must be
/apps. -
The 2nd-level folder represents the application with
-packagespost-fixed to the folder name. Often, there is only a single 2nd-level folder that all subpackages are embedded under, however any number of 2nd-level folders can be created to best represent the application’s logical structure:/apps/my-app-packages/apps/my-other-app-packages/apps/vendor-packages
WARNINGBy convention, subpackage embedded folders are named with the suffix of-packages. This naming ensures that the deployment code and content packages are not deployed the target folders of any subpackage/apps/<app-name>/...which results in destructive and cyclic installation behavior. -
The 3rd-level folder must be either
application,contentorcontainer- The
applicationfolder holds code packages - The
contentfolder holds content packages - The
containerfolder holds any extra application packages that might be included by the AEM application.
This folder name corresponds to the package types of the packages that it contains.
- The
-
The 4th-level folder contains the subpackages, and must be one of:
installso you install on both AEM author and AEM publishinstall.authorso you install only on AEM authorinstall.publishso you install only on AEM publish
Onlyinstall.authorandinstall.publishare supported targets. Other run modes are not supported.
For example, a deployment that contains AEM author and publish specific packages may look like the following:
-
allContainer package embeds the following packages, to create a singular deployment artifactui.appsembedded in/apps/my-app-packages/application/installdeploys code to both AEM author and AEM publishui.apps.authorembedded in/apps/my-app-packages/application/install.authordeploys code to only AEM authorui.contentembedded in/apps/my-app-packages/content/installdeploys content and configuration to both AEM author and AEM publishui.content.publishembedded in/apps/my-app-packages/content/install.publishdeploys content and configuration to only AEM publish
TIPContainer Package’s 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.
TIPEmbedding 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.
TIPPackage Dependencies between the ui.apps from ui.content Packages
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.
TIPThe common patterns for content package dependencies are:
Simple Deployment Package Dependencies
The simple case sets the ui.content mutable content package to depend on the ui.apps immutable code package.
-
allhas no dependenciesui.appshas no dependenciesui.contentdepends onui.apps
Complex Deployment 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.
-
allhas no dependenciescommon.ui.apps.commonhas no dependenciessite-a.ui.appsdepends oncommon.ui.appssite-a.ui.contentdepends onsite-a.ui.appssite-b.ui.appsdepends oncommon.ui.appssite-b.ui.contentdepends onsite-b.ui.apps
Local Development and Deployment
The project structures and organization outlined in this article is fully compatible local development AEM instances.
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
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
The container all/pom.xml project does not declare a <packageType>.
Code (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
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
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
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
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
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
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
WARNINGIn 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
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
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>