Documentation

Upgrade Overview

Liferay’s tools and instructions facilitate upgrading DXP and Portal CE environments safely and quickly. Non-clustered environments that have small data sets, for example can be upgraded using a Docker image. DXP environments and Portal CE environments that are complex, have larger data sets, or have many customizations are upgraded using the Database Upgrade Tool.

Warning

Always back up your database and installation before upgrading. Testing the upgrade process on backup copies is advised.

Note

Upgrading via Docker is the easiest way to upgrade a database for a small, casual Portal CE environment.

Before starting your upgrade, consider what may be involved. The upgrade topics fall into these categories:

Preparation and Planning

Preparation and planning may be of little consequence for small, casual installations but is mandatory for large enterprise-level installations.

Review Available Upgrade Paths

Look up your current Liferay DXP/Portal version in this table to determine your installation upgrade path.

Upgrade Path Description
Liferay DXP/Portal 6.2+ → DXP 7.3
Liferay Portal 6.1.x → DXP/Portal 7.1 → DXP 7.3 Support life ended for Liferay Portal 6.1
Liferay Portal 5.x and 6.0.x → Liferay Portal 6.2 → Liferay DXP 7.3 Support life ended for Liferay Portal 5.0, 5.1, 5.2, and 6.0

If your path includes upgrading to Liferay Portal 6.2, follow the Liferay Portal 6.2 upgrade instructions first.

Review Deprecations and Changes to Default Settings

Features and configuration defaults may change in new versions of Liferay. See the reference section or the following articles for the most recent deprecations and changes to features and to settings:

Request an Upgrade Patch (Subscription)

Subscription

If you have a Liferay DXP subscription, update to the latest fix pack and/or request an upgrade patch to prepare for the database upgrade. File a ticket in the Help Center to start this process.

Update Marketplace Apps

Marketplace apps should be updated to the latest version for the Liferay version you’re currently on before upgrading the Liferay database. Skipping app updates can be problematic and prevent the apps from enabling on the new Liferay version.

Important

Do this on your current installation before upgrading.

After upgrading the database, install the latest app versions for your new Liferay instance.

Upgrading Custom Development

Plugins (e.g., themes, apps, and customizations) you’ve developed must be adapted to the new Liferay version. This can be as simple as updating dependencies or involve updating code to API changes. If you forgo updating your custom plugins, they may be disabled on the new Liferay version. Upgrading Custom Development walks through the code upgrade process.

Migrating and Updating Configurations and Infrastructure

Configurations and supporting infrastructure must be migrated and updated from your previous installation to your new one.

Important

If you’re upgrading from 6.2 or earlier, update your file store configuration. See the Updating the File Store for more information.

You can wait until after database upgrade to update your other settings. See these Migrating Configurations and Properties for more information.

Improving Upgrade Performance

Upgrading large data sets can take a prohibitively long time, if you leave unnecessary data intact or forgo performance tuning. There are several ways to quicken database upgrades.

Prune Data

If your Liferay server has instances, sites, pages, or versioned content items (e.g., Web Content articles, Documents and Media files, and more) that are unnecessary, removing them can cut down upgrade time considerably. See Database Pruning for Faster Upgrades on ways to prune your database of unnecessary data.

Tune Database Performance

Adjusting your database for upgrade operations (more data writes than in production) improves database upgrade performance. See Database Tuning for Upgrades for details.

Executing the Database Upgrade

There are two ways to upgrade your Liferay database:

  • Upgrade via Docker involves passing an auto upgrade parameter to the command for starting a Docker image. The image updates the database and then starts up using the upgraded database.

  • Using the Database Upgrade Tool. The Upgrade Tool is a client program for updating the Liferay database while it’s detached from any Liferay instance. It facilitates focusing on the upgrade process, tuning the database for upgrade operations, and pruning unnecessary data to quicken the database upgrade.

Conclusion

Once you complete the tasks outlined above, your upgrade is complete. But before using Liferay, you must re-establish desired runtime settings and undo any upgrade-specific tuning. Plus there may be applications that weren’t available on your previous Liferay version that are recommended for new Liferay production instances. See the Post-Upgrade Considerations for more information.

Now that you’re familiar with the upgrade components, you can upgrade your Liferay instance. Make sure to do preliminary tasks on your current installation, before upgrading the database. It’s common to upgrade custom plugin code and execute the database upgrade in parallel. Since, database upgrade is a popular task to start first, here are links to the two methods:

Additionally, refer to these other upgrade scenarios if they relate to your upgrade: