Configuring Liferay PaaS for Client Extensions
Beta Feature
Client extensions are the ideal way to deploy various customizations and changes to Liferay DXP in cloud environments. Here are some configuration requirements for Liferay PaaS when you work with client extensions.
Client Extension Build Pipeline
To use client extensions, your environment must have two build pipelines present in your infra environment:

If you don’t have an extra pipeline for client extensions, contact Liferay Cloud Support to enable client extensions for your environment.
Required Service Versions
If your environment uses out-of-date cloud service versions, you cannot use client extensions in Liferay PaaS. You must update your services (via their LCP.json files) if they are older than these versions:
- CI Service: liferaycloud/jenkins:2.479.2-lts-jdk21-6.0.0
- Liferay Service: liferaycloud/liferay-dxp:7.4-5.8.4
In your project workspace’s liferay/gradle.properties file, you must also verify that Liferay DXP is configured to use at least version 2024.q2.0 (with the liferay.workspace.docker.image.liferay property).
Redeploy the Liferay DXP service after updating all of your services before you attempt to deploy any client extensions.
Web Server Configurations
By default, all non-production environments in Liferay PaaS require basic authentication (via your web browser) to access. This requirement secures your development environments so only developers for your site can view it.
However, the basic authentication requirement also prevents client extensions from communicating between your services by default. You can configure an exception on your web server so client extensions can bypass this constraint.
-
In your project’s repository, navigate to the
webserver/configs/<ENV>/conf.d/folder for the desired environment (e.g.,webserver/configs/dev/conf.d/). -
Add a new file called
proxy.include.touch proxy.include -
Copy and save these contents to the
proxy.includefile:proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto; proxy_set_header X-Forwarded-Port $http_x_forwarded_port; proxy_set_header Host $host; proxy_set_header X-Real-IP $http_x_forwarded_for; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $http_connection; proxy_hide_header liferay-portal; proxy_pass http://upstream_server; proxy_http_version 1.1; proxy_intercept_errors on; -
In the same folder, edit the
liferay.conffile and replace the contents with this:location /o { include /etc/nginx/conf.d/proxy.include; } location / { auth_basic "Authentication Required"; auth_basic_user_file /var/www/html/.htpasswd; include /etc/nginx/conf.d/proxy.include; } -
Save and commit these changes to your repository.
git commit -m "Configure dev web server for client extensions." -
Push and deploy the build using your normal workflow to the chosen environment.
When the build completes, the web server is configured to allow client extensions to communicate with the Liferay DXP service.
Incompatible Liferay DXP Configurations
Certain configurations for Liferay DXP are incompatible with client extensions. Remove these configurations to avoid issues when you deploy client extensions to the environment.
Environment Variables
LIFERAY_COMPANY_PERIOD_DEFAULT_PERIOD_VIRTUAL_PERIOD_HOST_PERIOD_NAME
LIFERAY_COMPANY_PERIOD_DEFAULT_PERIOD_VIRTUAL_PERIOD_HOST_PERIOD_SYNC_PERIOD_ON_PERIOD_STARTUP
LIFERAY_MODULE_PERIOD_FRAMEWORK_PERIOD_PROPERTIES_PERIOD_ORG_PERIOD_APACHE_PERIOD_FELIX_PERIOD_CONFIGADMIN_PERIOD_PLUGIN_PERIOD_INTERPOLATION_PERIOD_SECRETSDIR
LIFERAY_VIRTUAL_PERIOD_HOSTS_PERIOD_VALID_PERIOD_HOSTS
LIFERAY_WEB_PERIOD_SERVER_PERIOD_PROTOCOL
OSGi Configurations
"com.liferay.portal.http.internal.configuration.HttpConfiguration",
"com.liferay.portal.k8s.agent.override.OverridePortalK8sAgentConfiguration",
"com.liferay.portal.workflow.configuration.WorkflowDefinitionConfiguration"
Portal Properties
company.default.virtual.host.name
company.default.virtual.host.sync.on.startup
module.framework.properties.org.apache.felix.configadmin.plugin.interpolation.secretsdir
virtual.hosts.valid.hosts
web.server.protocol
Targeting a Specific Virtual Instance
The name of the Git branch a client extension is built from determines which virtual instance receives it. To target a virtual instance other than the default, end the branch name with an underscore and the instance’s ID, such as prd_clarity. Use this feature when one PaaS environment hosts several virtual instances and a client extension must reach only one of them. Targeting works for every client extension type: frontend, configuration, batch, and microservice.
Before you target a virtual instance, you must have
- An environment with the client extension build pipeline
- A target virtual instance whose ID contains no underscore (
_)
Naming the Branch
A virtual instance’s ID is its Web ID, which you set when you add the instance. Liferay PaaS reads everything after the last underscore in the branch name as the virtual instance ID and ignores everything before it. For this reason, you can’t target a virtual instance whose ID contains an underscore. A branch name with no underscore targets the default virtual instance.
These branch names show which virtual instance each build targets:
| Branch name | Target virtual instance |
|---|---|
master | Default virtual instance |
prd | Default virtual instance |
prd_clarity | clarity |
dev_clarity.example.com | clarity.example.com |
feature_dev_clarity | clarity |
If no virtual instance in the environment has an ID that matches the text after the branch name’s last underscore, the deployment fails. The Liferay Cloud console shows a virtualInstanceNotFound error that lists the environment’s virtual instances. For example, a client extension built from a branch named feature_login fails to deploy unless the environment has a virtual instance with the ID login. To fix the deployment, push the client extension to a branch whose name ends with an underscore and one of the listed IDs, or contains no underscore. Then deploy the new build.
To deploy the same client extension to more than one virtual instance, push a separate branch for each instance, such as prd_clarity and prd_example. Each client extension runs as a service, and a service targets only one virtual instance. Give the client extension a different service ID on each branch, so that deploying it to one virtual instance doesn’t replace the service running in another.
The id in the LCP.json file in the client extension’s project folder sets its service ID. A microservice client extension’s build requires this file. A frontend, batch, or configuration client extension without the file takes its service ID from the folder name. The folder name is converted to lowercase, and all characters other than letters and digits are removed, so a project in my-extension runs as myextension.
Deploying to a Virtual Instance
-
In your project’s Git repository, create a branch whose name ends with
_[virtualInstanceId], where[virtualInstanceId]is the target virtual instance’s Web ID. -
If you deploy the same client extension to more than one virtual instance, give it a different service ID on each branch. Set the
idin theLCP.jsonfile in the client extension’s project folder, such asmy-extension-exampleon theprd_examplebranch, and create the file if the folder has none. -
Commit the client extension and push the branch to your Git repository.
The build appears on the Builds page in the Liferay Cloud console.
-
Deploy the build to the environment that hosts the virtual instance.
When the deployment completes, the client extension appears in the environment as a new service.
-
For a frontend client extension, open the Global Menu (
) in the target virtual instance and go to Applications → Client Extensions.The client extension appears in the list.