Upgrading to CQ 5.3

For the upgrade procedure from CQ 5.2.1 to CQ 5.3, there are two options available:

• Upgrading by installing a content package from Package Share
• Upgrading by replacing the quickstart jar file

When upgrading directly from CQ 5.2.0 to CQ 5.3, replacing the quickstart jar file is the only available procedure.

Please read the following points and take action where necessary:

• These instructions apply to CQ 5.2 installation made using Quickstart. If your installation was not made using Quickstart, such as installations with a third party application server, the following instructions need to be adjusted accordingly. 
• You must test the operation of the upgraded website; highly customized items may need to be upgraded separately.
• The security model has changed between CRX 1.4 and CRX 2.0; therefore between CQ 5.2 and CQ 5.3. The upgrade process handles these changes, but you should test the access privileges within your CQ instance after completion. See Security Model Changes if you should have any specific questions or issues, regarding how access control rights are evaluated, after migration.
• Check for changes to the APIs that might affect your project and its operation.
• If OSGi bundles and configurations have been setup directly from the OSGi console (as opposed to storing them in the JCR repository) the configuration should be saved before the upgrade.
  This is done by saving the output of /system/console/config
• Be aware that certain default content is impacted by the upgrade:
  • Default content under /etc is replaced by the upgrade.
    If you need this content then please save the original content tree (for example, as etc_52) before the upgrade. After the upgrade is complete you can re-insert any differences manually.
  • Any changes that you have made to the repository folders containing CQ 5.2 software (/libs and others) might be lost after this upgrade.
  • Content packages delete everything under the path(s) that they impact. Therefore, content created under /content/geometrixx will be deleted by the upgrade to CQ 5.3.
  • The upgrade procedure deletes everything under:
    • /content/geometrixx
    • /apps/geometrixx
    • /etc/designs/geometrixx
    • /libs/

All preparation steps must be checked to ensure a smooth upgrade:

1. Ensure you have a full backup of your CQ 5.2 instance.

2. Ensure that you have at least 2GB of free diskspace.

3. The system account you are using must have sufficient privileges to replace the Quickstart jar file.

Updating your CQ 5.2.1 instance to a CQ 5.3 instance by installing a content package from Package Share is performed by downloading the CQ 5.3 upgrade package from Package Share and installing it on the existing CQ 5.2.1 instance, which requires you to first install another package that enables the package based upgrade mechanisms in the Package Manager. This procedure doesn't work for a CQ 5.2.0 instance.

This upgrade procedure requires the following steps:

1. Please verify that bundles are running as intended and that the WCM welcome page works as expected.
2. Install the required hotfix cq-packaging-5.2.14 in order to enable Package Share based upgrading.
3. Before going further, please verify that all bundles are still running and that the WCM welcome page works as expected. Installing the hotfix on a fresh 5.2.1 installation may cause a problem with stopped and non-startable bundles. If you see this behavior you can
   • delete the crx-quickstart/launchpad and restart
     Warning: this step would remove bundles and delete configurations which may have been installed and configured manually using the OSGi console on your existing CQ instance.
     
   • apply hotfix cq-5.2.1-hotfix-23751.zip or manually upgrade the bundles org.apache.sling.osgi.installer and org.apache.sling.jcr.jcrinstall as which are contained in the before mentioned hotfix
4. If custom access controls have been specified on the /libs/collab node, that access control should be removed prior to the upgrade.
5. Install the 5.3 upgrade content package from Package Share at day/cq521/update/cq-upgrade-5.3.0.
6. Restart CQ twice
   • First restart renames the cq jar file to something like cq.jar.UPGRADED_20100120_172841_333 where the last part is the timestamp, and replaces it with the jar extracted from the upgrade package. On Windows platforms there will two of such files after the upgrade.
     
   • Second restart executes the actual 5.3 upgrade and restores the original file name of the quickstart jar file. Your original name of the jar file is restored because it may contain information like port number, author/publish mode, etc. If your quickstart jar filename contains the version number, make sure you rename it to reflect the change from 5.2 to 5.3 in order to avoid confusion.
     

• Stop your CQ 5.2.1 or CQ 5.2.0 instance.
  
• Replace the quickstart.jar from your existing instance with the new quickstart.jar from CQ 5.3
  
• Restart using the new quickstart.jar. This will upgrade the existing instance to 5.3.
  

The following tasks should be performed after the upgrade:

1. Reinstall any customized OSGi bundles (if you had manually installed them before).
2. Restore any customized configurations from the Apache Felix Console:
   • Mail Service
   • Day Commons GFX Font Helper
   • SSO Authentication Handler
   • Apache Sling Resource Resolver
3. Check for changes to the APIs that might affect your project and its operation.
   

