Developing Client Extensions in Liferay PaaS

Note: please note that Liferay has renamed its Liferay Experience Could offerings to Liferay SaaS (formerly LXC) and Liferay PaaS (formerly LXC-SM).

Introduction

This document provides a user manual for deploying client extensions on Liferay PaaS.

Prerequisites

Deployment Process Flow 

The following is a high level overview of the deployment process, you will need to complete those steps in order to to configure your micro - service client extension on Liferay PaaS and Liferay Self-Hosted.

Create Client Extension Workspace

Liferay Workspace is a set of folders and Gradle scripts that represents the Liferay-opinionated way of handling a full development life cycle:

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

Please refer to the the following documentation links in order to learn more about Liferay Workspaces and How to start a new one:

Configure Environment Variables “LCP.json”

The client extension needs to be deployed within your environment Liferay PaaS, encapsulated in a container. To configure your service, you'll retrieve the necessary settings from the container's environment variables. To achieve this, it's essential to identify the potential configuration keys and comprehend their usage within the microservice.

Variable Name Value (Type / Default Value)
COM_LIFERAY_LXC_DXP_DOMAINS comma delimited string
COM_LIFERAY_LXC_DXP_MAIN_DOMAIN string
COM_LIFERAY_LXC_DXP_SERVER_PROTOCOL string
LIFERAY_OAUTH_APPLICATION_EXTERNAL_REFERENCE_CODES comma delimited string
OAuth Server Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”
<ERC>_OAUTH2_AUTHORIZATION_URI string
<ERC>_OAUTH2_HEADLESS_SERVER_AUDIENCE string
<ERC>_OAUTH2_HEADLESS_SERVER_CLIENT_ID string
<ERC>_OAUTH2_HEADLESS_SERVER_CLIENT_SECRET string
<ERC>_OAUTH2_HEADLESS_SERVER_SCOPES comma delimited string
<ERC>_OAUTH2_INTROSPECTION_URI string
<ERC>_OAUTH2_JWKS_URI string
<ERC>_OAUTH2_TOKEN_URI string
OAuth Agent Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”
<ERC>_OAUTH2_AUTHORIZATION_URI string
<ERC>_OAUTH2_INTROSPECTION_URI string
<ERC>_OAUTH2_JWKS_URI string
<ERC>_OAUTH2_REDIRECT_URIS string
<ERC>_OAUTH2_TOKEN_URI string
<ERC>_OAUTH2_USER_AGENT_AUDIENCE string
<ERC>_OAUTH2_USER_AGENT_CLIENT_ID string
<ERC>_OAUTH2_USER_AGENT_SCOPES comma delimited string
The following are important keys if you are deploying the client extension on LXC
LIFERAY_ROUTES_CLIENT_EXTENSION /etc/liferay/lxc/extinitmetadata
LIFERAY_ROUTES_DXP /etc/liferay/lxc/dxpmetadata

 

To add the required environment variable to your service, you will need to add them to the LCP.JSON file:

<workspace>/<client-extensions>/<client-extension-project>/lcp.json

 

"env": {
"<Key 1>" : "<Default Value>",

 "<Key 2>" : "<Default Value>",

 "<Key 3>" : "<Default Value>",

 …

 "<Key n>" : "<Default Value>"
}

 

If you're deploying to a Self-Hosted environment or prefer not to utilize environment variables, you have the flexibility to transmit the configuration to your client extension through a flat file configuration method of your choice as long as you make sure to pass the required keys with the standard naming convention.

Build Client Extension

In this phase, you'll be required to build the client extension using the Gradle tasks specified within the Liferay Workspace. To accomplish this, refer to the documentation provided on Liferay Learn. Please note that you should only build it and refrain from deploying at this stage.

Go to your workspace’s client-extensions/ folder and run

../gradlew clean build

 

Once the build completed, you find your client extension built file under the following path:

<workspace>/<client-extensions>/<client-extension-project>/dist/<client-extension>.ZIP

Deploy Client Extension “Service”

The subsequent step involves deploying your microservice either to your Liferay PaaS or a Self-Hosted Environment. The primary objective of this step is to initiate your microservice. Therefore, the procedures outlined below will vary based on your specific environment configuration.

If you are using Liferay PaaS, then you will need to use the LCP Deploy Command line which will help you to create the docker image and container in your environment, read more about LCP Deploy on Liferay Learn.

lcp deploy --extension [extension-zip-file]

 

If you're deploying the service within your environment “Self Hosted”, ensure it's accessible from your DXP server.

Deploy Client Extension on DXP

In this phase, you'll set up the service within your DXP instance. However, note that this doesn't imply your service will be hosted or deployed on DXP. Instead, it focuses on establishing a connection between your microservice and the Liferay DXP instance. This connection is governed by the .YAML file you've generated in your microservice client extension.

In order to deploy the client extension on Liferay PaaS you will need to copy the build file “.ZIP” into your Liferay PaaS github repo on the following path:

Liferay/Configs/<Target Environment "PRD/UAT">/OSGI/client-extensions/

If you are deploying to DXP Self Hosted, you will need to copy the build file to the following path:

<Liferay Bundle>/OSGI/client-extensions/

 

Update Environment Variables Values

In the preceding step, you've effectively deployed your microservice to Liferay DXP, which will automatically generate the essential OAuth Applications (Agent/Server). Upon creation, you'll have access to specific key values. For the Agent type, you should copy the client ID, while for the Server type, you'll need both the Client ID and Client Secret.

 

Subsequently, replace these copied values with your service environment variables. If you're utilizing Liferay PaaS, you can accomplish this via the Liferay PaaS Console.

Sample Server OAuth

Sample Service Environment Variables Configuration Panel

 

If you're deploying to a Self-Hosted DXP environment, you'll need to update the configuration values either within your managed container environment variables  or within your flat configuration file.

Restart Client Extension Service

To apply the configuration modifications, you'll need to restart your service and verify its connectivity.

Sample Workspace

A prebuilt sample containing all the necessary configurations has been prepared for you. Please locate the sample code at the following URLs:

Please be aware that we've developed a configuration utility library to simplify the process of retrieving configuration keys. This library ensures the implementation of a failover mechanism, searching for configurations both in environment variables and configuration files.

Conclusion

This user manual has provided a step-by-step guide for deploying microservice client extensions on Liferay PaaS / Self Hosted.

By following these steps, you can successfully deploy your microservice and configure it with the necessary OAuth credentials, enabling secure communication with Liferay.

Was this article helpful?
1 out of 1 found this helpful