Development Lifecycle for a Liferay Workspace

Liferay Workspaces provide an environment that supports all phases of a Liferay module’s development lifecycle:

• Creating projects
• Building projects
• Deploying projects
• Testing projects
• Releasing projects

In this tutorial, you’ll explore the development lifecycle phases Liferay Workspace provides for you. Then you’ll be directed to other tutorials that go into further detail for leveraging the workspace’s particular lifecycle phase for a specific tool (e.g., Blade CLI or Liferay Dev Studio DXP). Let’s get started!

Creating Projects

The first step of Liferay Workspace’s development phase is the project creation process. Workspace provides a slew of templates that you can use to create many different types of Liferay projects. Workspace also provides development support for frontend portlets generated with the Liferay JS Toolkit. They’re stored in the modules folder by default.

You can configure where your workspace creates modules by editing the liferay.workspace.modules.dir property in the workspace’s gradle.properties file. By default, modules are created in the [ROOT]/modules folder.

You can also control where themes are generated by specifying the liferay.workspace.themes.dir property in the gradle.properties file. Themes are typically migrated to the themes folder after being created using the Liferay Theme Generator.

Workspace also provides a way to create WAR projects, which are generated in the folder set by the liferay.workspace.wars.dir property in the gradle.properties file. There are several project templates that create WAR-style projects, which should be stored in the wars folder.

To learn more about creating projects in a workspace using Blade CLI or Liferay Dev Studio, visit the Creating Projects with Blade CLI and Creating Modules with Liferay Dev Studio tutorials, respectively.

Building Projects

Liferay Workspace abstracts many build requirements away so you can focus on developing projects instead of worrying about how to build them. Liferay Workspace is built using Gradle, so your projects leverage the Gradle build lifecycle.

Workspace includes a Gradle wrapper in its ROOT folder (e.g., gradlew), which you can leverage to execute Gradle commands. This means that you can run familiar Gradle build commands (e.g., build, clean, compile, etc.) from a Liferay Workspace without having Gradle installed on your machine.

Note: You can also use the workspace’s Gradle wrapper by executing blade gw followed by the Gradle command. This is an easier way to run the workspace’s Gradle wrapper without specifying its path. Since the workspace’s Gradle wrapper resides in its root folder, it can sometimes be a hassle running it for a deeply nested module (e.g., ../../../../gradlew compileJava). Running the Gradle wrapper from Blade CLI automatically detects the Gradle wrapper and can run it anywhere.

When using Liferay Workspace, the workspace plugin is automatically applied which adds a multitude of subprojects for you, hiding some complexities of Gradle. For example, a typical project’s settings.gradle file could contain many included subprojects like this:

...
include images:base:oracle-jdk:oracle-jdk-6
include images:base:oracle-jdk:oracle-jdk-7
include images:base:oracle-jdk:oracle-jdk-8
include images:base:liferay-portal:liferay-portal-ce-tomcat-7.1-ga1
include images:source-bundles:glassfish
include images:source-bundles:jboss-eap
include images:source-bundles:tomcat
include images:source-bundles:websphere
include images:source-bundles:wildfly
include compose:jboss-eap-mysql
include compose:tomcat-mariadb
include compose:tomcat-mysql
include compose:tomcat-mysql-elastic
include compose:tomcat-postgres
include file-server
...

You don’t have to worry about applying these subprojects because the workspace plugin does it for you. Likewise, if a folder in the /themes folder includes a liferay-theme.json file, the gulp plugin is applied to it; if a folder in the /modules folder includes a bnd.bnd file, the liferay-gradle plugin is applied to it. See the Gradle reference article for a list of Liferay Gradle plugins automatically provided for all Workspace apps. As you can see, Liferay Workspace provides many plugins and build configurations behind the scenes to make your development process convenient.

A good example of the Gradle build lifecycle abstraction is the project deployment process in a workspace. You can build/deploy your modules from workspace without ever running a Gradle command. You’ll learn how to do this next.

Deploying Projects

