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:

You must have a separate pipeline for client extensions to deploy them.

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.include file:

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.conf file 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