Upgrading to CQ 5.3

The scope of this section is to provide a guideline for planning and executing CQ 5.3 upgrade projects.

It is recommended to run the upgrade on a copy of the production author (local or separate server) or a dev instance first, following the upgrade procedure described elsewhere on this page. This will help you judge the time the upgrade will take, given your content and hardware, and to determine the final upgrade procedure.

Once you have an upgraded copy, you can start adapting the code base using this instance and when done export the upgraded code base to SVN. After that QA can use this copy to verify functionality of templates and components.

Preparing the upgrade carefully requires to list out areas where the project extended the product. These are risk areas that need explicit "after upgrade" testing. i.e. every extension point needs to be covered by a specific test. Such extension points include custom components, overlays and extensions of foundation components, special selectors, overlayed widgets and so on.

The easiest way is to get this list from the project. If the project did not explicitely list all extension points as recommended in the development checklist, this is a good time to start such a list for the future.

The list will help you to define test cases and ensure that your QA and tests have covered all system functionality that is needed for your project.

In addition to basic functionality testing the following parts need special attention:

• Find selectors and check if they still work.
• Find foundation component overlays and check if they still work.
• 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
• The Table component has been updated in CQ5.3, though the changes will not be automatically applied during an upgrade (customer choice). If the new functionality is required it can be applied manually.
• 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.

The upgrade procedure below can be used as a baseline for your projects upgrade procedure and can be used for the first upgrade attempt. Project specific configuration and installation might require to adapt the procedure for your project.

• Disable replication agents
  • log in as admin and disable all replication agents (author only)
• Run consistency check
  • open install-dir/crx-quickstart/repository/workspaces/crx.default/workspace.xml
  • add following lines to TarPersistenceManager config
    
    <param name="consistencyCheck" value="true"/>
    <param name="consistencyFix" value="true"/>
    <param name="autoOptimizeAt" value="-0"/>
    
    
  • restart instance and wait until it's coming up again
  • open install-dir/crx-quickstart/repository/workspaces/crx.default/workspace.xml
  • reset values to false
    
    <param name="consistencyCheck" value="false"/>
    <param name="consistencyFix" value="false"/>
    
    
  • and remove
    
    <param name="autoOptimizeAt" value="-0"/>
    
    
  • for more details please check:
    • run a consistency check/fix on the persistence manager
    • fix non-repairable errors with the CRX Console (usually those are nodes that have a wrong parent id. use the command 'patch')
    • run a consistency check/fix on the index
      
      
• Reset admin password to default
  
  • for details on changing the admin password please check the security checklist
• Configure for upgrade
  • apply all necessary configuration changes that were found during the code upgrade (eg. remove ACL entries from /libs/collab/blog)
• Run the upgrade
  • stop instance
    
  • replace old quickstart JAR with new CQ 5.3 quickstart JAR (use latest from package share)
  • start instance
  • open install-dir/crx-quickstart/logs/stdout.log and check that upgrade starts properly
  • wait until upgrade is finished (the time it takes depends on your instance size and hardware)
  • check if you can login
  • check stdout.log (or install-dir/crx-quickstart/logs/crx/error.log) if there are any errors
  • check http://host:port/system/console/bundles to see if all bundles are install (CQ WCM Core bundle version should start with 5.3)
  • check http://host:port/system/console/components if all components are started properly
  • if your instance is using LDAP comment login module in install-dir/crx-quickstart/repository/repository.xml to reenable LDAP access and restart it
    
  • install content package containing upgraded code base
  • reset admin passwords to original value (CRX/Sling/CQSE)

The following diagram shows an overview of a sample system architecture which will be used for the upgrade project plan.

The system is distributed across 2 data centers. The author will be upgraded and QA'ed first before the publish instances are upgraded. This allows to focus on one upgrade first and authors can start using it again while the upgrade team is working on the publish instances (but without publishing).

Due to long upgrade times and network latency between the data centers only one publish is upgraded on each coast. After that a copy of the upgraded publish is moved to the other server at the respective data center.