The resulting system is identical to a fresh CQ 5.3 installation, with the user's content preserved (assuming it was not stored in any repository folders that contained the CQ 5.2 software).

During the upgrade CRX will log warnings about unknown node types and that nt:unstructured is used instead:

This is the expected behaviour as CRX 2.0 has different security nodetypes and migrates the old security content to the new structure.

Upgrading to 5.3 will remove the groups surfer and uploader as neither group is needed anymore. Membership of the anonymous user in either of the groups (uploader on an author instance or surfer on a publish instance) is no longer necessary either as permissions are now governed through the everyone group. Every user is implicitly a member of the everyone group. Additional permissions that have been set for the surfer or uploader group after the installation of 5.2.1 must be re-applied manually to the everyone group after the upgrade.

Where a custom login-page at /apps/wcm/auth/content/login is used, it needs to be adapted as follows:

• Change the sling:resourceType from wcm/auth/components/login to cq/core/components/login
• move all the static-files (background image, css and js) below the /apps/wcm/auth/content/login node

Please read the following points and take action where necessary:

• This upgrade procedure only works if the CQ 5.1 installation was performed with Quickstart. As opposed to installation with a third party application server.

• You must test the operation of the upgraded website; highly customized items may need to be upgraded separately.

• Beginning with CQ 5.2 the Text Components add a HTML paragraph tag around the text.

  Prior versions did not always do that. Adding the paragraph tag might cause visual differences.

  Make advance tests (edit a test object) to confirm whether this occurs with your installation. If necessary adapt the CSS selector, and note the changes necessary after the upgrade.

• Check whether you have any extremely large character strings in your repository.

  See for further information.

• If OSGi bundles and configurations have been setup directly from the OSGi console (as opposed to storing them in the JCR repository) the configuration should be saved before the upgrade. This is done by:

  • saving the output of /system/console/config

  and

  • saving a copy of the crx-quickstart/launchpad folder

  As the crx-quickstart/launchpad folder is deleted before the upgrade, then the bundles and configurations must be restored manually after the upgrade,

• Be aware that certain default content is impacted by the upgrade:

  • Default content under /etc is replaced by the upgrade.

    If you need this content then please save the original content tree (for example, as etc_51) before the upgrade. After the upgrade is complete you can re-insert any differences manually.

  • Any changes that you have made to the repository folders containing CQ 5.1 software (/libs and others) might be lost after this upgrade.

  • Content packages delete everything under the path(s) that they impact. Therefore, content created under /content/geometrixx will be deleted by the upgrade to CQ 5.2.

  • The upgrade procedure deletes everything under:

    • /content/geometrixx

    • /apps/geometrixx

    • /etc/designs/geometrixx

    • /libs/

• The cq-security-content package is not reinstalled when upgrading, the old version is kept.

  You must manually update the permissions after the upgrade. You must make the group contributor a member of the group uploader.

• Replication configuration settings are reset during the update. You need to reconfigure these after the upgrade, using the new Replication configuration under Tools.

• The default workflows are overwritten during the upgrade, so any customizations are lost. Please take a copy of these if required.

All preparation steps must be checked to ensure a smooth upgrade:

1. Ensure you have a full backup of your CQ 5.1 instance.

2. Ensure that the CQ 5.1 installation was made using Quickstart.

3. Ensure that you have at least 2GB of free diskspace.

4. Ensure that the system account you are using has sufficient privileges to replace the jar file.

5. Ensure that the crx-quickstart/repository folder that contains your repository data is binary compatible between the CQ 5.1 and 5.2 versions.

   Ensure that no changes (hotfixes or customizations) have been applied to the repository folder that make it incompatible with the 5.2 version that is about to be installed.

   If you are in doubt please check with Day.

6. Request the cleanupMessage.jsp script from Day.

Updating your CQ 5.1 instance to a CQ 5.2 instance requires the following steps:

1. Delete the crx-quickstart/launchpad folder.

2. Run the cleanupMessage script:

   1. Copy the cleanupMessage.jsp file to your author environment:

      <cq-installation-dir>/crx-quickstart/server/runtime/0/_crx/config/cleanupMessage.jsp

      Adapt the path as necessary.

   2. Start your CQ 5.1 instance, then navigate to your CRX console, for example:

      http://localhost:4502/crx (adapt as necessary).

   3. Log in as admin to the workspace where CQ is installed; for example crx.default.

   4. Open the script at:

      http://localhost:4502/crx/config/cleanupMessage.jsp (adapt as necessary).

   5. Only the following properties are changed:

      • with the name message under the specified node

      • those that are longer than the specified size

      The default settings should be correct in all cases.

   6. Start the script using 'clean'.

   7. The output is formed of the nodes that contain a message property.

      The prefix cleaned: means the text was truncated, while ignored: means the text was short and therefore unchanged.

   After the script is run, you may reduce the repository size using Tar PM Optimization.

