Upgrading to AEM 5.6.1

You are reading the Adobe Experience Manager 5.6.1 version of Upgrading to AEM 5.6.1.
This documentation is also available for the following versions: AEM 5.6  CQ 5.5  CQ 5.4  CQ 5.3 

The basic procedure for upgrading to AEM 5.6.1 is straightforward: Simply stop your existing AEM nstance, replace the jar file (for standalone instances) or the war file (for application server instances) and restart.

This in-place upgrade is described in the next section. It applies to the upgrade from the following version to AEM 5.6.1:

  • CQ 5.2.1
  • CQ 5.3
  • CQ 5.4
  • CQ 5.5
  • AEM 5.6

For the upgrades from the following version to AEM 5.6.1 an in-place upgrade is not available:

  • Communiqué 3
  • Communiqué 4
  • ADEP WEM

For details about these scenarios, see Upgrading From Other Versions of CQ.

Even though the upgrade process has been designed to be as simple as possible, any upgrade of a production environment is a significant task. For this reason, we recommend that you invest time in planning your upgrade throroughly. For guidance on this, see Planning Your Upgrade.

For information about upgrading Social Communities (SoCo) components, see Upgrading CQ Social Communities.

Note

When upgrading, if you have previously deleted geometrixx sites, you wil need to remove them after upgrading. See Removing Geometrixx Sites.

Known Issues for Upgrade to 5.6.1

  • Deployment: A custom context path is reset to / during upgrade process. The path setting from etc/server.xml needs to be restored manually after upgrade.
  • Workflow Models: References to sub-workflows in container steps are not updated and need to be adapted manually after upgrade.
  • Portlet Component: Customers using the Portlet component with Portlet web apps hosted on CQSE need to switch to an Application Server WAR file deployment of CQ.
  • Social Communities: Customers update from versions before 5.6 will need a migration tool which will be made available shortly on Package Share with documentation to follow on docs.day.com.
  • Replication: After the upgrade is complete, replication may not function correctly until an additional restart is performed.

Note

If you point to a Replication agent to a non-existent IP during upgrade: When upgrading an author instance with minimal downtime, it's customary to create a replication agent pointing to a non-existing IP/port. The agent, which is configured "on modification" and "on distribution" collects all changes that happen during the time of the upgrade. The upgrade is on a different server with a clone of the original author instance. When the upgrade has finished, the agent is reconfigured with the correct IP/port of the upgraded instance, pushing all changes to it. When the queue is empty, the original instance can be shut down and the upgraded one brought up.

If the upgraded instance has active replication agents itself (the default agent, plus the additional agent described above), you will getStaleItemStateExceptions/ReplicationExceptions in the log. To avoid these, disable all replication agents on the new instance until the replication from the old one has finished.

Inplace Upgrade from CQ 5.x and AEM 5.6