The upgrade of the production system needs careful planning to reduce system downtime and the risk of data loss. Below you find a sample upgrade plan for the described system.

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 installations 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
• The Table component has been updated in CQ5.3, though the changes will not be automatically applied during an upgrade (customer choice). If the new functionality is required it can be applied manually.
• 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/usergenerated will be deleted by the upgrade to CQ 5.3.
  • The upgrade procedure deletes everything under:
    • /content/geometrixx
    • /content/usergenerated
    • /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.
4. Run Consistency checks on your (CRX) instance before starting the upgrade; this procedure details the checks and action points if you encounter any inconsistencies.
5. Download the CQ quickstart jar file from Daycare.
   

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.
     

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

To upgrade from 5.2.1 to 5.3 with the WebSphere 6.1 server, you need to complete the following tasks:

1. Unpack CQ 5.3.
2. Update the CRX and the Launchpad web applications to the CQ 5.3 version.
   
3. Configure the Default JDK.
4. Update the shared libraries of the application server to the CQ 5.3 version.
5. Install the CQ 5.3 content package.

Detailed instructions are provided in the following sections.

Unpack CQ 5.3

Unpacking must be performed from the command line. If you open the jar file directly, you activate the Quickstart installation and activate the server.

1. Open a terminal window.
2. Start the CQ Quickstart jar with the option -unpack by typing, for example:
   java -jar quickstart.jar -unpack
   This creates a folder <cq-unpack-dir>\crx-quickstart containing the files and folders used for installation, without starting the installation.
   

Update the CRX and the Launchpad web applications to the CQ 5.3 version

1. Login to the IBM web console at http://localhost:9060/ibm/console. (Port number 9060 is the default port number.)
   
2. Click Applications, then Enterprise Applications.
3. Stop the CRX web application:
   • Select crx-explorer_crx.war
   • Click Stop.
4. Stop the Launchpad web application:
   • Select crx-launchpad.war
   • Click Stop.
5. Update the CRX web application to the CQ 5.3 version:
   • Select crx-explorer_crx.war
   • Click Update.
   • In the Specify the path to the replacement ear file section, click Browse and choose the crx-explorer_crx.war file of CQ 5.3 located at <cq-unpack-dir>\crx-quickstart\server\webapps\
   • As Context root specify /crx
   • Click Next through all the steps. Click Save at the last step.
6. Update the Launchpad web application to the CQ 5.3 version:
   • Select crx-launchpad.war.
   • Click Update.
   • In the Specify the path to the replacement ear file section, click Browse and choose the crx-launchpad.war file of CQ 5.3 located at <cq-unpack-dir>\crx-quickstart\server\webapps\
   • As Context root specify /launchpad
   • Click Next through all the steps. Click Save at the last step.

Configure the Default JDK

1. Stop the WebSphere server.
2. Within the deployed crx-explorer_crx.war, edit ibm-web-ext.xmi and add the following configuration parameter to specify the JSP engine:   
   <jspAttributes xmi:id="JSPAttribute_1225281520121" name="jdkSourceLevel" value="15"/>    
   The default configuration directory for the web module is as follows:
   <WAS_ROOT>\profiles\profilename\config\cells\cellname\applications\enterpriseappname\ deployments\deployedname\webmodulename\WEB-INF\
   
3. Repeat for crx-launchpad.war. 
   

Update the shared libraries of the application server to the CQ 5.3 version

1. Remove the crx-shared.jar  and the jcr-1.0.jar files from the shared library folder of the WebSphere server.
   
2. Copy the cq-shared-libs-5.3.x.jar file from <cq-install-dir>/crx-quickstart/server/lib/common to the shared library folder of the WebSphere server.
3. Remove everything except the config folder and the sling.properties file from <cq-install-dir>\crx-quickstart\launchpad

Install the CQ 5.3 content package

1. Start the WebSphere server: it starts both the CRX and the Launchpad web applications.
   
2. Stop the Launchpad web application:
   • In the IBM web console at Enterprise Applications, select crx-launchpad.war.
   • Click Stop.
