The fundamentals of code development are similar in AEM as a Cloud Service compared to the AEM On Premise and Managed Services solutions. Developers write code and test it locally, which is then pushed to remote environments on AEM as a Cloud Service. Cloud Manager, which was an optional content delivery tool for Managed Services, is required. This delivery tool is now the sole mechanism for deploying code to AEM as a Cloud Service dev, stage, and production environments. For quick feature validation and debugging before deploying those previously mentioned environments, code can be synced from a local environment to a Rapid Development Environment.
The update of the AEM version is always a separate deployment event from pushing custom code. Viewed another way, custom code releases should be tested against the AEM version that is on production because that is what it is deployed on the top. AEM version updates that happen after that, which are frequent and are automatically applied. They are intended to be backward compatible with the customer code already deployed.
The rest of this document describes how developers should adapt their practices so they work with both AEM as a Cloud Service’s Version updates and customer updates.
For previous AEM solutions, the most current AEM version changed infrequently (roughly annually with quarterly service packs) and customers would update the production instances to the latest quickstart on their own time, referencing the API Jar. However, applications on AEM as a Cloud Service are automatically updated to the latest version of AEM more often, so custom code for internal releases should be built against the latest AEM version.
Like for existing non-cloud AEM versions, a local, offline development based on a specific quickstart is supported and is expected to be the tool of choice for debugging usually.
There are subtle operational differences between how the application behaves on a local machine versus the Adobe Cloud. These architectural differences must be respected during local development and could lead to a different behavior when deploying on the cloud infrastructure. Because of these differences, it is important to perform the exhaustive tests on dev and stage environments before rolling out new custom code in production.
To develop custom code for an internal release, the relevant version of the AEM as a Cloud Service SDK should be downloaded and installed. For additional information about using the AEM as a Cloud Service Dispatcher Tools, see this page.
The following video provides a high-level overview on how to deploy code to AEM as a Cloud Service:
Customers deploy custom code to cloud environments through Cloud Manager. Cloud Manager transforms locally assembled content packages into an artifact conforming to the Sling Feature Model, which is how an application on AEM as a Cloud Service is described when running in a cloud environment. As a result, when looking at the packages in Package Manager on Cloud environments, the name includes “cp2fm” and the transformed packages have all metadata removed. They cannot be interacted with, meaning they cannot be downloaded, replicated, or opened. Detailed documentation about the converter can be found here.
Content packages written for applications on AEM as a Cloud Service must have a clean separation between immutable and mutable content and Cloud Manager only installs the mutable content, also outputting a message like the following:
Generated content-package <PACKAGE_ID> located in file <PATH> is of MIXED type
The rest of this section describes the composition and implications of immutable and mutable packages.
All content and code persisted in the immutable repository must be checked into git and deployed through Cloud Manager. In other words, unlike current AEM solutions, code is never deployed directly to a running AEM instance. This workflow ensures that the code running for a given release in any Cloud environment is identical, which eliminates the risk of unintentional code variation on production. As an example, OSGI configuration should be committed to source control rather than managed at runtime by way of the AEM web console’s configuration manager.
As application changes due to the deployment pattern are enabled by a switch, they cannot depend on changes in the mutable repository except for service users, their ACLs, nodetypes, and index definition changes.
For customers with existing code bases, it is critical to go through the repository restructuring exercise described in AEM documentation to ensure that content formerly under the /etc is moved to the right location.
Some additional restrictions apply for these code packages, for example, install hooks are not supported.
As mentioned above, OSGI configuration should be committed to source control rather than through the web console. Techniques to do so include:
Read more about OSGI configuration at Configuring OSGi for AEM as a Cloud Service.
Sometimes, it might be useful to prepare content changes in source control so it can be deployed by Cloud Manager whenever an environment was updated. For example, it might be reasonable to seed certain root folder structures. Or, line up changes in editable templates to enable policies components that were updated by the application deployment.
There are two strategies to describe the content that is deployed by Cloud Manager to the mutable repository, mutable content packages and repoinit
statements.
Content such as folder path hierarchies, service users, and access controls (ACLs) are typically committed into a maven archetype-based AEM project. Techniques include exporting from AEM or writing directly as XML. During the build and deployment process, Cloud Manager packages the resulting mutable content package. The mutable content is installed at three different times during the deploy phase in the pipeline:
Ahead of startup of new version of application:
During startup of new version of application but ahead of switchover:
After switchover to new version of application:
/conf
) (add, modify, remove)It is possible to limit mutable content installation to author or publish by embedding packages in an install.author or install.publish folder under /apps
. Restructuring to reflect this separation was done in AEM 6.5 and details around recommended project restructuring can be found in the AEM 6.5 documentation.
Content packages are deployed to all environment types (dev, stage, prod). It is not possible to limit deployment to a specific environment. This limitation is in place to ensure the option of a test run of automated execution. Content that is specific to an environment requires manual installation by way of Package Manager.
Also, there is no mechanism to roll back the mutable content package changes after they’ve been applied. If customers detect a problem, they can choose to fix it in their next code release or as a last resort, restore the entire system to a point in time before the deployment.
Any included third-party packages must be validated as being AEM as a Cloud Service compatible, otherwise its inclusion results in a deployment failure.
As mentioned above, customers with existing code bases should conform to the repository restructuring exercise needed by the 6.5 repository changes described in the AEM 6.5 documentation.
For the following cases, it is preferable to take the approach of hand coding explicit content creation repoinit
statements in OSGI factory configurations:
Create/delete/disable service users
Create/delete groups
Create/delete users
Add ACLs
Definition of ACLs requires the node structures to be already present. Thus, preceding create path statements might be necessary.
Add path (for example, for root folder structures)
Add CNDs (nodetype definitions)
Repoinit is preferable for these supported content modification use cases due to the following benefits:
Repoinit
creates resources at startup so logic can take the existence of those resources for granted. In the mutable content package approach, resources are created after startup, so application code relying on them may fail.Repoinit
is a relatively safe instruction set as you explicitly control the action to be taken. Also, the only supported operations are additive except for a few security-related cases which allow removal of Users, Service Users, and Groups. In contrast, a removal of something in the mutable content package approach is explicit; as you define a filter, anything present covered by a filter is deleted. Still, caution should be taken since with any content there are scenarios where the presence of new content can alter the behavior of the application.Repoinit
performs fast and atomic operations. Mutable content packages in contrast can highly depend performance wise on the structures covered by a filter. Even if you update a single node, a snapshot of a large tree might be created.repoinit
statements on a local dev environment at runtime because they are run when the OSGi configuration gets registered.Repoinit
statements are atomic and explicit and are skipped if the state is already matching.When Cloud Manager deploys the application, it executes these statements, independently from the installation of any content packages.
To create repoinit
statements, follow the below procedure:
org.apache.sling.jcr.repoinit.RepositoryInitializer
in a configuration folder of the project. Use a descriptive name for the configuration like org.apache.sling.jcr.repoinit.RepositoryInitializer~initstructure.repoinit
statements to the script property of the config. The syntax and options are documented in Sling documentation. There should be explicit creation of a parent folder before their child folders. For example, an explicit creation of /content
before /content/myfolder
, before /content/myfolder/mysubfolder
. For ACLs being set on low-level structures, it is recommended to set them on a higher level and work with a rep:glob
restriction. For example, (allow jcr:read on /apps restriction(rep:glob,/msm/wcm/rolloutconfigs))
.For ACLs defined for nodes underneath /apps
or /libs
the repoinit
, execution starts on a blank repository. The packages are installed after repoinit
so statements cannot rely on anything defined in the packages but must define the preconditions like the parent structures underneath.
For ACLs, the creation of deep structures might be cumbersome. Therefore, it is more reasonable to define an ACL on a higher level and constrain where it is supposed to act by way of a rep:glob
restriction.
More detail about repoinit
can be found in the Sling documentation
There are use cases where a content package should be installed as a “one off”. For example, importing specific content from production on to staging to debug a production issue. For these scenarios, Package Manager can be used in environments on AEM as a Cloud Service.
Since Package Manager is a runtime concept, it is not possible to install content or code into the immutable repository, so these content packages should only consist of mutable content (mainly /content
or /conf
). If the content package includes content that is mixed (both mutable and immutable content), only the mutable content is installed.
The Package Manager user interface might return an undefined error message if a package takes longer than ten minutes to install.
This time is not due to an error with the installation, but to a timeout that Cloud Service has for all requests.
Do not retry the installation if you see such an error. The installation is proceeding correctly in the background. If you do restart the installation, some conflicts could be introduced by multiple concurrent import processes.
Any content-packages installed by way of Cloud Manager (both mutable and immutable) appear in a frozen state in AEM Package Manager’s user interface. These packages cannot be reinstalled, rebuilt, or even downloaded, and are listed with a “cp2fm” suffix, indicating their installation was managed by Cloud Manager.
It is common for customers to include pre-built packages from third-party sources such as software vendors like Adobe’s translation partners. The recommendation is to host these packages in a remote repository and reference them in the pom.xml
. This method is possible for public repositories and also for private repositories with password protection, as described in password protected maven repositories.
If storing the package in a remote repository is not possible, customers can place in a local, file system-based Maven repository, which is committed to SCM as part of the project. It is referenced by whatever depends on it. The repository is declared in the project pom as illustrated below:
<repository>
<id>project.local</id>
<name>project</name>
<url>file:${maven.multiModuleProjectDirectory}/repository</url>
</repository>
Any included third-party packages must adhere to AEM as a Cloud Service coding and packaging guidelines described in this article, otherwise its inclusion results in a deployment failure.
The following Maven POM.xml
snippet shows how third-party packages can be embedded in the project’s “Container” package, typically named ‘all’, by way of the filevault-package-maven-plugin Maven plugin configuration.
...
<plugin>
<groupId>org.apache.jackrabbit</groupId>
<artifactId>filevault-package-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
...
<embeddeds>
...
<!-- 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>
...
Like AEM updates, customer releases are deployed using a rolling deployment strategy to eliminate author cluster downtime under the right circumstances. The general sequence of events is described below, where nodes with both the old and new versions of customer code are running the same version of AEM code.
New or modified indexes cause an extra indexing or reindexing step before the new version can take on traffic. Details about index management in AEM as a Cloud Service can be found in this article. You can check the indexing status of build pages on Cloud Manager, and receive a notification when the new version is ready to take traffic.
The time needed for a rolling deployment varies depending on the size of the index. The reason is because the new version cannot accept traffic until the new index is generated.
Currently, AEM as a Cloud Service does not work with index management tools such as ACS Commons Ensure Oak Index tool.
The publication mechanism is backwards compatible with the AEM Replication Java™ APIs.
To develop and test with replication with the cloud ready AEM quickstart, the classic replication capabilities must be used with an Author/Publish setup. If the user interface entry point on AEM Author is removed for the cloud, users go to http://localhost:4502/etc/replication
for configuration.
As detailed above, AEM as a Cloud Service’s rolling deployment strategy implies that both the old and new versions may be operating at the same time. Therefore, be cautious of code changes that are not backwards compatible with the old AEM version that is still operation.
In addition, the old release should be tested for compatibility with any new mutable content structures applied by the new release if there is a rollback, because mutable content is not removed.
Changing service users, or ACLs that access content or code, could lead to errors in the older AEM versions resulting in access to that content or code with outdated service users. To address this behavior, the recommendation is to make changes spread across at least two releases, with the first release acting as a link before cleaning up in the subsequent release.
If changes to indexes are made, it is important that the new version continues to use its indexes until it is terminated, while the old version uses its own modified set of indexes. The developer should follow the index management techniques described in this article.
If a failure is reported or detected after the deployment, it is possible that a rollback to the old version is required. Ensure that the new code is compatible with any new structures created by that new version since the new structures (any mutable content) are not rolled back. If the old code is not compatible, fixes must be applied in subsequent customer releases.
Rapid Development Environments (or RDEs for short) allow developers to quickly deploy and review changes, minimizing the amount of time necessary to test features that are already proven to work on a local development environment.
Unlike regular dev environments, which deploy code by way of Cloud Manager pipeline, developers use command-line tools to sync code from a local development environment to the RDE. After the changes are successfully tested in an RDE, deploy them to a regular Cloud Development environment through the Cloud Manager pipeline, which puts the code through the appropriate quality gates.
In existing AEM solutions, customers have the option of running instances with arbitrary run modes and apply OSGI configuration or install OSGI bundles to those specific instances. Run modes that are defined typically include the service (author and publish) and the environment (rde, dev, stage, prod).
AEM as a Cloud Service on the other hand is more opinionated about which run modes are available and how OSGI bundles and OSGI configuration can be mapped to them:
<service>.<environment_type>
is being supported, whereas these environments have to be used in this particular order (for example, author.dev
or publish.prod
). The OSGI tokens should be referenced directly from code rather than using the getRunModes
method, which no longer includes the environment_type
at runtime. For more information, see Configuring OSGi for AEM as a Cloud Service.install.author
or install.publish
.AEM as a Cloud Service does not allow using run modes to install content for specific environments or services. If a development environment must be seeded with data or HTML that is not in the staging or production environments, Package Manager can be used.
The supported run mode configurations are:
The OSGI configuration that has the most matching run modes is used.
When developing locally, a run mode startup parameter, -r
, is used to specify the run mode OSGI configuration.
$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev
Maintenance Task configurations must be persisted in source control because the Tools > Operations screen is not available in Cloud environments. This benefit ensures that changes are intentionally persisted rather than reactively applied and forgotten. See Maintenance Task article for additional information.