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
- Project Organization Changes
- Liferay Service Changes
- Search Service Changes
- CI Service Changes
- Webserver Service Changes
- Backup Service Changes
- Known Limitations
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/ |
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/ |
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/ |
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.
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. Other file names are instead used to define additional locations for your webserver.
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
To add custom static content, place these files in webserver/configs/[ENV]/public/
. Liferay Cloud looks for this public folder and copies all files in it to /var/www/html
.
You must 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.