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.
Performing an in-place upgrade to AEM 6.5v
This post talks about the upgrade procedure for the AEM 6.5.
Section
- Pre-Upgrade
- In Place Upgrade
- Code Base Upgrade
- Post Upgrade
Pre-Upgrade Scenario:
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.
Pre-upgrade checks and tasks
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.
- Back up your running AEM instance
- For big repositories it is important to have a sufficient disk space (almost 1.5 times the repository size)
- Create a package/ backup /etc node structure
- Verify QuickStart. Properties file
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.
Running pre-upgrade tasks using Adobe’s pre-upgrade package
- Install the package of pre-upgrade-tasks from Adobe package share.
- Go to JMX Console:
https://aemserver:aemport/system/console/jmx
- Go to preupgradetasks, and invoke MBean - runAllPreUpgradeTasks()
NOTE
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 .
Migration requirements
- Minimum Java version requirement: The migration tool only works with Java versions 7 and up. Note that for AEM 6.3 and up, Oracle’s JRE 8 and IBM’s JRE 7 & 8 are the only supported versions.
- Upgraded AEM Instance: If you are upgrading from a version older than 5.6, make sure that you have performed an in-place upgrade to AEM 6.0 by following the procedure described in the 6.0 version of the Upgrade documentation from Adobe.
- Review Adobe’s Technical requirements page
Preparation of the AEM QuickStart jar file
- Stop the instance if it is already running
- Download the new AEM jar file and use it to replace the old one outside the crx-quickstart directory
- Unpack the new QuickStart jar by running below command
- NOTE – it is an important step, please do not skip
java -Xmx4096m -jar aem-quickstart.jar -unpack
Content Repository Migration
This 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.
Determine the correct command for migration:
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.
Analysing migration problems
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.
Performing an in-place upgrade
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:
- On a running AEM instance, execute the following from the command line:
ps -ef | grep java- Look for the AEM process. It will look something like:
/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.properties- Modify the command by replacing the path to the existing jar (
crx-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.properties- This will ensure that all proper memory settings, custom runmodes (if any), and other environmental parameters are applied for the upgrade. After the upgrade has completed, the instance may be started from the start script for future start/stop.
- Monitor error and upgrade log for more details on upgrade process.
Deploying codebase upgrade
Once 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.
Quick summary for codebase upgrade:
- Trigger a start of AEM using new 6.5 Quickstart Jar
- Consider deploying codebase
- Update Maven (if need be)
- Use latest Uber Jar from Adobe (if required)
- Reflect new changes in your POM/ Parent POM
- Detect deprecated APIs
- Convert Services to Declarative Services.
- Configure and Use Service Users and avoid using declarative admin resource resolver
- We have backed up
- /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.
