1. Liferay Help Center
  2. Knowledge Base
  3. How-to

Checklist for Upgrading to Liferay DXP

Avatar

Liferay Support

  • Updated

Upgrading to Liferay DXP (7.0, 7.1, 7.2, or 7.3) is a major project and requires careful planning, testing and execution in order to be successful. However, Liferay DXP and DXP Cloud teams have introduced several features that make this upgrade process easier and as seamless as possible. This article is designed to be a high-level overview of the upgrade process, and provides a general checklist for customers. It is a supplement to the Official Documentation and Support Knowledge Base articles. Most importantly, administrators should always review documentation that is specific to their environment (e.g. Apache for Tomcat, IBM for WebSphere, and so forth).

This article's scope is limited to customers upgrading from Liferay Portal 6.2 and higher to Liferay DXP 7.x.

Table of Contents

  1. Overall Project Management
  2. Prepare the Upgrade Environment
  3. Consult Documentation
  4. Create Backups
  5. Resolve Issues in the Legacy Environment
  6. Update Customizations
  7. Perform Upgrade Simulations
  8. "What should I do when there are failures during upgrade process?"
  9. After the Upgrade

 

1. Overall Project Management

Before upgrading, system administrators should do the following:

  1. Identify the personnel and resources involved;
  2. Identify the risks and plans for mitigation of risks;
  3. Create a rollback strategy;
  4. Notify the Liferay sales representative about possible issues or having the Liferay Global Services conduct an upgrade analysis first.
  5. Open a Help Center ticket after an issue has been discovered.

2. Prepare the Upgrade Environment

Consult the Liferay Compatibility Matrix ( DXP 7.0 | DXP 7.1 | DXP 7.2 | DXP 7.3) before choosing the desired environment to see whether it is supported.

Consult the Deployment White Paper to get the minimum requirements for each Liferay DXP JVM.

Obtain the following:

  1. Java JDK 1.8 or its equivalent;
  2. The latest Liferay DXP  .war or bundle with the most recent service pack;
  3. Elasticsearch for the appropriate environment 
  4. The most recent version of the database and associated JDBC drivers.
  5. Liferay Connected Services (LCS) activation key and latest LCS Client (for those who want LCS)
  6. DXP 7.0, 7.1, 7.2, or 7.3 Activation Key

Important configuration notes:

  • In Liferay DXP, configurations for the Documents and Media will have to be configured in a separate .config file in order to leverage the updated Documents and Media module. See Introduction to Upgrading to Liferay DXP for more information.
  • Administrators planning to the Advanced File Store method to manage documents need to create a file called com.liferay.portal.store.file.system.configuration.AdvancedFileSystemStoreConfiguration.config and place it in the /osgi/config folder.

    At the same time, set dl.store.impl=com.liferay.portal.store.file.system.AdvancedFileSystemStore in the portal-ext.properties file.

    For more information, see Document Repository Configuration.
  • For environments utilizing staging: Administrators should publish their changes to the live site before upgrading. If this step is missed, you will need to run a full publish (or manually publish changes) as the upgraded system won't know what content changes have occurred since the last publish.

3. Consult Documentation

4. Create Backups

Upgrades perform database modifications and not all upgrades complete successfully. Creating backups are mandatory and thus available in case a roll back is needed. No matter which version of Liferay Portal is being used, having a backup that can be brought up and on-demand reduces the amount of downtime for the environment.

Create backups for the following (but not limited to): configuration files like the portal-ext.properties, the database, and any document library file system (e.g. Sharepoint, Documentum, Nuxeo) repository. Backing the application server is also advised to facilitate restoring the environment. There is no need to save the search indices because they will be rebuilt after the upgrade.

Note that in Liferay DXP, the upgrade tool has the ability to restart the upgrade at each failed point of the upgrade process for modules and not the core upgrade. However, it is strongly recommended that if there are logical stopping points in the upgrade process (e.g. from Liferay Portal 5.2 to Portal 6.1 EE GA2, then Portal 6.2, and finally DXP 7.0, 7.1, 7.2, or 7.3), administrators should create a backup for a known good point.

5. Resolve Issues in the Legacy Environment

