The AEM version 6.5 is a feature-packed upgrade from Adobe. Here’s a step-by-step upgrade process that has been followed and curated to successfully upgrade many of our enterprise customers to AEM 6.5.
This post talks about the upgrade procedure for the AEM 6.5.
Section
Before executing your upgrade, there are several steps that you must follow. Please also visit Adobe’s official page for Upgrading Code and Customizations and Pre-Upgrade Maintenance Tasks for more information.
Subsequently, make sure that your system meets the requirements for the new version of AEM.
Please verify how Pattern Detector can help you estimate the complexity of your upgrade and also see the Upgrade Scope and Requirements section of Planning Your Upgrade for more information.
Following tasks can prepare your AEM instance for the upgrade process. Please make sure to attempt and complete these steps before proceeding for the actual In-place upgrade to AEM 6.5.
When you start your AEM using the QuickStart jar, then a file called quickstart.properties under /crx-quickstart/conf will be created. However, If so far you have started your AEM, only with the start script, then this file will not be present and this could create a problem in upgrade process and your upgrade might fail. Therefore, you may attempt to start AEM using QuickStart Jar so that this file gets generated.
Make sure to provide executable permissions to all the scripts located in /crx-quickstart/bin and /crx-quickstart/monitoring This is required in order to perform the upgrade process.
https://aemserver:aemport/system/console/jmxNOTE
There is a known bug in AEM 6.1 where disk storage might be occupied; One can clear excessive disk storage by running Oak-run tool .
java -Xmx4096m -jar aem-quickstart.jar -unpackThis migration is not required if you are upgrading from AEM 6.3. For versions older than 6.3, Adobe provides a tool that can be used to migrate the repository to the new version of the Oak Segment Tar present in AEM 6.3. It is provided as part of the QuickStart package and is mandatory for any upgrades that will be using TarMK. Upgrades for environments that are using MongoMK do not require repository migration.
The actual migration is performed using the standard AEM QuickStart jar file, executed with a new -x crx2oak option which executes the crx2oak tool in order to simplify the upgrade and make it more robust.
To determine the exact command you should run, use the following command:
java -Xmx4096m -jar aem-quickstart.jar -v -x crx2oak -xargs -- --load-profile <> <>
Where <> and <> are replaced with the profile and flags listed in Adobe’ official doc here
Check the configuration files beneath crx-quickstart/install folder. If a migration was necessary, these will be updated to reflect the target repository.
You may skip this section if you are upgrading from AEM 6.3. While the provided crx2oak profiles should meet the needs of most customers, there are times when additional parameters will be necessary.
If you run into an error during your migration, it is possible that there are aspects of your environment that require additional configuration options to be provided. If so, you will likely encounter the following error.
Checkpoints won’t be copied, because no external datastore has been specified. This will result in the full repository reindexing on the first start.
Use skip-checkpoints to force the migration, visit Checkpoints migration for more details.
The migration process needs access to binaries in the datastore and is unable to find it. To specify your datastore configuration, include the following flags in the <> portion of your migration command:
For S3 datastores:
--src-s3config=/path/to/SharedS3DataStore.config --src-s3datastore=/path/to/datastore
Where /path/to/SharedS3DataStore.config represents the path to your S3 datastore config file and /path/to/datastore represents the path to your S3 datastore.
For File datastores:
--src-datastore=/path/to/datastore
Where /path/to/datastore represents the path to your File Datastore.
Determining the correct upgrade start command
To execute the upgrade, it is important to start AEM using the QuickStart jar file to bring up the instance. For upgrading to AEM 6.5, please also see other content restructuring and migration options in Lazy Content Migration that you can choose with the upgrade command.
IMPORTANT
If you are running Oracle Java 11 (or generally versions of Java newer than 8), additional switches will need to be added to your command line when starting AEM. For more information, see Java 11 Considerations.
Note that starting AEM from the start script will not start the upgrade. Most customers start AEM using the start script and have customized this start script to include switches for environment configurations such as memory settings, security certificates, etc.
For this reason, Adobe recommends following this procedure to determine the proper upgrade command:
ps -ef | grep java/usr/bin/java -server -Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true -Dsling.run.modes=author,crx3,crx3tar -jar crx-quickstart/app/cq-quickstart-6.2.0-standalone-quickstart.jar start -c crx-quickstart -i launchpad -p 4502 -Dsling.properties=conf/sling.propertiescrx-quickstart/app/aem-quickstart*.jar in this case) with the new jar that is adjacent to the crx-quickstart folder. Using our previous command as an example, our command would be:/usr/bin/java -server -Xmx1024m -Djava.awt.headless=true - Dsling.run.modes=author,crx3,crx3tar -jar cq-quickstart6.5.0.jar -c crx-quickstart -p 4502 - Dsling.properties=conf/sling.propertiesOnce in-place upgrade process has been completed, the updated code base should also be deployed. Steps for updating the code base to work in the target version of AEM can be found on Adobe’s doc Upgrade Code and Customizations page.
- /etc/* now this node needs to be moved to /libs/ or /content/ or /conf/ based on usages)Perform post-upgrade checks and troubleshooting
Please See Adobe’s official page for Post Upgrade Checks and Troubleshooting.
We hope this blog post would help you achieve a smoother upgrade scenario on AEM 6.5. We request you to share it with your colleagues, peers and reach out to us if you have queries.