3. Install the CQ 5.3 content package:
   • Open http://localhost:9080/crx or the location of your CRX installation.
     
   • Open the Package Manager.
   • Upload the CQ 5.3 content package (cq-content-5.3.jar file) from the <cq-unpack-dir>\crx-quickstart\repository\install folder.
   • Install the package.
4. Remove the felix folder and the startup folder located at <cq-install-dir>\crx-quickstart\launchpad
   
5. Start the Launchpad web application:
   • In the IBM web console at Enterprise Applications, select crx-launchpad.war.
   • Click Start.

To upgrade from 5.2.1 to 5.3 with the MySQL server, you need to complete the following tasks:

1. Unpack CQ 5.3.
2. Replace the quickstart.jar from your existing instance with the new quickstart.jar from CQ 5.3.
3. Edit the repository-template.xml file and copy it into crx-explorer_crx.war and copy the MySQL driver library. 
4. Start the instance.

Detailed instructions are provided in the following sections.

Unpack CQ 5.3

Unpacking must be performed from the command line. If you open the jar file directly, you activate the Quickstart installation and activate the server.

1. Open a terminal window.
2. Start the CQ Quickstart jar with the option -unpack by typing, for example:
   java -jar quickstart.jar -unpack
   This creates a folder <cq-unpack-dir>\crx-quickstart containing the files and folders used for installation, without starting the installation.
   

Update the .jar file to the CQ 5.3 version, edit the repository-template.xml file, and copy the MySQL driver library.

1. Stop the CQ 5.2.1 web application.
2. Replace the .jar file of the CQ 5.2.1 web application with the CQ 5.3 version.
3. Edit the repository-template.xml file:
   1. Go to ../crx-quickstart/server/webapps and extract repository-template.xml from the crx-explorer_crx.war file.
      
   2. Edit the repository-template.xml file as described in the repository-template.xml file code snippets that follow.
      
   3. Copy the updated repository-template.xml file into crx-explorer_crx.war.
4. Copy the MySQL driver library to ../crx-quickstart/server/lib/common.
5. Start CQ 5.3 instance using start script in ../crx-quickstart/server.

The following code snippets in the repository-template.xml file need to be modified when upgrading CQ 5.2.1 to 5.3 with MySQL:

Datastore:

Workspace persistence manager:

Versioning persistence manager:

Cluster journal:

To upgrade from 5.2.1 to 5.3 with the WebLogic 10.3 server, you need to complete the following tasks:

1. Unpack CQ 5.3.
2. Update the .war files of the CRX and the Launchpad web applications to the CQ 5.3 version.
   
3. Update the shared libraries of the application server to the CQ 5.3 version.
4. Update the CRX and the Launchpad web applications to the CQ 5.3 version.
5. Install the CQ 5.3 content package.

Detailed instructions are provided in the following sections.

Unpack CQ 5.3

Unpacking must be performed from the command line. If you open the jar file directly, you activate the Quickstart installation and activate the server.

1. Open a terminal window.
2. Start the CQ Quickstart jar with the option -unpack by typing, for example:
   java -jar quickstart.jar -unpack
   This creates a folder <cq-unpack-dir>\crx-quickstart containing the files and folders used for installation, without starting the installation.
   

Update the .war files of the CRX and the Launchpad web applications to the CQ 5.3 version.

1. Stop the CRX and the Launchpad web applications:
   • Login to the Administration Console, for example http://localhost:7001/console
   • Click Deployments in the Domain Structure (in the left side).
   • Select the CRX web application and click Stop.
   • Select the Launchpad web application and click Stop.
2. Stop the WebLogic server.
3. Update the .war file of the CRX web application to the CQ 5.3 version:
   • Remove the crx-explorer_crx.war file from the $MyDomain\packages\crx folder.
     
   • Copy the crx-explorer_crx.war file from the <cq-unpack-dir>\crx-quickstart\server\webapps folder to the $MyDomain\packages\crx folder.
     
4. Update the .war file of the Launchpad web application to the CQ 5.3 version:
   • Remove the crx-launchpad.war file from the $MyDomain\packages\launchpad folder.
     
   • Copy the crx-launchpad.war file from the <cq-unpack-dir>\crx-quickstart\server\webapps folder to the $MyDomain\packages\launchpad folder.
     