Ensure that the legacy Liferay Portal version does NOT currently have any issues. Any exceptions or issues (with data) that are found within the legacy Liferay Portal version need to be resolved prior to any upgrade attempts. This extends to issues which prevent portal functionality or usage.

In order to locate and resolve some issues, the verify process can be used to run on startup to fix any integrity problems found within the database.

The verify process can be enabled via the verify.frequencyportal-ext.properties file.

 # Specify the frequency for verifying the integrity of the database.
 #
 # Constants in VerifyProcess:
 #     public static final int ALWAYS = -1;
 #     public static final int NEVER = 0;
 #     public static final int ONCE = 1;
 #
 verify.frequency=1

The new version will have to leverage some of the legacy properties and values from the previous version in order to ensure no data is lost during the upgrade.
Specific issues include:

  • Document Library
    Most importantly, beginning in Liferay Portal 6.1, dl.store.impl replaced dl.hook.impl for the implementation of the Documents and Media portlet. Although other hooks can still be used in Liferay Portal 6.1, they will be unavailable in later versions.
  • Web Content
    Structures cannot have duplicate names; see Structures With Duplicate Element Names Fail DDM Verification When Upgrading on how to resolve this known issue before upgrading to DXP.

6. Update All Official Liferay and Customized Apps

Customized portlets and apps developed in legacy versions of Liferay Portal only work with their specific portal version. Newer versions will have updates to API and class changes. These changes must be reviewed and any code changes will have to be incorporated to any portlets, plugins, or themes for Liferay DXP 7.0, 7.1, 7.2, or 7.3.
These code changes can be found within the Release Notes documentation for each version of the Liferay platform. Liferay's Java Docs are also very useful for finding any deprecated methods and changes. DTD files can also be referenced. Consult the Breaking Changes for more information.

Users will also need to update to the specific version of the Liferay SDK for the Liferay portal and re-compile customized apps to ensure they are made available immediately after the upgrade has completed. The SDK is readily available to download at the Help Center. Be sure to download the latest versions of the apps from Liferay Marketplace so that there are no interruptions. Liferay Support MAY be able to assist in providing resources to these updated changes within Liferay. However, support is limited in reviewing any customizations or custom code changes.

7. Perform Upgrade Simulations

Before performing the actual upgrade, it is suggested that administrators perform a simulated upgrade. One way is to use a copy of the production database and data directory to simulate the final upgrade. This tests the upgrade process against the database and sometimes leads to failures due to discovering stale, corrupt or invalid data. Upgrade simulation runs are used to clean up data so the final production upgrade runs without issue.
Upgrade simulations also test the upgrade tool to verify it works against the environment; if there is a problem with the tool, it is always better to find and report the issue in Help Center before being stuck the middle of the final production upgrade.
Upgrade simulations will also give the team completing the upgrade experience running the various commands, resolving issues identified during the upgrade, and lastly give confidence that they will be able to complete the upgrade successfully.

Do not underestimate the value of a dry-run. Database upgrades take time to complete and it is difficult if not impossible to estimate upgrade runtime; factors such as amount of customer data and customizations impact runtime duration.
Perform a dry-run upgrade against a copy of the production database and data directory to identify how long the final upgrade will take.

 

8. "What should I do if there are failures during upgrade process?"

  1. If the upgrade appears to be "stuck" during any point of the process, please note at which step this occurs.
  2. Provide the Liferay Support team with the full upgrade logs, thread dumps, and relevant database queries that may be affecting the "stuck" point of the process. Provide information on any customizations and custom apps that may be affecting the upgrade process.
  3. If the upgrade fails with ANY exceptions, address the issue within the legacy portal and re-launch the process again since the upgrade is prepared to be re-launched from the latest point of failure (Note: except for upgrade processes related to DXP 7.0 or 7.1 where you will need to restore a backup). This is helpful for non-production environments where you have enough time to diagnose or fix issues.
  4. Incremental upgrades may help when troubleshooting upgrade issues (e.g. when upgrading from 6.1 portal to DXP 7.x, it may help isolate the issue if you upgrade from 6.1 to 6.2, then 6.2 to 7.0 and finally 7.0 to the latest.)

9. After the Upgrade

Please consult this official documentation on Post Upgrade Considerations

Was this article helpful?
2 out of 3 found this helpful