Upgrading to CQ 5.5

This section describes the procedure and troubleshooting steps for upgrading to CQ 5.5 from CQ 5.2.1, 5.3 or 5.4.

Before getting started it is recommended that you plan out the process clearly. Consult the Planning Your Upgrade section for information.

CQ 5.5 supports upgrade paths from 5.2.1, 5.3 and 5.4. Most upgrade steps and troubleshooting tips relate to all cases, but some may be relevant only to an upgrade from a particular version.

In this section each step or troubleshooting tip is marked to indicate which upgrade path the issue applies to:

ALL: Applies to upgrades from all of the supported versions, 5.2.1, 5.3 or 5.4, to 5.5.

5.2.1: Applies only to upgrades from 5.2.1 to 5.5.

5.2.1, 5.3: Applies only to upgrades from 5.2.1 or 5.3 to 5.5.

5.3: Applies only to upgrades from 5.3 to 5.5.

In all cases the issues listed apply equally to both quickstart and application server installations.

ALL

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 and disable the replication agents - in order to avoid unnecessary interference with the production environment.
5. Run a consistency check on each instance, and perform the appropriate fixes, if necessary.
   
6. Download the CQ 5.5 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.
     
7. Follow the steps appropriate to your environment below.

ALL

1. Stop each instance and replace the existing quickstart jar file with the 5.5 quickstart jar file.
   
2. Start the instances.
   
3. The quickstart will detect that there is an older repository version present and will run the upgrade process. This might take a few minutes.
   
4. Once the system has restarted successfully, shut it down and restart it again. This triggers the conversion of workflows to the new 5.5 format. See New Workflow Model.
5. Change the replication agents configuration to point to your testing publish environment and test the replication process.

ALL

If you use CQ as web application within a third party application server, follow the instructions in Upgrading CQ 5.5 with Application Servers.

ALL

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.

ALL

If you experience problems with the procedure above, restart to the process and do the following:

1. Clear all workflow processes including completed and aborted processes.
2. Perform Data store garbage collection.
3. Perform TarPM optimization.
4. Perform TarPM index merge.
5. Stop the CQ instance.
6. Delete all the logs: 
   1. crx-quickstart/logs
   2. crx-quickstart/server/logs
   3. crx-quickstart/launchpad/logs
   4. Any *.hprof files
   5. Any *.dump files
   6. crx-quickstart/server/tmp/0/_crxde (if it exists)
   7. crx-quickstart/server/webapps/crx-de_crxde.war
7. Start CQ and wait for "Server ready" message from server.log.
8. Make sure all bundles are started.
9. Using CRXDE Lite, open file /libs/sling/servlet/errorhandler/404.jsp.
10. Change all instances of variable "bindings" to "sbindings".
11. Click "Save All".
12. Stop CQ.
13. Proceed with upgrade as described above.

ALL

In CQ 5.5 the admin password has to be changed only once in the repository.

1. Go to /crx/explorer/index.jsp
2. Use the "User Administration" and browse to the admin user
3. Change the password and save

It's no longer necessary to change the admin password for CQSE and in the Felix Console.

ALL

Change the file name of the quickstart to contain the port number.

New in CQ 5.5 it requires a prefix -p before the port number: Example: cq-quickstart-5.5.0-publish-p4503.jar to start the server as publish on port 4503.

ALL

Follow these instructions for a clean installation:

1. Use the -unpack option to extract the CQ5 installation without starting the server:
   java -server -jar cq-quickstart-5.5.0.jar -unpack
2. In the extract folders there is a crx-quickstart/bin folder that contains a start and stop script for Windows or Unix based systems.
3. Edit the start (on Unix) or start.bat (Windows) to change the runmode, port number and java memory settings.

ALL

CQ 5.5 is also available as single WAR file for Web Application Server deployments.

The WAR file is preconfigured to start as author instance. Follow these steps to change the runmode to publish:

1. Unpack the web.xml from the war file
2. Edit web.xml and change run mode parameter to publish
3. Repack web.xml into the war file
4. Deploy the war file in the web application server container

ALL

To access and modify DAM assets via WebDAV, use the path /content/dam to locate the assets in Windows Explorer or Mac Finder.

Versions prior CQ 5.5 had the DAM assets located in /var/dam. This folder is no longer used.

ALL

Problem: After the upgrade of site to CQ 5.5, pages are only partly loaded or look broken when accessed over the publish server.

Solution: By default, CQ 5.5 prevents read access for anonymous users to certain locations in the repository on a publish server. If the site requests resources in these locations, they will not be loaded and result in a 404. We recommend moving these resources to publicly available locations in the repository.