Liferay Workspace provides easy-to-use deployment mechanisms that let you deploy your project to a Liferay server without any custom configuration. To learn more about deploying projects from a workspace using Blade CLI or Liferay Dev Studio DXP, visit the Deploying Projects with Blade CLI and Deploying Modules with Liferay Dev Studio DXP tutorials, respectively.

Testing Projects

Liferay provides many configuration settings for Liferay DXP 7.1. Configuring several different Liferay DXP installations to simulate/test certain behaviors can become cumbersome and time consuming. With Liferay Workspace, you can easily organize environment settings and generate an environment installation with those settings.

Liferay Workspace provides the configs folder, which lets you configure different environments in the same workspace. For example, you could configure separate Liferay DXP environment settings for development, testing, and production in a single Liferay Workspace. So how does it work?

The configs folder offers five subfolders:

• common: holds a common configuration that you want applied to all environments.
• dev: holds the development configuration.
• local: holds the configuration intended for testing locally.
• prod: holds the configuration for a production site.
• uat: holds the configuration for a UAT site.

You’re not limited to just these environments. You can create any subfolder in the configs folder (e.g., aws, docker, etc.) to simulate any environment. Each environment folder can supply its own database, portal-ext.properties, Elasticsearch, etc. The files in each folder overlay your Liferay DXP installation, which you generate from within workspace.

Figure 1: The `configs/common` and `configs/[environment]` overlay you Liferay DXP bundle when it's generated.

When workspace generates a Liferay DXP bundle, these things happen:

1. Configuration files found in the configs/common folder are applied to the Liferay DXP bundle.

2. The configured workspace environment (dev, local, prod, uat, etc.) is applied on top of any existing configurations from the common folder.

To generate a Liferay DXP bundle with a specific environment configuration to the workspace’s /bundles folder, run

./gradlew initBundle -Pliferay.workspace.environment=[ENVIRONMENT]

To generate a distributable Liferay DXP installation to the workspace’s /build folder, run

./gradlew distBundle[Zip|Tar] -Pliferay.workspace.environment=[ENVIRONMENT]

The ENVIRONMENT variable should match the configuration folder (dev, local, prod, uat, etc.) you intend to apply.

Note: You may prefer to set your workspace environment in the gradle.properties file instead of passing it via Gradle command. If so, it’s recommended to set the workspace envrionment variable inside the [USER_HOME]/.gradle/gradle.properties file.

liferay.workspace.environment=local

The variable is set to local by default.

To simulate using the configs folder, let’s explore a typical scenario. Suppose you want a local Liferay DXP installation for testing and a UAT installation for simulating a production site. Assume you want the following configuration for the two environments:

Local Environment

• Use MySQL database pointing to localhost
• Skip setup wizard

UAT Environment

• Use MySQL database pointing to a live server
• Skip setup wizard

To configure these two environments in your workspace, follow the steps below:

1. Open the configs/common folder and add the portal-setup-wizard.properties file with the setup.wizard.enabled=false property.

2. Open the configs/local folder and configure the MySQL database settings for localhost in a portal-ext.properties file.

3. Open the configs/uat folder and configure the MySQL database settings for the live server in a portal-ext.properties file.

4. Now that your two environments are configured, generate one of them:

   ./gradlew distBundle[Zip|Tar] -Pliferay.workspace.environment=uat
   

   You’ve successfully configured two environments and generated one of them.

Awesome! You can now test various Liferay DXP bundle environments using Liferay Workspace.

Releasing Projects

Liferay Workspace does not provide a built-in release mechanism, but there are easy ways to use external release tools with workspace. The most popular choice is uploading your projects to a Maven Nexus repository. You could also use other release tools like Artifactory.

Uploading projects to a remote repository is useful if you need to share them with other non-workspace projects. Also, if you’re ready for your projects to be in the spotlight, uploading them to a public remote repository gives other developers the chance to use them.

For more instructions on how to set up a Maven Nexus repository for your workspace’s projects, see the Creating a Maven Repository and Deploying Liferay Maven Artifacts to a Repository tutorials.