With the introduction of Adobe Experience Manager as a Cloud Service (AEMaaCS), customers who currently run AEM on premise or through Adobe Managed Services (AMS) and want to migrate to the cloud need to plan for changes made to the AEM repository. One tool to assist in the process is the Repository Modernizer.

This tool comes after you’ve already used the Best Practices Analyzer and is a part of the code refactoring process. The Repository Modernizer is needed to update the code repository structure from a 6.X structure to one that is compatible with AEMaaCS.

Transforming your code base so that it adheres to the new cloud service-compliant package structure is a crucial step and the Repository Modernizer tool can help reduce the project restructuring effort by separating code and content. This content separation is necessary to achieve zero downtime for deployments and AEM updates.

The Need for Repository Modernization and Content Separation

Unlike AEM run on premise or on AMS, AEMaaCS is containerized. This means that AEM instances are transient and can be created and destroyed at any time to meet demand. To keep code and content consistent across these transient containers, AEM defines two types of content: mutable and immutable.

Mutable content is stored and accessed via a common Content Repository Service by all AEM instances.  Immutable content is built into the image used to create fresh AEM instances in each container that is spun up. Immutable content can only be changed via a Cloud Manager Pipeline build and not at runtime.

Cloud-compatible Packaging Structure

The areas that are considered immutable are /apps and /libs whereas the rest of the repository including /content, /conf, /var, /etc, /oak:index, /system, /tmp, etc. is considered mutable.  Note that /oak:index still needs to be deployed with immutable code as part of a Pipeline deployment before mutable content can be deployed. Other mutable content may also be included as part of a Pipeline deployment, and then only that mutable content may be modified at runtime.

Additional content that you might not have kept in your code repository that needs to be included for use in AEMaaCS are OSGi Configurations including Repo Init for creating system users, etc. You won’t be able to edit OSGi configs at runtime the way you could in on non-cloud versions of AEM.  Also, if you have any custom run modes defined to be used for configurations, they are not supported in AEMaaCS.  You must only use the pre-defined, supported run modes that include the instance type of author or publish and the environment in which the cloud includes rde, dev, stage, and prod.

Using the Package Manager to deploy any immutable content cannot be done in AEMaaCS.  Any package that includes immutable content will fail when attempting to install via Package Manager.

Refer to the link included in the references below for more details on the recommended package structure.

Project Restructuring With Repository Modernizer

Projects that don’t conform to the above structure that supports the separation of mutable and immutable content will need to be restructured to adhere to the requirements.  Adobe provides the Repository Modernizer tool to assist in refactoring an AEM code base to be compatible with AEMaaCS.

Repository Modernizer Run Modes

Repository modernizer can be executed via two different methods:

Adobe I/O CLI (recommended)
Standalone utility

Adobe IO CLI (Recommended Approach)

The Repository Modernizer tool is provided as a utility under Adobe I/O CLI AEM Cloud Service Migration Plugin. To use this utility, one needs to follow the steps below.

1. Install Node.js 10.0+
The AEM Cloud Service Migration Plugin requires Node.js (JavaScript runtime environment) version 10.0 or higher to run which can be installed from https://nodejs.org/en

Mac users can also use Homebrew to install Node.js  https://brew.sh/

brew install nodejs 

2. Install Adobe I/O CLI  https://github.com/adobe/aio-cli
Next Step is to install Adobe I/O CLI plugin by running the following command 

npm install -g @adobe/aio-cli  

3. Install AEM Cloud Service Migration Plugin https://github.com/adobe/aio-cli-plugin-aem-cloud-service-migration 

aio plugins:install @adobe/aio-cli-plugin-aem-cloud-service-migration  

NOTE: Windows users will need to have Visual Studio installed on their system 

4. Set up Migration Tools Configuration
Migration tools are configured via a file named aem-migration-config.yaml. The location of migration tools configuration should be:

Mac/Unix: ~/.config/@adobe/aio-cli 

Windows: %LOCALAPPDATA%@adobeaio-cli 

Configurations for the Repository Modernizer are configured in the repositoryModernizer: section which includes configuration of the parent pom and all of the other projects to be included in the archetype. 

5. Change directory (cd) into the output directory, and run the command

aio aem-migration:repository-modernizer  

The above command will create an AEMaaCS-compatible structure in your current directory. Once a new project structure has been generated, you can initialize a new GIT repo, check it in, and commit it back to the GIT repository.  Now your code structure is ready to be used with AEM as a Cloud Service. 

 

References

Repository Modernizer
https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/migration-journey/refactoring-tools/repo-modernizer.html 
AIO CLI Plugin Cloud Migration
https://github.com/adobe/aio-cli-plugin-aem-cloud-service-migration 
Configure Cloud Service Migration Tool
https://github.com/adobe/aio-cli-plugin-aem-cloud-service-migration/blob/master/config/README.md 
AEM Project Structure
https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/implementing/developing/aem-project-content-package-structure.html 
Deploying to AEM as a Cloud Service
https://experienceleague.adobe.com/docs/experience-manager-cloud-service/content/implementing/deploying/overview.html  
Validate YAML syntax
https://www.yamllint.com/ 

 

Want more AEMaaCS content? Check out this 3-part series.

How Creative Content Automation in AEMaaCS is Speeding Up Content Delivery – Part 1

How Creative Content Automation in AEMaaCS is Speeding Up Content Delivery – Part 2

How Creative Content Automation in AEMaaCS is Speeding Up Content Delivery – Part 3