Submit Feedback

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: https://docs.docker.com/get-docker

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:

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.
If you’re using Commerce, prepare to upgrade it. See Upgrading Liferay Commerce for details.
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.
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.
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. Only copy over your custom configuration files. Do not include any *-default.config files generated by Liferay.
- 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.

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

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"
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.
(Optional) Enable batch insert by adding the JDBC property to your portal-ext.properties file.
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.
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.
After you have resolved any failures or errors, examine the Post Upgrade Considerations.
Update the Portal properties in your new installation.
Validate your upgraded database.

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.

If the upgraded database is all you need, then enjoy using your new Liferay instance! If there’s more to completing your upgrade, see the related topics below.

Upgrading Via Docker

Upgrading with the Latest Docker Image

Related Topics