Announcements

Developing Client Extensions in Liferay PaaS

1/4/24 10:58 AM


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.

Note: This is a temporary approach for deploying client extensions on PaaS. We are actively developing features that will enable PaaS users to utilize Liferay Cloud’s CI/CD for this operation in the near future.

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 NameValue (Type / Default Value)
COM_LIFERAY_LXC_DXP_DOMAINScomma delimited string
COM_LIFERAY_LXC_DXP_MAIN_DOMAINstring
COM_LIFERAY_LXC_DXP_SERVER_PROTOCOLstring
LIFERAY_OAUTH_APPLICATION_EXTERNAL_REFERENCE_CODEScomma delimited string
OAuth Server Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”OAuth Server Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”
_OAUTH2_AUTHORIZATION_URIstring
_OAUTH2_HEADLESS_SERVER_AUDIENCEstring
_OAUTH2_HEADLESS_SERVER_CLIENT_IDstring
_OAUTH2_HEADLESS_SERVER_CLIENT_SECRETstring
_OAUTH2_HEADLESS_SERVER_SCOPEScomma delimited string
_OAUTH2_INTROSPECTION_URIstring
_OAUTH2_JWKS_URIstring
_OAUTH2_TOKEN_URIstring
OAuth Agent Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”OAuth Agent Application(s) Configurations, the following configuration should be prefixed with your OAuth Server ERC “External Reference Code”
_OAUTH2_AUTHORIZATION_URIstring
_OAUTH2_INTROSPECTION_URIstring
_OAUTH2_JWKS_URIstring
_OAUTH2_REDIRECT_URISstring
_OAUTH2_TOKEN_URIstring
_OAUTH2_USER_AGENT_AUDIENCEstring
_OAUTH2_USER_AGENT_CLIENT_IDstring
_OAUTH2_USER_AGENT_SCOPEScomma delimited string
The following are important keys if you are deploying the client extension on LXCThe 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:

///lcp.json
“env”: { “<Key 1>” : “”, “<Key 2>” : “”, “<Key 3>” : “”, … “” : “” }

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:

///dist/.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:

/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.