Make your CONGA-based AEM project ready for AEM Cloud Service
- 1 Overview
- 2 Step 1: Update Dependencies
- 3 Step 2: Update ACS AEM Commons package references
- 4 Step 3: Enable reproducible builds in Maven
- 5 Step 4: Remove AEM Service Packs/Hotfixes
- 6 Step 5: Remove obsolete Apache Sling bundles
- 7 Step 6: Switch to AEM SDK API
- 8 Step 7: Remove AEM Core Components dependency/packages
- 9 Step 8: Create service users via repoinit
- 10 Step 9: Remove longCacheKey definitions
- 11 Step 10: Make content package modules compatible with AEM Cloud
- 12 Step 11: Make CONGA-generated content packages compatible with AEM Cloud
- 13 Step 12: Add new CONGA Environments for AEM Cloud
- 14 Step 13: Build “all” and “dispatcher config” packages for Cloud Manager
- 15 Step 14 - Workarounds for Issues
- 16 Last Remarks
- 17 Related articles
Overview
This article describes the required steps to make your CONGA-based AEM project compatible with AEM as a Cloud Service and deployment via Adobe Cloud Manager.
If you want to create a new CONGA-based project you do not need this article, but can create an new project straightaway with the wcm.io Maven Archetype for AEM 3.0.0 or above using “cloud” as optionAemVersion
. It’s also helpful to setup an new sample project with this archetype alongside with a migration, because in this article we aim to reach the same structure as it is generated by the archetype.
Step 1: Update Dependencies
Make sure to update the following dependencies:
Update to latest version (1.4.8 or later) of aem-global-parent in the parent POM to get the latest versions of CONGA plugins and other updates
Update all other wcm.io dependencies to the latest versions - some had some small fixes for AEM Cloud compatibility
Check other dependencies for required updates, e.g. ACS AEM Commons or AC Tool
Step 2: Update ACS AEM Commons package references
In case you are using ACS AEM Commons in your project you have to update the package references and update to latest version (6.0.x or above):
In the parent POM, replace the reference to
com.adobe.acs:acs-aem-commons-content
with:<dependency> <groupId>com.adobe.acs</groupId> <artifactId>acs-aem-commons-all</artifactId> <version>${acs.aem.commons.version}</version> <type>zip</type> </dependency>
In the config-definition POM, replace the reference to
com.adobe.acs:acs-aem-commons-content
with:<dependency> <groupId>com.adobe.acs</groupId> <artifactId>acs-aem-commons-all</artifactId> <type>zip</type> <scope>compile</scope> </dependency>
In the CONGA role in
config-definition/src/main/roles
, replace the reference tocom.adobe.acs:acs-aem-commons-content
with:- url: url: mvn:com.adobe.acs/acs-aem-commons-all//zip dir: packages
Step 3: Enable reproducible builds in Maven
If you are using bnd-maven-plugin
to build your OSGi bundles (what we recommend) there is a special edge case using Sling-Initial-Content and Sling i18n JSON files (example) and wrong ordering of files in the bundle ZIP file which may lead to deployment failures.
To solve this problem add this Maven property to your project’s parent POM to enable the “reproducible builds” feature of Maven (which is useful anyways) for your project:
It’s not relevant which actual timestamp value you are using here - it’s automatically updated during the release by the release or gitflow maven plugins.
Step 4: Remove AEM Service Packs/Hotfixes
In case you have referenced any AEM Service Pack or Hotfix content packages in the CONGA role files in
remove all of them - they are no longer required for AEM Cloud service.
Step 5: Remove obsolete Apache Sling bundles
Check if you have embedded Apache Sling bundles in the content-packages/complete package that are obsolete, because the same or a newer version of it is already available in the AEM Cloud version you are using. To remove them:
Remove the version definition from the parent POM
Remove the dependency definition from the complete package and the reference to it in the
embeddeds
section of the package definition.Remove dependency definitions to them in the bundle POMs
This step is optional - it does not harm if you have included older versions of Sling Bundles in your complete packages - they will be ignored if a newer version is already present in AEM.
Step 6: Switch to AEM SDK API
Remove the reference to io.wcm.maven:io.wcm.maven.aem-dependencies
in your parent POM and replace it with a new one that includes the AEM Cloud Service dependencies maintained by wcm.io:
Lookup the latest version available for this dependency in Maven Central.
Additionally you have to replace all references to com.adobe.aem:uber-jar
in your bundle POMs with this dependency:
Step 7: Remove AEM Core Components dependency/packages
The latest version of AEM Core Components is already included in the AEM SDK API and AEM Cloud Service, it’s not longer required to reference it as explicit dependency or deploy the packages together with your project:
Remove all references to
com.adobe.cq:core.wcm.components.core
andcom.adobe.cq:core.wcm.components.all
from your parent POM.Remove all references to
com.adobe.cq:core.wcm.components.core
from your bundle POMs.Remove all references to
com.adobe.cq:core.wcm.components.all
from theconfig-definition
POM, and remove the reference to it from the CONGA Roles atconfig-definition/src/main/roles
.
Step 8: Create service users via repoinit
Update: It is recommended to use the OOTB principals instead of creating you own service users, see https://wcm.io/handler/configuration.html for examples.
Some wcm.io bundles requires service users to set up appropriate permissions, and this was done in the past using CONGA-generated bundles with a file definition in the CONGA role like this wcm-io-samples-aem-cms-author-systemusers with this JSON template .
Remove this file definition {project}-aem-cms-author-systemusers.json
from the CONGA role and the HBS template it references and replace it with an addition to the {project}-aem-cms-config.provisioning.hbs
template which defines the OSGi configurations of your project using Sling RepoInit syntax:
Replace the user names accordingly. If you have created more system users or more “initialization” packages like this, convert them to repoinit as well. Additional benefit: this repoinit syntax us much more compact and better readable.
Step 9: Remove longCacheKey definitions
It’s not longer required to set longCacheKey properties for client libraries - this feature is enabled by default in AEM Cloud Service generating a hash based on the content of the client library.
Please note that this is only the case in the cloud environment, not when using the local quickstart JAR of AEM Cloud SDK. If you want to activate the feature for the local AEM instance as well, set the “Long term client side cache key” in the “Adobe Granite HTML Library Manager” OSGi configuration to /.*;hash
.
Step 10: Make content package modules compatible with AEM Cloud
The Project Structure documentation of AEM Cloud Service explains the new requirements for content packages (immutable and mutable, that means application packages and config/sample content packages).
If you’ve not done it already, make sure you have switched all your content package projects to the Apache Jackrabbit FileVault Package Maven Plugin (see migration guide).
The latest wcm.io aem-global-parent
also includes the latest version of the FileVault Package Maven Plugin which has built-in additional validation steps, you may have to adapt your packages, see this guide .
Check/adapt all your content package module POMs:
Make sure the appropriate
packageType
property is set for each content package. “application” and “container” are immutable content packages, “content” are mutable content packages. It’s not allowed to use the “mixed” type. Example:If you have packages that mix immutable and mutable content (the validation rules of the FileVault Package Maven Plugin will tell you that), you have to split up your packages.
Make sure that all packages have a new package property
cloudManagerTarget
set tonone
. This instructs the Cloud Manager to ignore this package - it will be handed over to the Cloud Manager as part of an “all” package generated by CONGA in a later step. Example:You do not have to declare dependencies between your packages. This is done by CONGA automatically based on the order of the files defined in the CONGA role.
It is recommended (but not mandatory) to create a “repository structure” package module that defines all application folders that are already present OOTB in AEM Cloud Service and which should not fail the validation of the other packages if application content is deployed to them. In the Adobe documentation this module is referenced as
repository-structure
, in the latest Adobe AEM project archetypes it’s namedui.apps.structure
.For CONGA-bases projects the recommendation is to create it at
Example package definition (full example):
Once this is defined it can be referenced from the other content package modules containing immutable application content of the project. Example:
Make sure this package gets never deployed to any AEM instance! It’s only a tool for supporting the package validation during build time.
Step 11: Make CONGA-generated content packages compatible with AEM Cloud
Check the CONGA roles defined at config-definition/src/main/roles
if you have custom packages defined using JSON templates and the aem-contentpackage
post processor:
Set a package type for each content package. Example:
Split packages that mix immutable with mutable content, or check if the package can be replaced with repoinit statements.
This applies not to OSGi configuration packages generated with the aem-contentpackage-osgiconfig
post processor - they are automatically generated as immutable container packages.
Step 12: Add new CONGA Environments for AEM Cloud
The way recommended by Adobe is to put the AEM application code directly in the GIT repository provided by the Cloud Manager. In this case no separate “configuration-management” GIT repository is used, so we need to define an additional CONGA Environment for the AEM cloud dev/stage/prod environments. Create a CONGA environment directly in the application GIT repository at config-definition/src/main/dev-environments
:
Define a new “cloud” environment:
Copy the https://github.com/wcm-io/wcm-io-maven-archetype-aem/blob/develop/src/main/resources/archetype-resources/config-definition/src/main/dev-environments/cloud.yaml template from the archetype and remove the velocity statements (#set, #if..#end)
Replace the variables
${projectName}
and${packageGroupNames}
Validate the root/redirect paths in the dispatcher/tenant configuration
Consider to use the
cloudManagerConditional
configuration option instead of the simplifiedserverName
/serverAlias
definition to define the host names for each cloud environment
Rename the predefined “development” environment to “local” to avoid confusion with the cloud “dev” environment. For this you have to:
Rename the file
development.yaml
tolocal.yaml
Change the references to the “development” CONGA_ENVIRONMENT in the
configuration/definition/packages-upload.sh
andbuild-deploy.sh
scripts to “local”
Mark this “local” environment to be ignored by the Cloud Manager (it’s only used for local AEM deployment) by adding to the
config:
section:
The rationale behind this:
We define a single “cloud” CONGA environment instead of three for dev/stage/prod cloud environments because the Adobe Cloud Manager has currently limitations and does not support deploying packages on some and environments and not on others (e.g. sample content not on prod). Therefore we currently have to live with a single “cloud” environment. It’s still possible to define different host names for each environment, and OSGi configuration can also be defined individually using the environment names as run modes.
CONGA will build a separate “all” package for author and publish instances containing the selected packages with dependencies automatically defined following the order of the files in the role definitions
An additional ZIP file is generated containing the dispatcher configuration which is used for all cloud environments as well.
Step 13: Build “all” and “dispatcher config” packages for Cloud Manager
Add two new plugin executions to the POM at config-definition/pom.xml
:
Replace ${packageGroupName}
with the group name of packages you use in this project.
This will generate the ZIP files that will be picked up by Adobe Cloud Manager to deploy the content packages and dispatcher configuration to AEM Cloud Service.
Step 14 - Workarounds for Issues
This section lists workarounds for issues that are currently present in AEM Cloud 2020.4. They may be fixed in more recent releases and no longer required.
Do not configure Sling Log Manager
Check if you have a configuration present for the PID org.apache.sling.commons.log.LogManager
in any of the provisioning file templates at
If you find such a configuration, remove it completely. It will fail the image build in Adobe Cloud Manager.
NodeJS Maven Plugin
If you encounter problems with building your frontend code by Adobe Cloud Manager consider switching from wcm.io NodeJS Plugin to frontend-maven-plugin. See configuration example.
Last Remarks
Use a Sandbox in AEM Cloud to test your migrated project thoroughly. Do not deploy to a stage/prod environment before all is running as expected on a dev environment (it’s easy to delete a dev environment and start from scratch).