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.


Your comments are welcome!
Did you notice a way we could improve the documentation on this page?
Please leave your comments below and we will make the appropriate changes.

COMMENTS

  • By Special Monkey - 9:53 PM on Mar 12, 2013   Reply
    Regarding the following in a 5.4 to 5.6 upgrade :


    "Start the instances.
    The quickstart will detect that there is an older repository version present and will run the upgrade process. This might take a few minutes."


    How does one know when the initial repository upgrade is complete? Is there something to lookout for in the logs?

    By what means should one start the standalone instance with the new jar in place, the default 5.4 start script fails with "invalid option" when using the 5.6 jar. Commenting some of these options out, in serverctl, seems to fix ...?

    5.6 recommends Java 7 but Java 7 as far as I know doesn't work for 5.4, so is it OK to run the upgrade from 5.4 to 5.6 using Java 1.6?
    • By alvawb - 6:51 PM on Mar 19, 2013   Reply
      I have opened an issue to have this clarified in the documentation, particularly the issue about upgrading to Java 7. Did you upgrade the instance to Java 7 after you upgraded the repository to 5.6? Since you've already performed the upgrade and are having trouble, I would suggest that the best course of action would be to contact customer support directly and open a ticket. Alternatively, if you want a quicker answer than I can provide, you may want to post your issue to our AEM dedicated forum at http://forums.adobe.com/community/digital_marketing_suite/cq5.
    • By Special Monkey - 10:34 PM on Mar 15, 2013   Reply
      I realize now logs are created under /approot/sling/logs - I suppose it can be determined by examining these logs that the initial upgrade is done ... to answer my own question perhaps (but what should be looked out for here?). Additionally, on the restart I found nothing new happened, and my 5.4 site was no longer visible within the WCM. The 5.6 new interface was installed, along with all the geometrixx sites, but the "upgrade" to my 5.4 instance did not happen. Any ideas? I will try again and report back if anything changes.

      • By alvawb - 5:02 PM on Mar 19, 2013   Reply
        I am investigating your previous comment and this one. You may want to open a customer support ticket to get your upgrade running properly. I will respond to your previous comments once I have answers.
      • By Sheldon - 12:37 PM on Jun 18, 2013   Reply
        Step 5 on "STANDALONE (QUICKSTART) UPGRADE" for AEM 5.6.1 upgrade is asking you to delete cq-quickstart-5.6.1-standalone.jar which is the quickstart for 5.6.1! It should ask you to rename or delete the old quickstart from 5.6 and below. If I'm new to this upgrade process, following this step will caused problems and confusion.
        • By Anonymous - 12:10 PM on Jun 21, 2013   Reply
          Thanks, the mistake has been fixed!
        • By Special Monkey - 3:51 PM on Jul 11, 2013   Reply
          Is there any clarification re: Java 7? Should upgrades be performed using Java 7 (even though 5.4 doesn't support Java 7), or should we switch to Java 7 post upgrade, performing the upgrade using Java 1.6?

          Additionally, I think it should be clarified that one shouldn't extract the quickstart jar from AEM/aem_x file but rather should rename this file to cq-quickstart-5.6.1.jar.


          Thanks,
          SM



          • By Special Monkey - 4:22 PM on Jul 11, 2013   Reply
            Please clarify at what point Java 7 should be used in the upgrade;

            - during (on initial start w/ new jar)
            - before first restart (before the workflow upgrade)
            - after second restart (only when instance is upgraded)
            • By Guillaume Carlino - 2:00 PM on Jul 12, 2013   Reply
              Hi

              Thanks for your feedback. This is still on our to-do list, but I've raised the priority of your request.
              In the meantime, I would recommend that you contact customer support directly and open a ticket:
              http://helpx.adobe.com/marketing-cloud/contact-support.html

              Hope that helps
              Guillaume
            • By Bill - 7:23 PM on Aug 01, 2013   Reply
              "... It is therefore recommended to remove custom code before upgrade and re-install the code after upgrade is complete.
              9. It is recommended to remove all custom application code from the instance befor
              10. Run a consistency check on each instance, and perform the appropriate fixes, if necessary."

              Someone forgot to finish #9, or that #9 was part of #8...
              • By zumbrunn - 10:16 PM on Aug 04, 2013   Reply
                Thank you Bill, it's fixed!
              • By mohan - 7:04 AM on Aug 28, 2013   Reply
                Is there any patch that we can have for Annotate functionality in 5.6.1??
                • By alvawb - 7:19 PM on Dec 16, 2013   Reply
                  Annotate is available in 5.6.1. Please feel free to open a daycare ticket if that's not the case for your installation (http://helpx.adobe.com/marketing-cloud/contact-support.html).
                • By Anonymous - 2:15 PM on Oct 08, 2013   Reply
                  Step 4 states "If you have changed any of the scripts in crx-quickstart/bin/, they will not be replaced. Instead, the new versions will be copied next to them and you will see a notice of the file name."
                  BUT this is NOT TRUE> Your old scripts are in fact overwritten. So if you have made any changes to the scripts, you better rename them or pull them form backups.
                  • By Anonymous - 1:25 AM on Oct 09, 2013   Reply
                    When I upgraded the unpack of the jar file stated the following:

                    File exists and cannot be overwritten, extracted to start.NEW_20131008_211646_198 instead of /cq/publish/crx-quickstart/bin/start
                    File exists and cannot be overwritten, but unchanged: /cq/publish/crx-quickstart/bin/status
                    File exists and cannot be overwritten, but unchanged: /cq/publish/crx-quickstart/bin/stop

                    ...But the file noted as "start.NEW_20131008_211646_198" does not exist anywhere, and all files were overwritten in the /bin directory even though the messages indicate they could not be overwritten.

                    It would be helpful if messages during installation, as well as the documentation reflected what really is happening.
                    • By docs team - 3:44 PM on Oct 10, 2013   Reply
                      The directions have been corrected to reflect the actual behavior of the upgrade. Thanks for pointing this out.
                    • By Anonymous - 7:19 AM on Oct 23, 2013   Reply
                      Hi , After upgrading to CQ 5.6.1, we are facing a couple of issues:
                      1.) It fails to load the JSON - http://<ip>:<port>/ajax/libs/cq/i18n/dict.en.json in our application. Any idea why it is trying to find .json files under /ajax/

                      2.) JS error: Cannot read property 'PARAM_LIVE_RELATIONSHIP' of undefined in widgets.js.

                      Can you please share some insights.

                      Regards
                      Anshul



                      • By Scott Brodersen - 1:40 PM on Oct 23, 2013   Reply
                        For questions that are specific to your installation, please either post your question to the AEM forum (http://help-forums.adobe.com/content/adobeforums/en/experience-manager-forum/adobe-experience-manager.html) or open a ticket with Daycare support (http://helpx.adobe.com/marketing-cloud/contact-support.html).

                        thank you,
                        Scott
                      • By Anonymous - 12:36 PM on Jan 30, 2014   Reply
                        My question might sound a bit wierd & hypothetical, I was wondering if it is possible for CQ 5.4 and 5.6 to co-exist in a single application?

                        Is it possible to work with multiple launchpad application war in a single ear working with single (or) multiple repository...?

                        Thanks,
                        • By alvawb - 5:38 PM on Feb 07, 2014   Reply
                          Not a weird question at all. I have not heard of anyone doing this and am not sure it's possible. You may want to post this question on our dedicated AEM forum at http://help-forums.adobe.com/content/adobeforums/en/experience-manager-forum/adobe-experience-manager.html

                        ADD A COMMENT

                         

                        In order to post a comment, you need to sign-in.

                        Note: Customers with DayCare user accounts need to create a new account for use on day.com.

                        ***