Upgrading Your Liferay Cloud Stack
Upgrading your repository to use the new structure in Liferay Cloud version 4 allows you to take advantage of Liferay Workspace within your repository, keep your services up to date, and use a range of new and updated features.
Upgrading to the new repository structure involves the use of an upgrade script.
Preparing to Upgrade
In order to upgrade to version 4.x.x of the Liferay Cloud stack, your current services must be at 3.x.x. To verify your current version, locate the gradle.properties file in your repository. Before upgrading to version 4.x.x, repositories follow this structure:
repository
├── gradle
├── lcp
├── liferay
├── modules
├── themes
├── build.gradle
├── gradle.properties
├── gradlew
├── gradlew.bat
├── Jenkinsfile
├── README.md
├── README-dxpcloud.md
└── settings.gradle
If the repository does not follow this structure (and there is no gradle.properties
file or lcp
folder present at the root), then this indicates an upgrade to version 4.x.x has already been completed.
Open the gradle.properties
file and review the versions specified for any of your Docker images. For example, this is the image version for the Liferay service:
liferay.workspace.lcp.liferay.image=liferaycloud/liferay-dxp:7.2.10-sp1-fp4-3.0.19
The number at the end of the Docker image name indicates the version of the Liferay Cloud stack you are using. Ensure that the image name ends with 3.x.x
(in this example, liferay-dxp:7.2.10-sp1-fp4-3.0.19).
Next, make sure your Git repository is on a clean branch. The upgrade script will commit any previously uncommitted files and check out a new branch called upgrade-workspace
.
If you already have an upgrade-workspace
branch, then the script will skip creating it and will work with your current branch.
Running the Upgrade Script
Perform the following steps to upgrade:
-
Download the upgrade script, and extract it into the root of your local Liferay Cloud repository:
curl -L https://github.com/LiferayCloud/stack-upgrade/archive/release.zip -O
unzip -j release.zip stack-upgrade-release/upgrade-workspace.sh -d path/to/project/folder
-
Run the upgrade script:
cd /path/to/project/folder
./upgrade-workspace.sh
-
Read the script’s starting output, and enter your project’s ID at the prompt:
Press enter to continue: Please enter your project id: lfrlearn
-
At the prompt, authenticate into the Liferay Cloud Console.
-
Enter the number corresponding to the Liferay version to use for your services:
1) 7.0 2) 7.1 3) 7.2 Please select the Liferay DXP version, which will determine the Liferay CLOUD image set in liferay/LCP.json and the Liferay image set in liferay/gradle.properties: 3
-
At the prompt, enter a comma-delimited list of the environments you use for your project files (not including
common
):Please enter a comma-delimited list of environments: dev,uat,prd
importantOnly enter the names of Liferay environments that you add files to in your project repository. Do not add the infrastructure (
infra
) environment. -
If you want to install Elasticsearch plugins to all of your Liferay environments, enter a comma-delimited list of their names at the prompt. Otherwise, press enter.
Please enter a comma-delimited list of elasticsearch plugins:
The script creates and checks out a new branch in your repository, with the upgrade script added to your
.gitignore
file. -
Verify that the script execution was successful by checking the new organization of your repository, with the service folders now on the root level:
repository ├── backup ├── build ├── ci ├── database ├── liferay ├── search ├── webserver └── upgrade-workspace.sh
Your repository is now reorganized into a structure where the liferay
folder is a Liferay Workspace, and your services are upgraded to 4.x.x.
Verify CI Service’s Environment Variables
The environment variables within your project’s ci/LCP.json
file may now behave differently after you have completed the service stack upgrade. Before continuing with your upgraded project, make sure that your ci
service’s environment variables reflect the correct configuration.
Verify Repository Integration Variables
Verify that the following properties are set up correctly for your project’s integration with version control (in this example, using GitHub):
{
"LCP_CI_SCM_PROVIDER": "github",
"LCP_CI_SCM_REPOSITORY_OWNER": "OWNER_NAME",
"LCP_CI_SCM_REPOSITORY_NAME": "PROJECT_NAME",
"LCP_CI_SCM_TOKEN": "AUTH_TOKEN"
}
See the GitHub, Bitbucket, or GitLab integration references for more information.
Verify Jenkinsfile Configuration Variables
Since a default Jenkinsfile is no longer required in your project, the Jenkinsfile at the root of your project may also be removed after the upgrade. If you intend to use the default Jenkinsfile for your project, ensure that the ci
services environment variables reflect this:
{
"LCP_CI_USE_DEFAULT_JENKINSFILE": "true",
"LCP_CI_SCM_JENKINSFILE_HOOKS_DIR": "ci/",
}
You must define the LCP_CI_SCM_JENKINSFILE_HOOKS_DIR
variable if you want to use hooks to extend the default Jenkinsfile.
If you are defining your own Jenkinsfile within your ci
service directory to override the default, then ensure your environment variables instead look like this:
{
"LCP_CI_USE_DEFAULT_JENKINSFILE": "false",
"LCP_CI_SCM_JENKINSFILE_PATH": "ci/Jenkinsfile"
}
Next Steps
After your local repository has changed, deploy the ci
service to the infra
environment. Deploying to the infra
environment before any others ensures that the changes to the ci
service are deployed first, which allows further changes to deploy correctly.
The quickest way to deploy only the ci
service is to use the CLI tool. Navigate to your project repository’s ci/
folder and run the lcp deploy
command:
lcp deploy --project=<project-name> --environment=infra
Alternatively, you can also follow the development workflow and deploy the changes as a build from the Liferay Cloud console.
You may then want to deploy the new service versions to a development environment, or explore some of the new functionality in the new versions of your Liferay Cloud services. See the explanation of the changes to learn more.