How Can We Help?
< All Topics
Print

Code build and deployments

Introduction

Welcome to Firelay’s Liferay Cloud. Firelay’s Liferay Cloud is a Platform as a Service (PaaS) that offers smoothly running Liferay portals at competitive pricing. It has the same level of quality, dependability, and similar features as Liferay’s native cloud. Additionally it offers support for earlier Liferay versions and Liferay Community Edition on top of that.

Pre-requisites

Git repository

Supported services GitLab, Bitbucket, Azure Repos. It can be a Firelay-provided repository or a customer-owned repository.

It is required to have an active development branch (recommended name main) and a release branch (recommended name production or live)

Liferay workspace

It is required to have a project initialized with the default Liferay workspace folder structure. Complete documentation for Liferay Workspace can be found here

my-project
├── configs
│ ├── common
│ ├── dev
│ ├── docker
│ ├── local
│ ├── prod
│ └── uat
│ └── artifacts-release.json
├── modules
│ ├── java widgets
├── wars
│ ├── traditional WAR-style web applications and themes
└── themes
└── js themes

Additionally, a JSON file configs/artifacts-release.json must be added to manage the list of artifacts that will be published.

Note: The Liferay workspace contains more folders and files not listed in the previous code snippet. We have listed only the required folder/files needed for the code build trigger.

SSH Public Keys

A pair of public-private keys will be generated to be able to connect the repository to the cloud build triggers. Firelay will provide the public key to the customers to be configured by them if the repository belongs to them.

Webhook configuration

To trigger automatic builds for the Development Workflow and the Release Workflow, two webhook must be configured in the git repository. Firelay will provide the necessary webhook information to the customers.

Development Workflow

The objective of this workflow is to provide customers with a standardized development life-cycle allowing them to release new versions of their artifacts.

The customers are free to use any Git workflow they like, the only requirement for the automatic build and deployments is the presence of an active development branch (referred also to as main) and a release branch (referred also to as production or live).

General Overview

The Development Workflow is initiated when changes of any type are pushed into the main branch. The workflow is divided into three steps.

  1. Liferay Workspace code build

    A trigger instance will clone the repository, then it will compile the Liferay workspace. The built artifacts will be uploaded to a Maven-type repository.
  2. Image Build

    A trigger instance will clone the repository, then it will copy the configurations from the Liferay workspace folder [liferay_workspace]/configs into the new image. It will also search for the release configuration file configs/artifacts-release.json and download all the artifacts configured in it. The image will be tagged as latest and it will be pushed into a Docker-type repository.
  3. Image Deployment

    A trigger instance will fetch the new image tagged as latest and it will deploy it in the dev environment.

Supported artifacts

jar/zip

Any module that is compiled into a jar or zip file under the [liferay_workspace]/modules folder.

war

Any module that is compiled into a war file under the [liferay_workspace]/themes & [liferay_workspace]/wars folders.

It is a requirement to follow the semantic versioning guidelines for generating the next version of your modules.

For Java modules edit the bnd.bnd file and increment the Bundle-Version line accordingly.

Bundle-Name: test-api
Bundle-SymbolicName: com.liferay.test.api
Bundle-Version: 1.0.0
.....

For front-end modules edit the package.json file and edit the property version.

{
....
"name": "test-theme",
"version": "1.0.0"
....
}

How to release an artifact

1. Set the appropriate version for your module

2. Edit the configs/artifacts-release.json file and add the coordinates for the artifacts that will be included in the image

[
{
"groupId": "com.liferay",
"artifactId": "com.liferay.test.api",
"version": "1.0.0",
"extension": "jar"
},
{
"groupId": "com.liferay",
"artifactId": "test-theme",
"version": "1.0.0",
"extension": "war"
},
{
"groupId": "com.liferay",
"artifactId": "com.liferay.override.core.module",
"version": "1.0.0",
"extension": "jar",
"override": "com.liferay.portal.security.sso.openid.connect.impl.jar"
}
]

Coordinates explanation

groupId: arbitrary group, usually your company domain name reversed

artifactId: For Java modules, the Bundle-SymbolicName value from the bnd.bnd file. For Themes the name value from the package.json file.

version: For Java modules, the Bundle-Version value from the bnd.bnd file. For Themes the version value from the package.json file.

extension: The extension of the artifact generated after running the Gradle task ./gradlew clean assemble in your local development environment.

override: (Optional, default=false) If this property is present the module will be renamed to the value of this property and will be placed in the [liferay_workspace]/marketplace/override. Additional information can be found in Extending Liferay OSGi Modules Revisited, Extending Liferay OSGi Modules and Overriding OSGi Services.

Release Workflow

The objective of this workflow is to provide customers with an easy-to-use release cycle allowing them to deploy new versions of their artifacts in any non-development environment (uat, prod).

It is required to have a stable branch (recommended name production or live) from where the tags will be based.

Due to the nature of the tags, it is important to understand the content of the image will be based on the content of the configurations located at [liferay_workspace]/configs and the content of the configs/artifacts-release.json release file. For this reason, it is strongly recommended to create tags based on the stable branch. Any update in the configurations files (properties, OSGi config files) should be also updated in both the development and the release branches (main & production or live)

The tag name must follow the semantic version guidelines MAJOR.MINOR.PATCH e.g: 1.0.0

  1. MAJOR version when you make incompatible API changes
  2. MINOR version when you add functionality in a backwards-compatible manner
  3. PATCH version when you make backwards-compatible bug fixes

General Overview

The Release Workflow is initiated when a new tag is pushed into the repository. The workflow is divided into two steps.

  1. Image Build

    A trigger instance will clone the repository and checkout the tag that was pushed, then it will copy the configurations from the Liferay workspace folder [liferay_workspace]/configs into the new image. It will also search for the release configuration file configs/artifacts-release.json and download all the artifacts configured in it. The image will be tagged with the name of the git tag and it will be pushed into a Docker-type repository.
  2. Image Deployment

    A trigger instance will fetch the new image tagged with the name of the git tag and it will deploy it in the uat environment.

    Note: Production deployments will be performed by a support agent following a customer request to deploy a specific image version.
Table of Contents