Update the shared libraries of the application server to the CQ 5.3 version

1. Remove the crx-shared.jar  and the jcr-1.0.jar files from the shared library folder of the WebLogic server at $MyDomain\lib
   
2. Copy the cq-shared-libs-5.3.x.jar file from <cq-unpack-dir>\crx-quickstart\server\lib\common to the shared library folder of the WebLogic server at $MyDomain\lib
   

Update the CRX and the Launchpad web applications to the CQ 5.3 version

1. Start the WebLogic server.
2. Login to the Administration Console, for example http://localhost:7001/console
3. Click Deployments in the Domain Structure (in the left side).
4. Update the CRX web application:
   • Select the CRX web application and click Update.
   • Select Redeploy this application using the following deployment files. It should show  the correct paths by default.
   • Click Next, then Finish.
5. Update the Launchpad web application:
   • Select the Launchpad web application and click Update.
   • Select Redeploy this application using the following deployment files. It should show  the correct paths by default.
   • Click Next, then Finish.

Install the CQ 5.3 content package

1. Stop the Launchpad web application:
   • In the Administration Console at Deployments, select crx-launchpad.
   • Click Stop.
2. Install the CQ 5.3 content package:
   • Open http://localhost:7001/crx or the location of your CRX installation.
     
   • Open the Package Manager.
   • Upload the CQ 5.3 content package (cq-content-5.3.jar file) from the <cq-unpack-dir>\crx-quickstart\repository\install folder.
   • Install the package.
3. In the <cq-install-dir>\crx-quickstart\launchpad directory, remove:
   • the felix folder,
   • the startup folder, 
   • the org.apache.sling.launchpad.base.jar file
     
