Posted inDXP Liferay Liferay 7 Web

Master Liferay DXP Workspace Setup: Proven Steps to Build Faster with Blade, Gradle, and Docker

liferay-workspace-setup

Why a Liferay Workspace?

A Workspace standardizes your project structure (modules, themes, configs), ties dependencies to a Target Platform BOM, and streamlines deploys to a local bundle or Docker.

1) Prerequisites

  • Java: JDK 11 or 17 (match your DXP 7.4 update level) java -version echo $JAVA_HOME
  • Node.js (only if you’ll build JS/React modules later): node -v
  • Gradle Wrapper is provided by the workspace (no global Gradle needed).
  • Docker (optional path): docker --version

Tip: Prefer JDK 17 for the latest 7.4 updates if your stack supports it.

2) Install Blade CLI

Blade scaffolds workspaces and modules.

macOS / Linux (Homebrew):

brew install liferay/blade/blade

Manual (any OS):

curl -L https://releases.liferay.com/tools/blade-cli/latest/blade.jar -o blade.jar
alias blade="java -jar $(pwd)/blade.jar"
blade -v

3) Create the Workspace (DXP 7.4)

mkdir liferay-workspace && cd liferay-workspace
blade init -v 7.4 .

This generates:

configs/          # Environment configs (dev, uat, prod)
gradle/           # Gradle wrapper files
modules/          # OSGi modules live here
themes/           # Themes
wars/             # Optional WAR projects
gradle.properties # Workspace settings (important)
settings.gradle

4) Pin Your Target Platform (BOM)

Open gradle.properties and set these keys (adjust the update level as needed):

# Choose a concrete 7.4 update (example: U100 - replace with your current)
liferay.workspace.product=dxp-7.4-u100
liferay.workspace.target.platform.version=7.4.13.u100

# Where your local bundle will live
liferay.workspace.home.dir=bundles

# (Optional) enable Docker defaults if you use Docker frequently
# liferay.workspace.docker.image.liferay=liferay/dxp:7.4.13-u100

The Target Platform locks dependency versions for all modules—fewer mismatches, easier upgrades.

5) Download a Local Bundle (initBundle)

Let Gradle fetch and lay out the app server + portal into /bundles.

./gradlew initBundle

This creates:

bundles/
 ├── tomcat-*/bin
 ├── deploy/
 └── osgi/

6) Start the Portal

Option A — Start Tomcat directly

./bundles/tomcat-*/bin/catalina.sh run     # macOS/Linux
# or
.\bundles\tomcat-*\bin\catalina.bat run    # Windows

Option B — Use Blade (nice shortcuts)

blade server start
# later
blade server stop

First boot seeds the database. Log in at http://localhost:8080 and complete setup.

7) Create Your First Module

Let’s scaffold a simple MVC portlet:

cd modules
blade create -t mvc-portlet -p com.acme.hello -c HelloPortlet hello-web

Build & deploy:

cd ..
./gradlew :modules:hello-web:deploy

Gradle copies the JAR to bundles/deploy/, OSGi auto-installs it.
Add the Hello Web app to a page via Site Builder → Pages → Add Application.

8) Using Docker Instead of a Local Bundle (Optional)

If you prefer Docker, set the image in gradle.properties (example already shown), then:

./gradlew createDockerContainer
./gradlew startDockerContainer

Deploy to Docker:

./gradlew :modules:hello-web:deploy

The workspace Gradle tasks bind the container’s deploy directory so your modules hot-install.

9) Project Anatomy (Quick Tour)

  • modules/ – OSGi modules (portlets, services, rest-builder, fragments)
  • themes/ – Theme projects (yo liferay-theme or Blade theme templates)
  • configs/ – Environment configs (dev, uat, prod) → put portal-ext.properties, system configs (.config) by environment
  • bundles/ – Local portal runtime (created by initBundle)

10) Workspace Quality Settings

Add to gradle.properties to speed builds and keep output tidy:

org.gradle.caching=true
org.gradle.parallel=true
org.gradle.daemon=true
org.gradle.console=rich

11) Frequently Used Commands

# Build everything
./gradlew build

# Deploy only a project
./gradlew :modules:hello-web:deploy

# Refresh dependencies after changing Target Platform
./gradlew --refresh-dependencies

# Clean
./gradlew clean

# Re-init bundle (if needed)
./gradlew initBundle

12) Troubleshooting (Fast Fixes)

  • “Class version X not supported”
    Use a supported JDK (11 or 17) and set JAVA_HOME accordingly.
  • Module installs but isn’t visible
    Check bundles/osgi/state & bundles/osgi/logs. Verify app category + portlet name; rebuild with ./gradlew clean deploy.
  • Dependency version mismatch
    Ensure liferay.workspace.target.platform.version is set; run ./gradlew --refresh-dependencies.
  • Docker container can’t see deploys
    Recreate with createDockerContainer to refresh volume mounts; confirm the deploy path mapping.

13) Production-Friendly Notes

  • Keep configs/prod/ with .config files for System Settings (e.g., mail, search).
  • Use Target Platform consistently across CI and developer machines.
  • Consider Gradle Enterprise or a build cache on CI to speed builds.

Copy-Paste Checklist

  • Install Blade
  • blade init -v 7.4 .
  • Set Target Platform + product in gradle.properties
  • ./gradlew initBundle
  • Start portal (blade server start or Tomcat)
  • Create module (blade create …)
  • ./gradlew :modules:…:deploy
  • (Optional) Docker: createDockerContainer → startDockerContainer
Tags: