Development Setup Environment LIFERAY DXP 7.4

☁ LIFERAY DXP 7.4 Custom Development Environment Setup,

Setting up a Liferay DXP 7.4 development environment can feel overwhelming at first — multiple tools, workspac configurations, folder structures, and custom module scaffolding. This guide walks you through every step so you can get productive quickly.

Whether you're a seasoned Java developer new to the Liferay ecosystem, or a Liferay developer upgrading to 7.4, this blog covers everything you need to go from zero to deploying your first custom portlet.

1 · Prerequisites — Required Software

Before creating a Liferay workspace, make sure the following software is installed and configured on your development machine:

• JDK 11 or JDK 17 — DXP 7.4 supports both versions
• Java should be set to version 17 as the default (recommended)
• Gradle — comes bundled with the Liferay workspace; no separate install needed
• Node.js — required for frontend/client-extension modules
• Git — for version control and workspace management
• MySQL or PostgreSQL — as the portal database
• Apache Tomcat 9 — the default application server for DXP 7.4
• Blade CLI — the Liferay command-line tool for scaffolding projects

Set Java 17 as Default

Ensure Java 17 is active before running any Liferay commands:

• # Windows (set JAVA_HOME)
• set JAVA_HOME=C:\Program Files\Java\jdk-17
• set PATH=%JAVA_HOME%\bin;%PATH%
• # Verify
• java -version

2 · Create Liferay Workspace

A Liferay Workspace is a structured Gradle project that manages your DXP bundle, custom modules, themes, and configurations — all in one place.

Option A — Using Blade CLI (Recommended)

• blade init -v 7.4 dxp-workspace-demo
• cd dxp-workspace-demo

Option B — Using the Graphical Installer

If you prefer a GUI approach, download the Liferay Project SDK Installer from the official GitHub releases page and follow these steps:

• Run the installer — Java runtime will be auto-detected
• Click Next past the introduction screen
• Choose whether to initialize a Liferay Workspace immediately during install
• Set the workspace folder location if initializing now
• Select Liferay DXP or Community Edition as your product type
• Choose the product type and click Next
• Click Next to complete the Blade CLI installation

3 · Configure DXP 7.4 Product Version

After creating the workspace, open the file gradle.properties and verify or update the Liferay product line to match your target update version.

For Liferay DXP (Enterprise)

• # Open: gradle.properties
• liferay.workspace.product=dxp-7.4-u92
• # Replace u92 with your target update number, e.g., u100, u112 etc.

For Community Edition (CE)

liferay.workspace.product=portal-7.4-ga92

💡 Tip: Run 'blade update' to check available DXP product keys before choosing your version.

4 · Initialize the DXP Bundle

From inside your workspace folder (dxp-workspace-demo), run the bundle initialization command:

gradlew initBundle

This single command performs three important steps automatically:

• Downloads the DXP or CE distribution package
• Sets up Apache Tomcat as the embedded application server
• Creates the bundles/ folder — your local runtime environment

After completion, the bundles/ folder will appear in your workspace root. This is your Liferay Home directory.

5 · Folder & File Explanation (Liferay 7.4 Bundle)

Understanding the bundle folder structure is essential for day-to-day development, debugging, and production management. Here is a breakdown of every important directory:

data/

Stores all runtime data generated by Liferay during operation. This folder grows over time as content is added.

• Document Library files (uploaded documents, images, and media)
• Search indexes (Elasticsearch/Lucene data)
• HSQL in-memory database (if using the default embedded DB — not recommended for production)
• OSGi state cache (module states and configurations)

deploy/

The hot deploy folder. Any artifact you drop here is automatically picked up and deployed by the Liferay runtime — no restart required.

• JAR — OSGi module bundles (your custom portlets, services, hooks)
• WAR — traditional web archive format
• LPKG — Liferay Plugin Package (marketplace plugins)

📌 Note: This folder is mainly used for quick manual deployments during development. CI/CD pipelines typically deploy via the Gradle deploy task instead.

elasticsearch-sidecar/

The embedded Elasticsearch instance bundled inside Liferay DXP 7.4 for development convenience.

• Used when you are not connecting to an external Elasticsearch cluster
• Suitable only for local development and demos
• In production environments, always configure and connect to an external Elasticsearch cluster for performance, scalability, and reliability

glowroot/

Glowroot is a Java Application Performance Monitoring (APM) tool included with the DXP bundle for profiling and performance diagnostics.

• JVM-level performance tracking
• Thread monitoring and deadlock detection
• Memory usage profiling
• Enterprise teams use this for debugging slow portal pages and high memory usage issues

license/

Stores DXP enterprise license files (.xml format). Without a valid license, DXP runs in CE mode or may restrict enterprise features.

ℹ Info: This folder is not used in Community Edition (CE). Only relevant if you have a paid DXP license.

logs/

All server log output is written here. This is always the first place to look when the server fails to start, encounters errors, or behaves unexpectedly.

• liferay.log — portal-level log (startup, module activity, errors)
• catalina.out — Tomcat container-level log (JVM start, fatal errors)

osgi/

The heart of Liferay 7.4's modular architecture. This directory is where the OSGi container runtime lives and where all deployed modules reside.

• modules/ — your deployed custom bundles land here
• configs/ — OSGi component configuration files (.config)
• marketplace/ — marketplace plugin packages
• state/ — persisted OSGi bundle state

🔑 Key Point: When you run 'gradlew deploy', your JAR is copied into osgi/modules/. Liferay picks it up and registers it as an OSGi service without a restart.

routes/