The anonymous web site visitor has no access to following paths in CQ 5.5:

• /apps
• /libs
• /home

It is recommended to place publicly accessible resources in:

• /content
• /etc/designs

ALL

Custom authentication handlers/LoginModule are deployed as OSGi fragment bundles in CQ 5.5. This is due to changes in the way the CRX Content Repository is deployed.

• Wrap the LoginModule into a fragment bundle
• Use the Fragment-Host: com.day.crx.sling.server
• Bundle should have StartLevel 15
• The bundle must be present at startup time in order to work, so you have to restart the CQ instance after uploading it.

ALL

If you are upgrading a CQ installation inside an application server, the server configuration will define the context root used for the CQ application, just as with any other web application.

If you are upgrading a quickstart installation, changes between 5.4 and 5.5 will mean that any custom context root you may have defined in your former installation will be lost on upgrade, and revert to the default, which is "/".

In most cases, a standalone quickstart installation will not be configured with a context root other than "/". However, in some cases a custom context is required and will have been configure in your previous installation. In such cases the context root must be manually re-configured after the upgrade to 5.5.

To do this, open the file

    crx-quickstart/conf/sling.properties

Then, add the line

    org.apache.felix.http.context_path=<path>

where <path> is the context path you want. After saving the sling.properties file, restart the CQ instance.

If you set

    org.apache.felix.http.context_path=/cq5/

then to get the homepage of the example geometrixx outdoors website you would request

    http://localhost:4502/cq5/content/geometrixx-outdoors/en.html

instead of the usual

    http://localhost:4502/content/geometrixx-outdoors/en.html

ALL

As of CQ 5.5 the internal representation of workflows has been changed. In order to ensure that all old workflow definitions are properly converted to the new model, the system must be shut down and restarted again, after the upgrade has finished.

ALL

In CQ 5.5, all start, stop and status scripts are found in the directory

    crx-quickstart/bin/

This differs from previous versions of CQ where these scripts were found in

    crx-quickstart/server/

(which no longer exists in a fresh 5.5 installation)

On upgrade to 5.5, the new scripts are installed in crx-quickstart/bin/ just as they would be in a fresh installation, but the server directory from the previous installation is kept intact and untouched.

Nevertheless, it is highly recommended that the old scripts not be used anymore. They are preserved on upgrade solely to facilitate transfer of any specifc settings and changes that may have been made in the earlier installation to the new scripts. Note also that in 5.5 new scripts have been provided and old ones removed.

Consequently, any custom written scripts that rely on the old CQ scripts must be adjusted.

In addition, support for Windows services is now provided by the script

    crx-quickstart/opt/helpers/start-service.bat

ALL

When upgrading from any version to 5.5, if a non-standard repository.xml location has been specified in the old WEB-INF/web.xml or in a bootstrap.properties file, the repository.xml must be moved to crx-quickstart/repository/repository.xml before upgrading.

ALL

If you have a customized 404 page in /apps/sling/servlet/errorhandler/404.jsp and use a variable called bindings, replace it with a different name (e.g. bnd). This avoids a compile error.

ALL

CQ applications are built around the Sling framework, an important aspect of which is the URL resolution mechanism. In cases where content can be rendered in more than one way, applications will use customized selectors within the URL to govern which script is called to do the rendering (see URL Decomposition). The correct functioning of these selectors is one area that can be affected by the upgrade process, because changes in content structure between versions of CQ may cause the selector mapping to break. For this reason, it is important to make note of the custom selectors used in your application and ensure that they function correctly after the upgrade.

ALL

If your application uses components that overlay any built-in CQ foundation components (those found in /libs/foundation/components/) it is important to note these and test each one after the upgrade to ensure that it still works correctly. See Components for more details.

ALL

If you have installed and configured any OSGi bundles using the Apache Felix OSGi console (as opposed to storing them in the JCR repository), then the Felix configuration should be saved before the upgrade. This is done by saving the contents of /system/console/config.

ALL

The upgrade procedure deletes everything under the following repository folders:

• /content/geometrixx
• /content/usergenerated
• /apps/geometrixx
• /etc/designs/geometrixx
• /libs/

Consequently, any customizations located in these folders or any of their subfolders must be saved before the upgrade procedure is performed.

Note that the above are repository folders visible through CQDE Lite and CQDE, not file directories visible through the host OS.

To preserve content at these locations you must export that content to a content package and then import it back into the upgraded system. This is done through the Package Manager.

