Introduction
This document provides a user manual for deploying client extensions on Liferay PaaS.
Prerequisites
- Access to Liferay PaaS
- Liferay Command Line Interface (LCP) installed
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 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.