Supports modern React and SPA (Single Page Application) front-end routing in Liferay 7.4. This folder is relevant when building Client Extensions or Remote Applications that use modern JavaScript frameworks.

tomcat/

The embedded Apache Tomcat 9 application server. All standard Tomcat sub-directories are present here:

• bin/ — startup/shutdown scripts (startup.bat, shutdown.bat)
• conf/ — Tomcat configuration (server.xml, context.xml, catalina.properties)
• lib/ — Tomcat shared libraries and JDBC drivers
• logs/ — Tomcat-specific logs (catalina.out)
• webapps/ — deployed web applications including the Liferay portal ROOT

• # Start the server from:
• bundles/tomcat/bin/startup.bat # Windows
• bundles/tomcat/bin/startup.sh # Linux / macOS

tools/

Contains internal utilities and scripts used by Liferay during initialization and maintenance. Generally, you do not need to modify anything here.

work/

Stores temporary compiled JSP files and the Tomcat work cache. If the server starts behaving strangely after a Liferay upgrade or module change, safely deleting this folder and restarting often resolves the issue.

🗑️ Safe to delete: The work/ folder is fully regenerated on the next server startup. Deleting it clears stale JSP compilations and Tomcat cache.

6 · Important Root Files

At the root of the bundles folder, several hidden and configuration files play critical roles:

File	Purpose
.liferay-home	Marks this directory as the Liferay Home root. Liferay uses this marker to locate bundles, configs, and data.
.liferay-version	Stores the currently installed portal version string for internal reference.
.githash	Internal build hash reference used for tracking which exact build of Liferay is installed.
portal-ext.properties	⭐ The most important customization file. Used to override defaults for database, mail server, LDAP, CAS SSO, clustering, caching, and much more.

portal-ext.properties — What You Can Override

• Database connection (JDBC driver, URL, username, password)
• Mail server configuration (SMTP host, port, authentication)
• CAS / SAML / LDAP authentication settings
• Cluster node configuration (JGroups, cache)
• Cache settings (Ehcache, Infinispan)
• Custom portal properties (admin email, default locale, etc.)

7 · Configure the Database

By default, Liferay uses an embedded HSQL database — fine for initial startup, but not for real development. Configure a proper MySQL or PostgreSQL database using portal-ext.properties:

MySQL Configuration (portal-ext.properties)

• jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
• jdbc.default.url=jdbc:mysql://localhost:3306/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
• jdbc.default.username=root
• jdbc.default.password=yourpassword

Alternatively, you can configure the database via the OSGi config file:

• # Edit file:
• bundles/osgi/configs/com.liferay.portal.store.db.configuration.DBStoreConfiguration.config

⚠️ Important: Create the 'lportal' database in MySQL before starting Liferay. On first startup, Liferay auto-creates all tables and seeds initial data.

8 · Start the DXP Server

With the database configured and the bundle initialized, start the Liferay DXP server:

• cd bundles/tomcat/bin
• startup.bat # Windows
• # OR
• ./startup.sh # Linux / macOS

Once the server is running, open a browser and navigate to:

http://localhost:8080

The first-time setup wizard will ask you to configure the administrator account, portal name, and database connection (if not already set in portal-ext.properties).

💡 Watch the logs: Tail bundles/logs/liferay.log to monitor startup progress. A successful startup ends with: 'org.apache.catalina.startup.Catalina start — Server startup in XXXX ms'

9 · Create a Custom Module (MVC Portlet)

Liferay DXP 7.4 uses an OSGi-based modular architecture. Every custom feature — portlet, service, hook, or theme — is packaged as an OSGi bundle (JAR). The simplest starting point is the mvc-portlet template.

Step 1 — Scaffold the Module

blade create -t mvc-portlet -p com.sgc.demo demo-portlet

Blade CLI generates a complete, ready-to-deploy project structure:

• demo-portlet/
• ├── bnd.bnd # OSGi bundle metadata (Bundle-SymbolicName, version, etc.)
• ├── build.gradle # Module build config (dependencies, deploy task)
• └── src/
• └── main/
• ├── java/
• │ └── com/sgc/demo/
• │ └── DemoPortlet.java # Main portlet class
• ├── resources/
• │ └── content/
• │ └── Language.properties
• └── webapp/
• ├── css/
• ├── js/
• └── WEB-INF/
• └── view.jsp # Default portlet view

Step 2 — Deploy the Module

With the DXP server running, deploy your portlet using either of these commands:

• # Deploy all modules
• gradlew deploy
• 
  
• # Deploy a specific module only
• gradlew :modules:demo-portlet:deploy

Gradle builds the JAR and copies it to the deploy/ hot folder. Liferay picks it up, registers it in the OSGi container, and makes it available in the portlet widget menu — no server restart needed

✅ Verify Deployment: Check the liferay.log file for 'STARTED com.sgc.demo_1.0.0' — this confirms your OSGi bundle was registered successfully.

10 · Quick Reference — Key Commands

Command	Description
blade init -v 7.4 <name>	Create a new Liferay workspace targeting DXP 7.4
gradlew initBundle	Download and initialize the DXP/CE bundle inside the workspace
gradlew deploy	Build and deploy all modules to the running portal
gradlew :modules:<name>:deploy	Build and deploy a single specific module
startup.bat / startup.sh	Start the embedded Tomcat server (from bundles/tomcat/bin/)
shutdown.bat / shutdown.sh	Stop the embedded Tomcat server
blade create -t mvc-portlet -p ...	Scaffold a new MVC Portlet module using Blade CLI

🎉 Happy Coding with Liferay DXP 7.4!