oo
Analytics Cloud
Commerce
DXP / Portal
Liferay Cloud
Reference
Using Liferay Docker Images

Patching DXP in Docker

Liferay patches fix DXP issues and the Patching Tool applies the patches. On Docker Hub, Liferay provides images pre-populated with each new Fix Pack, Security Fix Pack, and Service Pack. Liferay also provides Security Fix Packs, Hotfixes, and new Patching Tool versions to install to DXP containers.

Enterprise Subscription

important

Always back up your database and installation before patching.

Using Fix Pack, Security Fix Pack, and Service Pack Images

Fix Pack, Security Fix Pack, and Service Pack images are based on Slim Bundles. Slim Bundles start up faster and have a smaller footprint than regular Liferay Tomcat bundles. Only one patch, however, can be applied to a Slim Bundle. These images, therefore, have these patching limitations:

  • Fix Pack and Service Pack images can receive only one additional patch, such as a Hotfix or a Security Fix Pack.

  • Security Fix Pack images cannot be patched. They comprise a Fix Pack patched with a Security Fix Pack already.

Using a new Fix Pack, Security Fix Pack, or Service Pack image requires migrating to a container based on that image. Here is how to migrate from a DXP container to a new patch image.

  1. Stop your current DXP container.

  2. Back up files you’ve used to customize your DXP container.

    git commit -a

  3. Download the new image from Docker Hub.

    docker pull liferay/dxp:[tag]

  4. Create a new container based on the image and that uses the artifacts and configuration files from your backup.

    For example, you can put your artifacts and files in a local folder structure like this:

    [host folder]
├───deploy
├───files
├───patching
└───scripts

    Then bind mount the host folder to the container’s /mnt/liferay folder in your run command.

    docker run ... -v [host folder path]:/mnt/liferay liferay/dxp:[tag]

DXP launches in the new container using your artifacts and files.

Installing a Patch

Fix Pack images and Service Pack images are limited to receiving one additional patch. The patch can be a Hotfix, Security Fix Pack, or a patch that combines both. To get this last type of patch, create a Help Center ticket and request a patch that includes the latest security fixes and product fixes on top of your current Fix Pack level.

Patching requirements:

  1. No existing patches in the container. Any existing patch must be reverted before applying a new patch.

  2. The image must not be Security Fix Pack image; those images already include a patch (the Security Fix Pack).

  3. A folder in your volume or bind mount that maps to the container’s /mnt/liferay/patching folder. Please see Providing Files to the Container for more information.

There are two methods for installing patches to containers:

  1. Installing a patch to an existing container.

  2. Installing a patch to a new container.

Installing to an Existing Container

Here are the steps for installing a patch to your existing container:

  1. Stop your current container.

  2. Download the patch and copy it to a folder in a volume or bind mount that maps to the container’s /mnt/liferay/patching folder.

  3. Restart your container.

Installing to a New Container

Here are steps for installing a patch to a new container:

  1. Create a host folder and a subfolder called patching.

    mkdir -p [host folder]/patching

  2. Download the patch and copy it to your [host folder]/patching folder. For example,

    cp ~/[patch file] [host folder]/patching

  3. Stop your current DXP container, if it’s running.

  4. Create a container with a bind mount that maps the patch file’s folder to the container’s /mnt/liferay/patching folder. Since this example’s patch file is in a folder called patching, you can bind mount its parent folder ([host folder]) to the container’s /mnt/liferay folder. This makes the patch accessible for applying to DXP.

    docker run ... -v [host folder path]:/mnt/liferay liferay/dxp:[tag]
    note

    Please see Providing Files to the Container for more information on specifying bind mounts.

The Patching Tool installs the patch and DXP launches.

important

If the Patching Tool reports this message: [patch file] is incompatible with Patching Tool version [x.y.z], install the latest Patching Tool. See Installing the Patching Tool for details.

Reverting a Patch

If you want to revert a patch from a container or install a different patch to a patched container, you must remove the container and create a new one.

  1. Stop the container.

    docker stop [container]

  2. Back up the container’s artifacts and files.

  3. Remove the container.

    docker rm [container]

  4. Use the docker run arguments you used previously to create a new container from the same image or an image that has a compatible Fix Pack Level. Apply any patch you want via a volume or bind mount.

Updating the Patching Tool

If your current Patching Tool is incompatible with the patch you’re installing, the Patching Tool reports this message: [patch file] is incompatible with Patching Tool version [x.y.z], where x.y.z are the tool’s major, minor, and micro version number.

Here’s how to install a new Patching Tool version:

  1. Download the latest Patching Tool from the Customer Portal.

  2. If the Patching Tool ZIP file name doesn’t have this format patching-tool-x.y.z.zip rename it to use that format. For example,

    mv patching-tool.zip patching-tool-2.0.15.zip

  3. Install the Patching Tool ZIP file to the container via the container’s /mnt/liferay/patching folder, in the same way that Hotfixes and Security Fix Packs are installed.

On restarting your container or running a new container, the container entry point installs the new Patching Tool.

Upgrading the Database for a Patch

If a patch requires upgrading the database, you must upgrade it using the Database Upgrade Tool in a non-containerized environment.

  1. Install the Liferay Tomcat Bundle installation of the Liferay version you’re using.

  2. Apply the patch to the installation. Please see Patching Liferay for more information.

  3. Upgrade the database using the Database Upgrade Tool. Please see Using the Database Upgrade Tool for more information.

After the database is upgraded, run your container that uses that database.

Capability:
DXP Self-Hosted Installation, Maintenance, and Administration
Deployment Approach:
Liferay Self-Hosted
Feature:
DXP Configuration