4. Start the Launchpad web application:
   • In the Administration Console at Deployments, select crx-launchpad.
     
   • Click Start.

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.
4. Review Changes to the Table component if required.
5. There are various items (mainly for backup reasons) that can be reviewed, and where appropriate, cleaned up after a successful upgrade to CQ5.3:
   • repository:
     • /home/groups-<xxx>
     • /home/users-<xxx>
   • file system:
     • crx-quickstart/server/*.NEW_<xxx>
     • crx-quickstart/archived-versions
   • miscellaneous:
     • /tmp/asset*
     • crx-quickstart/repository/shared/replication/durbo
       
6. The redundant workspaces can also be deleted:
   • crx-quickstart/repository/workspaces/crx.system
   • crx-quickstart/repository/shared/workspaces/crx.system
   crx-system is no longer obligatory. User data is now stored in the appropriate workspace, and other system-wide information is available without the need to initialize an additional workspace.
   

In CQ 5.3 the table component (foundation) has been updated. The updated component provides new formatting possibilities, with features such as merging, splitting and the application of styles to individual cells.

This has been achieved by adding a widget that uses an xtype of tableedit2 (the original widget used the xtype of tableedit).

The table component (foundation - /libs/foundation/components/table) is automatically updated during the upgrade so you should review whether you:

• want to revert the foundation table component to the original functionality
• need to update any customized components to the new functionality

Reverting to 5.2 Table Functionality (tableedit)

During an upgrade the changes are automatically applied to the table component (foundation). However, if for any reason you prefer to stay with the original functionality you can easily revert:

Updating Customized Components to 5.3 Table Functionality (tableedit2)

During an upgrade the changes to the table component (foundation) are automatically applied. However, if you have based any customized components on tableedit (or use the tableedit widget anywhere in the application) and now want to use the new functionality, you must update these manually:

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).

The following section details known issues that may be encountered when upgrading from CQ 5.2.0 and/or CQ 5.2.1.

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 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

When upgrading from 5.2 to 5.3 using the quick-start replacement method, after
upgrading, the blog content is not automatically migrated.

When upgrading from 5.2 there can be problems due to workspace inconsistencies. You can either run a test upgrade to see if this will be an issue, or run the consistency checks as preventive action.

If you run a test upgrade that fails due to workspace inconsistencies you will see entries similar to the following in crx-quickstart/logs/crx/error.log:

To detect and correct any workspace inconsistencies:

Where should I look for upgrade errors?

The crx/error.log will contain all upgrade related log messages. During the upgrade it will show WARN messages, but those are caused by node type changes and documented here.

Usually any stacktrace that you see there is an indication that the upgrade did not run successfully.

The currently the know exception to this rule is:

*WARN * SearchIndex: Unable to get aggregate root for 5cb50678-ff3e-d8c2-0eec-4e9477978603 (SearchIndex.java, line 1446) javax.jcr.RepositoryException: failed to resolve name of 5cb50678-ff3e-d8c2-0eec-4e9477978603
    at org.apache.jackrabbit.core.HierarchyManagerImpl.getName(HierarchyManagerImp l.java:467)
    at org.apache.jackrabbit.core.HierarchyManagerImpl.getName(HierarchyManagerImp l.java:427)
    at org.apache.jackrabbit.core.query.lucene.AggregateRuleImpl$AbstractInclude.m atches(AggregateRuleImpl.java:347)
[...]

This is non-critical and does not affect operations.

Related to the above issue are ERROR messages logged to crx/error.log,
which are also non-critical:

*ERROR* VirtualNodeTypeStateManager: Unable to index removed nodetype: javax.jcr.ItemNotFoundException (VirtualNodeTypeStateManager.java, line 194)
*ERROR* VirtualNodeTypeStateManager: Unable to index removed nodetype: javax.jcr.ItemNotFoundException (VirtualNodeTypeStateManager.java, line 194)

If the log contains other ERROR messages, then this might indicate that the upgrade failed or was done only partially.

Upgrade failed due to workspace inconsistencies. What can I do?

When the crx/error.log contains stacktraces like the following, then the workspace is inconsistent and the upgrade failed:

Caused by: org.apache.jackrabbit.core.state.ItemStateException: Trying to add a non-existing child node: e4469e5a-4892-4760-acd6-3a3e8f120d4e
    at org.apache.jackrabbit.core.state.SharedItemStateManager$Update.checkAddedCh ildNode(SharedItemStateManager.java:995)
    at org.apache.jackrabbit.core.state.SharedItemStateManager$Update.checkAddedCh ildNodes(SharedItemStateManager.java:978)
    at org.apache.jackrabbit.core.state.SharedItemStateManager$Update.begin(Shared ItemStateManager.java:577)

This is a check that was added in CRX2.0 that prevents that corrupt nodes are persisted. However, it will also prevent persisting changes to nodes that were already corrupt on disk.

It can be fixed by running consistency checks before the upgrade.

Content package install fails. What can I do?

nt:folder nodes with access controls that were added after the installation of CQ 5.2.1 may cause problems on upgrade to 5.3. This does not happen for all nt:folder nodes with ACLs, but only for some. E.g. a customer added ACLs to /libs/collab, which causes the problem.

The crx/error.log will log an ERROR like this:

12.02.2010 14:08:54 *ERROR* Importer: Error while committing /libs/collab: javax.jcr.nodetype.ConstraintViolationException: Unable to perform operation.  Node is protected. (Importer.java, line 715)

Remove those ACL entries to make the content package install work.

Re-indexing fails with OOME. What can I do?

Depending on the number of cores, JVM heap settings and content stored, it may happen that re-indexing a workspace in CQ 5.3 fails.

Specifically PDF files stored in content may require significant amount of heap memory when the workspace is re-indexed. Larger PDF files are processed in a number of background threads, which depends on the number of cores available. Modern hardware easily has +8 cores and supporting twice as many threads, which means a CQ instance could setup 32 threads for PDF text extraction. In some cases this will lead to OOME when all threads are busy with text extraction.

This can be solved by starting the JVM process with affinity to fewer cores.

After upgrade login fails with customized login-page. What can I do?

Adjust the sling:resourceType (cq/core/components/login) and move all the static-files (background image, css and js) below /apps/wcm/auth/content/login. These used to be on the same level than the actual login content 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.

• 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.