Preparation

  1. Create a copy of the author and publish instances. For example, with the CRX backup tool.
  2. Extract the backups into a testing environment.
  3. In that environment, make sure that you have at least 2GB of free disk space and sufficient privileges to perform the upgrade.
  4. Start the instances
  5. Disable the replication agents - in order to avoid unnecessary interference with the production environment.
  6. Go to CRX Explorer (e.g., http://localhost:4053/crx/explorer/browser/index.jsp) and delete recursively the following content:
    • /var/upgrade/WorkflowPreserveContentHook
    • /var/upgrade/PreserveContentHook

    Note that it is important to use the delete recursively in CRX Explorer as opposed to simple delete in either CRX Explorer or CRXDE Lite in performing this action, to prevent a long delay during the process.

  7. If you have unneeded archived workflows, these should be removed before upgrade, as upgrading workflows is among the more time-consuming steps in the upgrade process.
  8. Remove custom application code. In some cases custom application code may interfere with the upgrade process. It is therefore recommended to remove custom code before upgrade and re-install the code after upgrade is complete.
  9. Run a consistency check on each instance, and perform the appropriate fixes, if necessary.
  10. Download the AEM installation file appropriate to your case:
    • If you are upgrading a standalone environment, download the quickstart jar file.
    • If you are upgrading an application server environment, download the war file.
  11. Follow the steps appropriate to your environment below.

Caution

Starting with AEM 5.6, some run modes are now treated as installation run modes which can only be set on installation or during the initial upgrade from CQ 5.5 or older to AEM 5.6 or younger.

Irrespective of the upgrade procedure used, make sure that for the installation run modes, the correct run modes are effective when first starting your instances using AEM 5.6.1

Installation run modes can not be changed after the first startup under AEM 5.6.1.

Installation run modes are

  • "author" and "publish"
  • "samplecontent" and "nosamplecontent"

Standalone (Quickstart) Upgrade

If you are using the provided scripts in crx-quickstart/bin/ to run CQ,

  1. Stop each instance
  2. Copy cq-quickstart-5.6.1.jar to the directory containing your crx-quickstart/ directory
  3. run java -jar cq-quickstart-5.6.1.jar -unpack
  4. Note that your existing crx-quickstart/bin/ will be archived below crx-quickstart/archived-versions/. The precise path is given in the output of the above java -jar command. If you have customized any of the scripts in this directory, you can find those changed files in the archive.
  5. Start the instances.
  6. Wait until the upgrade has completed and CQ has fully started.
    If you have not implemented a custom Startup Listener, look for the statement org.apache.sling.startupfilter.disabler BundleEvent STARTED in the error.log
  7. Once the system has restarted successfully, shut it down and restart it again. This triggers the conversion of workflows to the new format (used since 5.5). See New Workflow Model.
  8. Change the replication agents configuration to point to your testing publish environment and test the replication process.

If you are running CQ by launching the quickstart jar file directly,

  1. Stop each instance
  2. Replace the existing cq-quickstart-5.x.x.jar with cq-quickstart-5.6.1.jar 
  3. Start the instances
  4. Wait until the upgrade has completed and CQ has fully started.
    If you have not implemented a custom Startup Listener, look for the statement org.apache.sling.startupfilter.disabler BundleEvent STARTED in the error.log
  5. Once the system has restarted successfully, shut it down and restart it again. This triggers the conversion of workflows to the new format (used since 5.5). See New Workflow Model.
  6. Change the replication agents configuration to point to your testing publish environment and test the replication process.

Application Server Upgrade

  1. Create a Backup of your instance.
  2. Stop both the launchpad and crx web applications using the administration interface of the application server.
  3. Uninstall the launchpad web application.
  4. Uninstall the crx web application.
  5. Stop the application server.
  6. Remove cq-shared-libs-<version>.jar, crx-shared-<version>.jar and jcr-2.0.jar from the app server's lib folder
  7. Remove the crx-quickstart/launchpad/startup folder.
  8. Remove the following properties from crx-quickstart/launchpad/sling.properties file:
    • sling.home
    • sling.installer.dir
    • org.osgi.framework.storage
    • felix.cm.dir
    • sling.jcrinstall.folder.name.regexp
    • org.apache.sling.launcher.system.packages
    • org.osgi.framework.system.packages
    • osgi-core-packages
    • osgi-compendium-services
    • jre-*
  9. Go to the folder crx-quickstart/launchpad/config/org/apache/sling/commons/log
  10. In that folder, edit the LogManager.config file and all files in the LogManager subfolder by replacing
    org.apache.sling.commons.log.file="../logs/error.log"
    with
    org.apache.sling.commons.log.file="logs/error.log"
  11. Make sure that the new AEM web application has the correct run mode in its web.xml (see the general web application deployment instructions for AEM)
  12. Start the application server.
  13. Deploy the AEM web application into the application server. This deployment step is essentially identical to the procedure used when installing a fresh AEM installation in an application server. The procedure specific to each type of application server is described in Installing AEM with an Application Server.

Perform Checks

During the upgrade, monitor crx-quickstart/logs/stdout.log to check that the upgraded instance starts properly. Then:

  • Confirm that you can login to the upgraded instance.
  • Check stdout.log (or crx-quickstart/logs/crx/error.log) to see if there were any errors.
  • Check http://host:port/system/console/bundles to confirm that all bundles were installed.
  • Check http://host:port/system/console/components to confirm that all components have started properly.

Security Checklist

Once the upgrade has been completed, it is very important to follow the security checklist, just as one would in the case of a fresh installation of AEM.

 

Caution

Failure to follow the security checklist after an upgrade may lead to vulnerabilities in the newly upgraded instance.

Troubleshooting

Because AEM is designed to be extensively customized, there maybe situations where you run into problems not anticipated in the generic upgrade procedure. For information on specific problems that may arise and how to deal with them please consult Tips and Troubleshooting.

Upgrading from Other Versions

When upgrading from Communiqué 3 or 4 to AEM, in-place upgrade is not possible. Instead you must migrate your content from your existing instance to a newly installed fresh AEM instance. AEM includes a built in migration tool that you can use to import your old content into your new system. See Upgrading From Communiqué 3 or 4.

When upgrading from ADEP WEM to AEM, an in-place upgrade is also not possible. Instead you must migrate your content from your old ADEP instance to a fresh AEM instance using the export and import of content packages (just as you would in migrating content between two instances of AEM). Information on import and export of packages can be found here: Working with Packages.

Architectural Changes in CQ 5.5, AEM 5.6 and AEM 5.6.1

Versions of CQ before 5.5 were based on a servlet container (CQSE, by default, though others could be used) running with multiple webapps: One for the CRX content repository and one for the OSGi container which itself contained Sling and AEM. The Sling webapp was bound to the root and handled most of the request processing.

With CQ 5.5 and AEM, the OSGi container is positioned at the root and the OSGi HTTP service, backed by Sling acting as the sole request handling end point. The CRX content repository is now just another OSGi service, alongside the various services that comprise the rest of the AEM unctionality. These changes do not affect applications built on top of AEM or Sling.

The new architecture means that the quickstart jar installation of AEM can no longer support other web applications running alongside AEM. However, the war version of AEM is designed to be deployed in an application server, where additional web applications can be deployed alongside it.