ALL

In most cases, a warning that includes a stacktrace indicates that the upgrade did not complete successfully.

Currently, the only known exception to this rule is the following stacktrace:

This is non-critical and does not affect operations.

Related to the above issue are the following error messages that may also be logged to crx-quickstart/logs/error.log, which are also non-critical:

If the log contains other error messages, apart from these, this may indicate that the upgrade failed or was only partially completed.

ALL

Errors such as the following indicate that the the upgrade process failed due to an workspace storage inconsistency:

To avoid these problems, it is recommended that you always perform a consistency check before proceeding with the upgrade. For details on how to perform the check and how to remedy any inconsistencies found, see Consistency Check.

5.2.1

In cases where a 5.2.1 installation has custom users and/or groups, direct upgrade to 5.5 will cause those users and groups to be lost. In that case these users and groups would have to be re-entered manually in the newly upgraded instance. If this is feasible, then a direct upgrade to 5.5 and subsequent re-entry of users and groups is the recommended course.

However, if preserving the exisiting users and groups is a priority (if, for example you have a very large nukmber of them, too many to re-enter manually) the 5.2.1 instance must be upgraded to either 5.3 or 5.4 after which the normal upgrade to 5.5 can be performed. See

• Upgrading from CQ 5.2 to CQ 5.3
• Upgrading from CQ 5.2.1 to CQ 5.3 with Application Servers
• Upgrading from CQ 5.2 to CQ 5.4

5.2.1

The foundation table component was updated in CQ 5.3. This new component continues to be used in 5.5. Consequently any upgrade from 5.2.1 to 5.5 will have to take this into account. See Table Component Changes.

5.2.1

In CQ 5.2 a URL mapping from /content to / was configured by default. Under CQ 5.5 this mapping is no longer set by default but must be configured explicitly. To configure URL mappings see Configuring CQ.

5.2.1

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

1. Change the sling:resourceType from wcm/auth/components/login to cq/core/components/login
2. Move all the static files (background image, css and js) to underneath the /apps/wcm/auth/content/login node (these used to be on the same level as the actual login content node).
   

5.2.1

When upgrading from 5.2 to 5.5 the blog content is not automatically migrated. This content must be manually migrated by exporting (through the package manager) and re-importing into the upgraded instance.

5.2.1

Nodes of type nt:folder with access controls that were added after the installation of CQ 5.2.1 may cause problems on upgrade to 5.5. This does not happen for all nt:folder nodes with ACLs, but only for some. For example, if a customer added ACLs to /libs/collab, this will cause a problem. The crx-quickstart/logs/error.log will log an error like:

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

5.2.1

Depending on the number of cores, JVM heap settings and content stored, there is a small risk that re-indexing a workspace in CQ 5.5 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, the number of which depends on the number of cores available. Modern hardware often has +8 cores and support twice as many threads, which means a CQ instance could setup 32 threads for PDF text extraction. In some cases this will lead to out-of-memory errors when all threads are busy with text extraction.

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

5.2.1

Changes were made to the CQ API from 5.2 to 5.3. These changes still apply in CQ 5.5. Therefore you must ensure that these changes are accounted for in your upgrade.

5.2.1, 5.3

The following API changes were made between CQ 5.3 and 5.4 and still apply in CQ 5.5. If your CQ application uses any of these functions you will need to manually adjust your code.

com.day.cq.dam.api.Asset has changed:

• Resource getRendition(String name) is now
  Rendition getRendition(String name)
• Resource getOriginal() is now
  Rendition getOriginal()
• Resource getCurrentOriginal() is now
  Rendition getCurrentOriginal()
• List<Resource> getRenditions() is now
  List<Rendition> getRenditions()
• Resource getRendition(RenditionPicker picker) is now
  Rendition getRendition(RenditionPicker picker)

com.day.cq.dam.api.RenditionPicker has changed:

• Resource getRendition(Asset asset) is now
  Rendition getRendition(Asset asset)

5.2.1, 5.3

The org.apache.sling.atom.taglib bundle displays an incorrect version number in the CRX system console. On an instance upgraded from 5.3 to 5.5 the version is 0.9.0.tlp-R830217. The correct version, as found in a freshly installed 5.5 instance, is 0.9.0.R988585. To fix this do the following:

