Documentation

Deploying to the Liferay Service

As with other services, deploying custom additions involves adding your configurations or files to the appropriate locations in your Git repository. However, deploying the Liferay service slightly differs from deploying other services.

The Liferay service makes use of a Liferay workspace to give you more options to add deployable files, source code, and more. These are easily included with a CI build, but if you are using the CLI tool, then some extra steps are necessary specifically for the Liferay service.

Defining the Liferay DXP Docker Image

The Liferay service image (defined in the LCP.json file, like other services) is not the same as the Liferay DXP Docker image. The Liferay DXP Docker image determines the exact version (including the fix pack) of Liferay that runs in your Liferay service. This is defined in your repository’s liferay/gradle.properties file, with the liferay.workspace.docker.image.liferay property.

Check the Liferay DXP Docker tags to find the right image for your version of DXP.

Important

The major version number of DXP defined in the image property of the Liferay service’s LCP.json file must match the major version in the liferay.workspace.docker.image.liferay property in liferay/gradle.properties. The Liferay service may fail to start up after deployment if the two are different.

CLI Tool Deployment

Deploying with the CLI tool requires extra steps to deploy with your customizations and configurations. These must be included in a special Dockerfile image that is generated before you deploy.

Deployable files, built source code, hotfixes, and licenses require extra steps to include with your deployment if you are using the CLI tool. These extra steps are not necessary if you are using the CI service to generate a build from your repository.

If you deploy the Liferay service with the CLI normally (when deploying all services at once, or from the liferay/ directory), then a default version of the Liferay DXP image (using the major version defined in LCP.json) will deploy, that does not contain your customizations. This happens because you must specifically build and deploy any customizations with the service for them to be included.

Follow these steps to deploy the Liferay service with your customizations:

  1. From the command-line in the liferay/ directory, run:

    gw clean createDockerfile deploy
    

This builds all of your customizations, and arranges them into a build/liferay/ subfolder. It also adds a Dockerfile specifically for a customized version of DXP.

  1. Copy the LCP.json file into the newly generated build/docker/ subfolder.

  2. Run the lcp deploy command as usual from this subfolder.

This deploys the customized service instead of a default version.

Deploying Themes, Portlets, and OSGi Modules

To install themes, portlets, or OSGi modules, include a WAR or JAR file into a configs/{ENV}/deploy/ folder in your Liferay DXP service directory.

For example, to deploy a custom JAR file to your development environment (using the dev/ environment folder), your Liferay DXP service directory could look like this:

liferay
  ├── LCP.json
  └── configs
      └── dev
          ├── deploy
          │   └── com.liferay.apio.samples.portlet-1.0.0.jar
          ├── osgi
          ├── patching
          ├── scripts
          └── portal-ext.properties

Once deployed, any files within the configs/{ENV}/deploy/ directory are copied to the $LIFERAY_HOME/deploy/ folder in your Liferay service’s container.

Note

Certain files and configurations are forced to be present when an image is deployed, and they may override your added files. Look for the message DXPCloud Liferay Overrides in your service’s logs to identify when your files are overridden.

Note

If you are using version 3.x.x services in your repository, then themes, portlets, and OSGi modules instead belong in the appropriate lcp/liferay/deploy/{ENV} folder. See Understanding Service Stack Versions for more information on checking the version.

Building and Deploying Source Code

The source code for new additions can also be included in a CI build. When the build starts, it will automatically compile the source code.

A CI build will compile source code within these folders:

  • The liferay/modules folder for new modules

  • The liferay/themes folder for custom themes

  • The liferay/wars folder for exploded WARs

Note

If you are using version 3.x.x services, then these subfolders are located at the root of the repository instead of in the liferay/ directory. See Understanding Service Stack Versions for more information on checking the version.

Once deployed, the deployable .jar or .war files are copied to the $LIFERAY_HOME/deploy/ folder in your Liferay service’s container. This occurs whether the build in CI compiles your code, or you generate it yourself using the available Gradle command before deployment.

Deploying Hotfixes

To apply a hotfix, add the hotfix ZIP file to a configs/{ENV}/patching/ folder within the Liferay DXP service directory. When you deploy this change, the hotfix is applied to the Liferay DXP instance.

Note

See these instructions to update to a new minor version of Liferay DXP instead (such as a new service pack).

For example, you can deploy a hotfix to your development environment with a structure like the following:

liferay
  ├── LCP.json
  └── configs
      └── dev
          ├── deploy
          ├── osgi
          ├── patching
          │   └── liferay-hotfix-2-7110.zip
          └── scripts

Note that the hotfix must be re-applied each time the server starts up. For this reason, updating to the latest Fix Pack or Service pack of the Liferay DXP Docker image in your LCP.json file is better than adding a hotfix into this folder for the long term; you can update the Docker version by replacing the image environment variable in this file (in the liferay/ directory.

Note

If you are using version 3.x.x services, then hotfixes are instead added into the lcp/liferay/hotfix/ folder. The Docker image version in this case is instead defined with the liferay.workspace.lcp.liferay.image property, in your repository’s gradle.properties file. See Understanding Service Stack Versions for more information on checking the version.

Patching via Environment Variable

You can also install hotfixes as part of the CI build process instead of directly committing them to your Git repository. This approach is ideal for large hotfixes so you can avoid keeping large files in your repository.

Add a comma-delimited list of hotfixes to the LCP_CI_LIFERAY_DXP_HOTFIXES_{ENV} environment variable (either through the Environment Variables tab in the Liferay Cloud console, or in the ci service’s LCP.json file) for the CI service to automatically apply them during the build process.

Note

If you add this environment variable to the LCP.json for your ci service, then you must deploy the ci service to your infra environment to complete the update.

See the following example of defining hotfixes through in the LCP.json file:

"env": {
    "LCP_CI_LIFERAY_DXP_HOTFIXES_COMMON": "liferay-hotfix-10-7210,liferay-hotfix-17-7210",
    "LCP_CI_LIFERAY_DXP_HOTFIXES_DEV": "liferay-hotfix-15-7210,liferay-hotfix-33-7210",
}

Note

This environment variable is only available if you have upgraded to at least version 4.x.x services. See Understanding Service Stack Versions for more information on checking the version.

Deploying Licenses

You can add your own license by putting it into a configs/{ENV}/deploy/ folder within the Liferay DXP service directory.

For example, you can add licenses to your development environment with a structure like this in your Liferay DXP service directory:

liferay
  ├── LCP.json
  └── configs
      └── dev
          ├── deploy
          │   ├── license.xml
          │   └── license.aatf
          ├── osgi
          ├── patching
          └── scripts

Behind the scenes, XML licenses are copied to $LIFERAY_HOME/deploy, and AATF licenses are copied to $LIFERAY_HOME/data.

Note

If you are using version 3.x.x services, then licenses instead belong in the lcp/liferay/license/{ENV}/ folder in your repository. See Understanding Service Stack Versions for more information on checking the version.

Additional Information