3. Stop your CQ 5.1 instance.

4. Copy the new jar file to the location of the currently installed jar file:

   <cq-installation-dir>/

   If you had changed the name of your CQ 5.1 jar file, then rename the CQ 5.2 jar file to that of the existing file.

   For example, if it had been renamed for an author environment:

   <cq-installation-dir>/cq-author-4502.jar

   Or a corresponding publish environment:

   <cq-installation-dir>/cq-publish-4503.jar

5. Start CQ 5.2; in the same manner as with your CQ 5.1 instance, by a double-click on the jar file, or from the command line.

   This step will take longer than a normal startup as the new 5.2 content packages have to be installed.

6. Restart CQ 5.2. The upgrade will now be complete.

The structure of digital assets has changed between CQ 5.1 and CQ 5.2. For this reason a wizard is included to automate the process of moving the assets to the new structure:

1. Ensure that you have a backup of your newly upgraded repository.

2. Start your newly upgraded CQ 5.2 instance.

3. Navigate to:

   http://localhost:4502/libs/dam/migrate.html

   

4. Click Start migration. A status message will be shown upon completion:

   

   After the upgrade script has finished it might take some time until all assets reappear for use, as they are being processed in the background. You can monitor stdout.log to see when everything has been finished.

   The upgrade removes the replication state on the assets.

The following tasks should be performed after the upgrade:

1. The CQ 5.1 jar file is not needed after the upgrade and if still present, should be removed from the installation folder to avoid confusion.

2. Reinstall any customized OSGi bundles (if you had manually installed them before).

3. Restore any customized configurations you had made on the file system:

   • /server/runtime/0/_crx/WEB-INF/repository.xml; for example, search engine settings.

   • /server/etc/; for example, LDAP configurations.

4. Restore any customized configurations from the Apache Felix Console:

   • Mail Service

   • Day Commons GFX Font Helper

   • SSO Authentication Handler

   • Apache Sling Resource Resolver

     CQ 5.2 adds a new default rule /content/-/ that you might want to remove.

      

5. Restore any customized configurations in CRX:

   • URL to tracker.js: /libs/wcm/config.publish/com.day.cq.wcm.core.stats.PageViewStatistics

6. Reconfigure the replication configuration settings, using the new Replication configuration under Tools.

7. The cq-security-content package is not reinstalled when upgrading, the old version is kept.

   You must manually update the permissions after the upgrade, by making the group contributor a member of the group uploader.

8. Check all forms on the site. If you had used the custom form action you need to change the dialog to fit the new structure.

9. Beginning with CQ 5.2 the Text Components add a HTML paragraph tag around the text.

   Prior versions did not do always do that. Adding the paragraph tag might cause visual differences. If necessary adapt the CSS selector - as according to your tests in Important information to read before starting the upgrade.

The resulting system is identical to a fresh CQ 5.2 installation, with the user's content preserved (assuming it was not stored in any repository folders that contained the CQ 5.1 software).

An Upgrade enables the automated, or partially automated, conversion of an existing instance, of either Communiqué 3 or 4, to CQ5.

Therefore Day has provided a Upgrade Tool for existing customers. This provides a straight-forward, time-efficient upgrade. This transfers the basic elements from Communiqué 3 or 4; you can then extend these to cater for new functionality available in CQ5:

The automatic upgrade can include different parts of the instance, including:

• Content

• Designs

• Components

• Templates

• Version History

• Audit Log

• Log files 

• CFC Dialogs

• Workflows

• MSM

Highly customized items might need to be upgraded separately.

• The URL to your existing Communiqué 3 or 4 installation.

• A fresh installation of CQ5; as installed without content or customization.

After upgrading you will have an instance that contains content, design, and so on (as above). The user can start to edit content on this new CQ 5 instance.

Content Pages   

• Upgrade of a page will include the versioning history and operates as follows:
• Create the CQ 5 page from the oldest version in the version history.
• For each version in the version history:
• Check in the page node to create a version.
• Check out the page node for update.
• Update to the version in the history.

The resulting CQ 5 page holds the most recent version (HEAD) and is checked out.

Components and Templates

Upgrading components consists of multiple parts:

• Descriptor - the component descriptor (such as component name) is upgraded into the node data of the new component.

• display.any - this is upgraded into the display descriptor of the new node structure.

• Script(s) - the component scripts are upgraded to the new location using the new naming convention.

To ease the upgrade, a limited ContentBus API is available to components through a JCR Adapter.

Audit Log

• Importing the Communiqué 4 Audit Log is a straight import of the file entries into a node structure.

Component coded applications

• Will be upgraded, with the exception of objects of the type CFC.Tools.

Media Library

• /etc/medialib will be moved to /content/dam.