• Delete the org.apache.sling.atom.taglib bundle via the bundles page of the system console (http://<host>:<port>/system/console/bundles)
• In the repository (using CRXDE Lite, for example), move /libs/sling/install/org.apache.sling.atom.taglib-0.9.0-R988585.jar to /tmp.
• Wait a few seconds and then move the bundle back to its previous location.
• Wait a few seconds and then verify the bundle version in the system console.

This issue has minimal impact, but for a 100% clean upgrade it should be addressed.

5.2.1, 5.3

The following bundles are no longer used in 5.5:

• org.apache.jackrabbit.jackrabbit-api
• org.apache.sling.samples.path-based.rtp

These can be removed using the Apache Felix console at http://<host>:<port>/system/console.

This issue has minimal impact, but for a 100% clean upgrade it should be addressed.

5.2.1, 5.3

Some properties in crx-quickstart/launchpad/sling.properties differ between CQ 5.2.1 and 5.3 and a fresh CQ 5.5 install. However, in an upgrade to 5.5 these changes are not automatically made. The upgrade installer assumes that any differences in that file are due to manual changes made by an administrator and therefore does not update them. The result is that an upgrade to 5.5 will retain theearlier sling.properties settings, while a fresh 5.5 will have slightly different settings.

The following sling.properties are not updated when upgrading from 5.2.1 or 5.3 to 5.5. Note that these differences all have minimal or no impact. However, if you want a 100% clean upgrade you may wish to change the settings to their fresh 5.5 install values:

• Upgrade refers to the setting as found in 5.2.1 or 5.3 and in a 5.3 instance that has been upgraded to 5.5.
  
• Fresh refers to the setting as found in a freshly installed 5.5 instance.

ds.loglevel

• Upgrade: ds.loglevel=${org.apache.sling.commons.log.level}
  
• Fresh: ds.loglevel=warn

felix.service.urlhandlers

• Upgrade: felix.service.urlhandlers=false
  
• Fresh: felix.service.urlhandlers=true

org.osgi.framework.bootdelegation

• Upgrade: org.osgi.framework.bootdelegation=
  com.yourkit.* ${org.apache.sling.launcher.bootdelegation}
  
• Fresh: org.osgi.framework.bootdelegation=
  com.yourkit.*,
  sun.reflect ${org.apache.sling.launcher.bootdelegation}

org.osgi.framework.system.packages

• Upgrade: org.osgi.framework.system.packages=
  ${osgi-core-packages},
  ${osgi-compendium-services},
  ${jre-${java.specification.version} ${org.apache.sling.launcher.system.packages}
  
• Fresh: org.osgi.framework.system.packages=
  ${osgi-core-packages},
  ${osgi-compendium-services},
  org.apache.sling.launchpad.api;version\=1.0.0,
  ${jre-${java.specification.version}} ${org.apache.sling.launcher.system.packages}

5.2.1, 5.3

In some cases, after a 5.3 to 5.5 upgrade, some bundles may not start properly and instead report an error related to a missing javax.activation package (check the Apache Felix console at http://host:port/crx/system/console/bundles).

In such a case:

• Stop CQ
• Edit the crx-quickstart/launchpad/sling.properties file to remove javax.activation (and the comma that follows) from any list of packages that contains it.
• Restart CQ

For example, in the following sling.properties file you would remove the highlighted string:

5.2.1, 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, for example:
   
   • Mail Service
   • Day Commons GFX Font Helper
   • SSO Authentication Handler
   • Apache Sling Resource Resolver
3. Re-enable LDAP if required (and if disabled during the consistency checks).
4. There are various items (mainly for backup reasons) that can be reviewed, and where appropriate, cleaned up after a successful upgrade to CQ 5.5:
   • repository:
     • /home/groups-<xxx>
     • /home/users-<xxx>
   • file system:
     • crx-quickstart/server/*.NEW_<xxx>
     • crx-quickstart/archived-versions
     • crx-quickstart/repository/patches/new/*.jar
       
   • miscellaneous:
     • /tmp/asset*
     • crx-quickstart/repository/shared/replication/durbo
       
5. 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.
   

5.3

The default CQ clustering system was changed with the introduction in CQ 5.4 from a shared-directory system to a shared-nothing system. The new shared-nothing system continues to be the the default system used in any fresh installation of CQ 5.5.

However, when a 5.5 instance is created through an upgrade from 5.2 (as opposed to a fresh 5.5 install) the clustering system is not automatically upgraded to shared-nothing. Instead, the cluster will continue to use the older shared-directory settings.

Consult CRX Clustering for more details.

ALL

If you performed the optional upgrade to shared nothing clustering and addressed the known issues, then the resulting system will be identical to a fresh CQ 5.5 installation, with the user's content preserved.