Documentation

Updating Previous Versions of Liferay

Staying current with updates gives you the best security and quality.

  • Security Updates are releases that address the latest security issues immediately.

  • Updates are releases that have the latest security updates, fix confirmed bugs, and include new features. The features are disabled by default, but you can opt-in to them in the UI when you want.

Here you’ll learn how to update to a new Liferay Docker image, update to a new Liferay Tomcat Bundle, and update an application server Liferay installation.

Warning

Always back up your database and installation before updating Liferay DXP/Portal.

Important

Versions before Liferay DXP 7.3 SP3 use a patching model instead. If you’re on a version before Liferay DXP 7.3 SP3, please see Patching DXP.

Note

Liferay DXP/Portal general availability (GA) releases are built from the source code. Updates and Security Updates follow the GA and are also built from the source code.

Updating to a New Docker Image

  1. Shutdown your current Docker container.

  2. Clean up the Liferay cache.

    Delete the [Liferay Home]/osgi/state folder.

    cd [Liferay Home]
    rm -rf osgi/state
    

    Empty the [Liferay Home]/work folder.

    rm -rf work/*
    

    Delete the application server cache. Please consult the application server vendor’s documentation for where where to find the cache.

    Note

    If a module’s changes are only internal, the changes are invisible to the OSGi framework, the module stays installed, and the module’s state persists. Clearing the OSGi bundle state information before the next server start ensures that such modules reinstall with the appropriate state.

  3. Find the Liferay Docker image and tag information on Docker Hub:

  4. Check the release notes for any database changes or index changes.

    If there are database changes, enable database upgrades to run automatically using this environment setting in your docker run command:

    -e LIFERAY_UPGRADE_PERIOD_DATABASE_PERIOD_AUTO_PERIOD_RUN=true
    

    If there are index changes, enable index updates using this environment setting in your docker run command:

    -e LIFERAY_DATABASE_PERIOD_INDEXES_PERIOD_UPDATE_PERIOD_ON_PERIOD_STARTUP=true
    
  5. Run the new Docker image with your current environment and parameters, and with any required database/index environment settings (from the previous step). For example, here’s a command for running an image that bind mounts a local folder called liferay to the new image.

    docker run -it -m 8g -p 8080:8080 \
     -v $(pwd)/liferay:/mnt/liferay \
     liferay/[place image name here]:[place tag here]
    
  6. If you enabled database upgrades or index updates in your docker run command, the console and log report all upgrade failures, errors, and additional optional modules to upgrade. You can use Gogo Shell commands to address them. When the upgrades complete successfully, stop the Docker container and create a new container, executing your docker run command without any database upgrade and index update environment settings.

You’re running on the new Liferay update Docker image.

Updating to a New Liferay Tomcat Bundle

  1. Export your modified System Settings (including your File Storage and Elasticsearch settings) to .config files and copy them to your [Liferay Home]/osgi/configs/ folder.

    For example, if you’re using Advanced File System Store or Simple File System Store, export your file store settings to a .config file and copy it to your [Liferay Home]/osgi/configs/ folder. Here’s an example com.liferay.portal.store.file.system.configuration.AdvancedFileSystemStoreConfiguration.config file with the required rootDir parameter:

    rootDir="data/document_library"
    
  2. If you’re using Commerce and the release notes mention database upgrades for Commerce, prepare to upgrade it. See Upgrading Liferay Commerce for details.

  3. Shut down your application server.

    Reasons:

    • On Unix-style systems, you can usually replace files that are running, but the old ones reside in memory.

    • On Windows systems, files in use are locked and can’t be patched.

  4. Back up your installation.

  5. Download the Liferay DXP/Portal Tomcat Bundle update you want from Help Center (subscribers) or Community Downloads.

  6. Unzip the bundle to an arbitrary location.

  7. Replace the new bundle’s [Liferay Home]/data folder with the [Liferay Home]/data folder from your backup.

  8. Copy these files from your backup to the new installation:

    • Configuration files (.config files)

    • DXP activation key (subscribers)

    • Portal Properties (e.g., portal-ext.properties)

    See Migrating Configurations and Properties for additional information.

  9. Replicate your Tomcat customizations (e.g., [tomcat version]/conf folder contents and added libraries) from your backup to the new installation.

  10. Copy your custom widgets and modules to the new installation.

  11. If the release notes mention database changes, use a compatible database upgrade option to apply all required changes and any optional changes you want.

  12. Start the application server.

You’re running on the Liferay update Tomcat Bundle.

Updating an Application Server Installation

  1. Download the Update’s .war file and OSGi Dependencies ZIP file.

  2. Shut down your application server.

    Reasons:

    • On Unix-style systems, you can usually replace files that are running, but the old ones reside in memory.

    • On Windows systems, files in use are locked and can’t be patched.

  3. Extract the .war file contents on top of your existing Liferay web application in your application server installation.

    Here are links to more information about Liferay installation on supported application servers:

  4. Merge the contents of the OSGi Dependencies ZIP file into your [Liferay Home]/osgi folder.

  5. Clean up the Liferay cache.

    Delete the [Liferay Home]/osgi/state folder.

    cd [Liferay Home]
    rm -rf osgi/state
    

    Empty the [Liferay Home]/work folder.

    rm -rf work/*
    

    Delete the application server cache. Please consult the application server vendor’s documentation on where where to find the cache.

    Note

    If a module’s changes are only internal, the changes are invisible to the OSGi framework, the module stays installed, and the module’s state persists. Clearing the OSGi bundle state information before the next server startup ensures that such modules reinstall with the appropriate state.

  6. If the release notes mention database changes, use a compatible database upgrade option to apply all required changes and any optional changes you want.

  7. Start the application server again.

Congratulations! Your Liferay instance is updated and running.