oo
Analytics Cloud
Commerce
DXP / Portal
Liferay Cloud
Reference
Upgrade Basics

Upgrading Via Docker

Running a Liferay Docker image with auto-upgrade enabled uses the Database Upgrade Tool to upgrade your database transparently on Liferay startup. After the upgrade completes, you can continue using Liferay via that Docker container or point a new Liferay on-premises installation to the upgraded database.

important

Don’t have Docker? Go here first:

DXP Edition Image Tags
Liferay DXP (Subscription) dxp here
Liferay Portal portal here
important

Upgrades to enterprise subscriber installations and critical installations should be done using the Database Upgrade Tool. See Using the Database Upgrade Tool for more information.

important

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

Upgrading with the Latest Docker Image

Here are the steps for upgrading with a Docker image:

  1. Create an arbitrary folder to use with the new Liferay Docker image and create subfolders called files and deploy. For example,

    mkdir -p new-version/files

    mkdir -p new-version/deploy

    • files: The Docker container copies files from this folder to the container’s Liferay Home folder.

    • deploy: The Docker container copies artifacts from this folder to the container’s auto-deploy folder.

  2. If you’re using Commerce, prepare to upgrade it. See Upgrading Liferay Commerce for details.

  3. If you want to upgrade your Marketplace app data along with the Liferay database upgrade, download the latest version of each app targeted for the new Liferay version and copy it to your new-version/deploy folder. Otherwise, you can install the apps after the database upgrade and upgrade their data as described in the Post-Upgrade Considerations.

  4. If you’re using an embedded Elasticsearch engine or a local File Store (Document Library), copy the [Liferay Home]/data folder to the new files folder to create new-version/files/data.

  5. Copy and merge the Liferay Home files and application server files from your backup to their corresponding locations in the files folder (your new [Liferay Home]). For example, copy your activation key to new-version/files/license/. The files may include but are not limited to these:

    • /license/*: Activation keys. (Subscription)

    • /log/*: Log files.

    • /osgi/configs/*.config: OSGi configuration files.

    • portal-*.properties: Portal properties files, such as portal-ext.properties.

    • setenv.sh, startup.sh, and more: Application server configuration scripts.

    • web.xml: Portal web application descriptor.

  6. If you’re upgrading to 7.2, disable search indexing using a configuration file in your [Liferay Home]/files/osgi/config/ folder. For example,

    echo "indexReadOnly=\"true\"" >> new-version/files/osgi/config/com.liferay.portal.search.configuration.IndexStatusManagerConfiguration.config

  7. If you’re using Advanced File System Store or Simple File System Store with a modified storage location, export your file store settings to a .config file and copy it to your new-version/osgi/configs folder.

    important

    If you’re using Advanced File System Store, you must configure it with a .config file in the new installation before upgrading the database.

    Here’s an example com.liferay.portal.store.file.system.configuration.AdvancedFileSystemStoreConfiguration.config file with the required rootDir parameter:

    rootDir="data/document_library"

  8. Make sure you’re using the JDBC database driver your database vendor recommends. If you’re using MySQL, for example, set jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver in new-version/files/portal-ext.properties and replace the MySQL JDBC driver JAR your app server uses. See Database Drivers for more details.

  9. (Optional) Enable batch insert by adding the JDBC property to your portal-ext.properties file.

  10. Run the Docker image mounted to your new version folder using the following command. Substitute the image name, tag, and environment values as needed.

    docker run -it -m 8g -p 8080:8080 \
 -v $(pwd)/new-version:/mnt/liferay \
 -e LIFERAY_UPGRADE_PERIOD_DATABASE_PERIOD_AUTO_PERIOD_RUN=true \
 liferay/[place image name here]:[place tag here]

    The -v new-version:/mnt/liferay arguments bind mount the host’s new-version folder to the container’s /mnt/liferay folder. Please see Providing Files to the Container for more information on the mapping files to the container’s Liferay Home.

    The parameter -e LIFERAY_UPGRADE_PERIOD_DATABASE_PERIOD_AUTO_PERIOD_RUN=true triggers the database upgrade to run automatically at startup.

    Optionally, the upgrade report can be enabled with the parameter -e LIFERAY_UPGRADE_PERIOD_REPORT_PERIOD_ENABLED=true and the upgrade log context can be enabled with the parameter LIFERAY_UPGRADE_PERIOD_LOG_PERIOD_CONTEXT_PERIOD_ENABLED=true. Use the parameter LIFERAY_UPGRADE_PERIOD_REPORT_PERIOD_DIR={your_directory} to define an output directory for the upgrade report. If none is set, Liferay_Home/reports is the default report directory.

  11. In the console or log, confirm successful database upgrade and server startup. Upgrade messages report starting and completing each upgrade process. A message like this one indicates server startup completion:

    org.apache.catalina.startup.Catalina.start Server startup in [x] milliseconds

    If there are any upgrade failures or errors, they’re printed to the console and log. You can use Gogo Shell commands to troubleshoot any issues and finish the upgrade.

    Additionally, these upgrades performed at startup can be monitored with MBeans.

  12. After you have resolved any failures or errors, examine the Post Upgrade Considerations.

  13. Update the Portal properties in your new installation.

  14. Validate your upgraded database.

    Here is the Liferay landing screen.

Your database upgrade is now complete!

If you want to continue using the new Liferay version via Docker, remove the -e LIFERAY_UPGRADE_PERIOD_DATABASE_PERIOD_AUTO_PERIOD_RUN=true environment setting from the docker run ... command you used to create the new container.

note

Using Liferay Docker Images demonstrates creating, stopping, and restarting Docker containers.

Conclusion

If the upgraded database is all you need, then enjoy using your new Liferay instance! If there’s more to completing your upgrade, these articles can help you finish: