oo
Analytics Cloud
Commerce
DXP / Portal
Liferay Cloud
Reference
Reference

Liferay Cloud Project Changes in Version 4

Several changes are made between version 3.x and 4.x of the Liferay Cloud stack, including where Docker image versions are defined for your services, the structure of the repository, and how Jenkinsfiles are used.

Contents:

Changes to Docker Image Definitions

Docker images for your services in version 4.x of Liferay Cloud are no longer defined in the project’s gradle.properties file. They are now defined in the LCP.json file for each service.

Upgrading to Liferay Cloud Stack version 4 changes every service’s Docker image version from 3.x.x to 4.x.x. These image changes are in addition to organizational changes to how Liferay Cloud projects are structured and function.

Project Organization Changes

The biggest change to the repository is that each service’s files (including their LCP.json file) have been moved to a folder at the root of the repository (e.g., liferay/ or webserver/). You can deploy each of these services individually by navigating into these relocated service folders and using the CLI tool. The lcp folder is removed and is no longer in the path for any of these services. These folders themselves have been reorganized to resemble a Liferay workspace structure.

Several other files previously at the root of the repository (including gradle.properties, build.gradle, and settings.gradle) have also been moved into the liferay service.

Liferay Service Changes

The liferay service folder now follows the functional structure of a Liferay Workspace.

All configurations within the liferay service now belong in an environment-specific configs directory that corresponds to a project’s Liferay Cloud environments. Additionally, the license folder has been removed; add your licenses into the deploy folder instead.

The following table summarizes the new organization of your liferay service configurations:

Files Location in 3.x Location in 4.x
Files for deployment lcp/liferay/deploy/[ENV]/ liferay/configs/[ENV]/deploy/
OSGi configuration files (.cfg or .config) lcp/liferay/config/[ENV]/ liferay/configs/[ENV]/osgi/configs/
Other configuration overrides lcp/liferay/config/[ENV]/ liferay/configs/[ENV]/
Custom shell scripts lcp/liferay/script/[ENV]/ liferay/configs/[ENV]/scripts/
Hotfixes and patching tools lcp/liferay/hotfix/[ENV]/ liferay/configs/[ENV]/patching/
Licenses lcp/liferay/license/[ENV]/ lcp/configs/[ENV]/deploy/
note

Files within the configs/[ENV]/ directory are copied as overrides into the LIFERAY_HOME directory in the Liferay container in Liferay Cloud.

Instead of directly committing hotfixes to the repository, a new CI service environment variable is now available to automatically add when deploying the Liferay service. See Installing Hotfixes with an Environment Variable for more information.

Custom Script Execution

Scripts placed in liferay/configs/[ENV]/scripts/ will now be run as the liferay user, rather than as a root user. If a script must be run as root, then the script must be added to the Jenkinsfile instead.

Search Service Changes

All configurations within the search service now belong in an environment-specific configs directory. See the following table for the new organization of your search service configuration:

Files Location in 3.x Location in 4.x
Elasticsearch configurations lcp/search/config/[ENV]/ search/configs/[ENV]/config/
Custom shell scripts lcp/search/script/[ENV]/ search/configs/[ENV]/scripts/
Elasticsearch license (.json) files lcp/search/license/[ENV]/ search/configs/[ENV]/license/
note

Files in search/configs/[ENV]/ are copied as overrides into usr/shared/elasticsearch/ in the Search container in Liferay Cloud. For example, configurations in search/configs/[ENV]/config/, such as elasticsearch.yml, are copied into usr/shared/elasticsearch/config/ and override existing defaults.

Elasticsearch Plugins

Elasticsearch plugins may now be installed to your search service. To see the installed Elasticsearch plugins, use the shell within the search service and run the following command:

bin/elasticsearch-plugin list

If you would like to install additional Elasticsearch plugins beyond the ones our image installs by default, you can set the LCP_SERVICE_SEARCH_ES_PLUGINS environment variable in your search service to a comma-delimited list of plugin names to be installed. They will be installed during the service’s deployment.

CI Service Changes

A default Jenkinsfile is no longer required in the repository, as a default pipeline is now defined. Any Jenkinsfile is now defined in the ci folder, rather than the root of the repository.

Multiple Jenkinsfile extension points are now available in the ci folder to define procedures at different stages of creating a build. See Extending the Default Jenkinsfile for more information.

Installing Hotfixes with an Environment Variable

Instead of directly committing large hotfixes to your Git repository, a new environment variable has been added that allows you to install a hotfix through the CI build process. Add the hotfix’s name (with the .zip extension omitted) 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.

The following example defines hotfixes using the LCP.json file:

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

Webserver Service Changes

All configurations within the webserver service now belong in an environment-specific configs directory. Additionally, the deploy folder for static content has been removed; add your custom content into the public folder instead.

See the following table for the new organization of your webserver service configuration:

File Location in 3.x Location in 4.x
Webserver configurations lcp/webserver/config/[ENV]/ webserver/configs/[ENV]/conf.d/
Custom scripts lcp/webserver/script/[ENV]/ webserver/configs/[ENV]/scripts/
Static content lcp/webserver/deploy/[ENV]/ webserver/configs/[ENV]/public/
note

Files in /webserver/configs/[ENV]/ are copied as overrides into /etc/nginx/ in the webserver container in Liferay Cloud. Files in /webserver/configs/[ENV]/public/ are copied as overrides into var/www/html/.

Webserver Configuration Overrides

You can customize the root location for the webserver service by adding a liferay.conf file into webserver/configs/[ENV]/conf.d/. This will override the default liferay.conf available in the webserver service image’s container. Access the shell in the Liferay Cloud Console to see the default liferay.conf file as a reference when customizing the root location.

warning

Do not customize the root location using a file name other than liferay.conf, so that this file specifically overrides the default liferay.conf. Otherwise, both files may exist together in the container and two root locations may be found, causing an error.

Other file names are instead used to define additional locations for your webserver.

You can also override the default NGINX configuration by adding an nginx.conf file into webserver/configs/[ENV]/. You can use this to further define the webserver’s behavior. See the official NGINX documentation for more information.

Configuring the Public Directory

If you wish to add custom static content, then place these files in webserver/configs/[ENV]/public/. Liferay Cloud will look for this public folder and copy all files inside of it to /var/www/html.

You will need to add additional locations within your conf.d folder to configure the public folder. For example, to add a .html file (such as index.html) to a new webserver/configs/[ENV]/public/static folder, add a unique .conf configuration file to webserver/configs/[ENV]/conf.d with the following content:

location /static/ {
  root /var/www/html;
}

Backup Service Changes

All configurations within the backup service now belong in an environment-specific configs directory. This mainly pertains to custom SQL scripts:

File Location in 3.x Location in 4.x
Custom SQL scripts lcp/backup/script/[ENV]/ backup/configs/[ENV]/scripts/

All .sql scripts deployed to the backup service are executed automatically after a backup restore process completes, and the environment that is being restored to executes the scripts from its own backup service. You can also compress large .sql files, or multiple .sql files, in .tgz, .gz, or .zip format and place them in this directory.

Known Limitations

The new stack does not contain a docker-compose file to spin up a local environment. Because of this, a DXP bundle is needed for local testing.

You can test changes in a local environment, and then migrate them to Liferay Cloud. See Migrating to Liferay Cloud for more help.

Capability:
Cloud
Deployment Approach:
Liferay PaaS
Feature:
Cloud Platform Administration
Reference