Building Liferay DXP from Source

Build Liferay DXP from source when you’re contributing changes or when you need a fix that hasn’t shipped in a published release. The liferay-portal repository contains the source code for Liferay DXP. Building from source produces a Liferay DXP bundle.

If you previously ran Liferay Portal CE and need a pre-built bundle, see Liferay DXP Free Tier. To build from source, follow the steps below.

Prerequisites

Install these tools before building:

• JDK 17 (or JDK 21)
• Apache Ant 1.10.14 or higher
• Git
• Liferay Blade CLI (only needed if you plan to build client extensions or OSGi modules)

The build uses the included Gradle wrapper, so you don’t need to install Gradle separately.

Build Steps

1. Create a working directory and cd into it. You clone two repositories side-by-side here:

   mkdir liferay-dev
   cd liferay-dev
   

2. Optionally clone the liferay-binaries-cache-2020 repository to speed up builds. Without it, the build downloads dependencies on demand.

   git clone https://github.com/liferay/liferay-binaries-cache-2020 --branch master --single-branch --depth 1
   

3. Fork liferay/liferay-portal on GitHub.

4. Clone your fork next to liferay-binaries-cache-2020:

   git clone https://github.com/[your-github-user]/liferay-portal
   cd liferay-portal
   

5. Add the upstream repository so you can fetch changes from liferay/liferay-portal:

   git remote add upstream https://github.com/liferay/liferay-portal
   

6. Build:

   ant all
   

   The bundle is unpacked into ../bundles/ and contains a Tomcat application server with Liferay DXP deployed.

To verify the build, list ../bundles/. You should see a tomcat-[version] directory (for example, tomcat-10.1.54). Start the bundle:

../bundles/tomcat-[version]/bin/startup.sh

Then visit http://localhost:8080.

Customizing the Build

app.server.properties and build.properties document the build’s defaults: application server type, bundle location, ant flags, and similar options. To override a default, create a sibling user-specific file: app.server.[user-name].properties or build.[user-name].properties. The build picks up your overrides automatically and your changes stay isolated from upstream updates.

Deploying Core Changes

After the bundle is built, you can rebuild and deploy Liferay DXP core projects (such as portal-impl or portal-kernel) without a full rebuild. Core components aren’t hot-swappable, so restart the bundle after each deploy.

1. Start the bundle if it isn’t already running:

   ../bundles/tomcat-[version]/bin/startup.sh
   

2. Rebuild and deploy. From the liferay-portal directory, ant deploy redeploys all core projects. To redeploy a single project, cd into its directory first:

   cd portal-impl
   ant deploy
   

3. Restart the bundle to pick up the change:

   ../bundles/tomcat-[version]/bin/shutdown.sh
   ../bundles/tomcat-[version]/bin/startup.sh
   

Deploying a Module

You can build and deploy a single OSGi module or client extension without recompiling the platform. Complete the build steps before deploying modules so the build environment is initialized.

1. From the module’s directory, run:

   blade gw deploy
   

   blade gw is shorthand for the project’s Gradle wrapper (./gradlew). It deploys the module to the running bundle’s osgi/ subtree.

To confirm a successful deploy, check the bundle log at ../bundles/tomcat-[version]/logs/catalina.out. Look for a STARTED <module-name> entry, similar to:

INFO [fileinstall][BundleStartStopLogger] STOPPED com.liferay.portal.workflow.web_3.0.0
INFO [Refresh Thread: Equinox Container][BundleStartStopLogger] STARTED com.liferay.portal.workflow.web_3.0.0

Contributing Changes Back to Liferay

Track your changes against a Jira ticket and submit them as a GitHub pull request.

Filing a Jira Ticket

1. Sign up for a Jira account.

2. Submit a ticket for your issue. Describe the issue clearly. For bugs, include reproduction steps.

3. Select an appropriate category for the issue.

4. Select the earliest version of the product affected by the issue.

5. Accept the Contributor License Agreement that appears when you click Contribute Solution.

If a ticket already exists for the issue, participate via the existing ticket instead of opening a new one.

Submitting a Pull Request on GitHub

1. Create a topic branch off the latest upstream/master so your work stays isolated from your fork’s master:

   git fetch upstream
   git checkout -b my-change upstream/master
   

2. Commit logical units of work, referencing the Jira ticket key. For example: LPS-83432 Make the example in CONTRIBUTING imperative and concrete.

3. Test your changes thoroughly. Liferay DXP supports many operating systems, databases, and application servers. Make sure your changes don’t break a configuration you haven’t tested.

4. Before pushing, rebase on the latest upstream master:

   git fetch upstream
   git rebase upstream/master
   

5. Push your branch to your fork:

   git push origin my-change
   

6. Submit the pull request to the liferay/liferay-portal repository.

7. In the Jira ticket, link to your pull request.

After you submit the pull request, respond to questions and review comments until it’s merged or closed.