A Liferay Workspace offers a development environment that can be configured to fit your development needs. You’ll learn about the files/folders a workspace provides by default, and then you’ll dive into configuring your workspace.
The top-level files/folder of a Liferay (Gradle) Workspace are outlined below:
bundles(generated): the default folder for Liferay DXP bundles.
configs: holds the configuration files for different environments. These files serve as your global configuration files for all Liferay DXP servers and projects residing in your workspace. To learn more about using the
configsfolder, see the Testing Modules section.
ext(generated): holds the Ext OSGi modules and Ext plugins.
gradle: holds the Gradle Wrapper used by your workspace.
modules: holds your custom modules. This can also hold frontend portlets created with the Liferay JS Toolkit
plugins-sdk(generated): holds plugins to migrate from previous releases. These project types should eventually be migrated to the
warsfolder, if possible. This is targeted for Liferay DXP 7.0 to provide a way to migrate from the Plugins SDK to Liferay Workspace. See the Using a Plugins SDK from Your Workspace section for more information. The Plugins SDK is no longer available for Liferay DXP 7.1.
themes: holds Node.js-style themes that use the Liferay JS Theme Toolkit, which are built using the Liferay Theme Generator.
wars: holds traditional WAR-style web application projects and theme projects (i.e., generated by the
build.gradle: the common Gradle build file.
gradle.properties: specifies the workspace’s project locations and Liferay DXP server configuration globally.
gradle-local.properties: sets user-specific properties for your workspace. This lets multiple users use a single workspace, letting them configure specific properties for the workspace on their own machine.
gradlew: executes the Gradle command wrapper.
settings.gradle: applies plugins to the workspace and configures its dependencies.
If you’re using a Liferay
instead, your folder hierarchy is the same, except the Gradle build files are
swapped out for a
pom.xml file. See the Maven Workspace tutorial for more info
on configuring that kind of workspace project.
The build/properties files included in your workspace’s root folder sets your workspace’s Gradle properties and facilitates the build processes of your modules.
Before you begin using your workspace, you should set your workspace Gradle
properties in the
gradle.properties file. There are many commented out
properties in this file. These are the default properties set in your workspace.
If you’d like to change a variable, uncomment the variable and set it to a
custom value. For instance, if you want to store your modules in a folder other
[ROOT]/modules, uncomment the
and set it to a different value.
If you’d like to keep the global Gradle properties the same, but want to change
them for yourself only (perhaps for local testing), you can override the
gradle.properties file with your own
All properties in the
gradle.properties file are documented within the file.
To learn more about how each property works and what’s available, visit your
gradle.properties file. You can also visit the
Gradle Workspace Properties section for a list
of these properties.
Now that you know about a workspace’s default folder structure and how to modify its Gradle properties, you’ll learn how to add a Liferay bundle to your workspace.
Adding a Liferay Bundle to a Workspace
Liferay Workspaces can generate and hold a Liferay Server. This lets you
build/test your plugins against a running Liferay instance. Before generating a
Liferay instance, open the
gradle.properties file located in your workspace’s
root folder. There are several configurable properties for your workspace’s
Liferay instance. You can set the version of the Liferay bundle you’d like to
generate and install by setting the download URL for the
You can also set the folder where your Liferay bundle is generated with the
liferay.workspace.home.dir property. It’s set to
bundles by default.
You can download a Liferay DXP bundle for your workspace if you’re a DXP
subscriber. Do this by setting the
liferay.workspace.bundle.url property to a
ZIP hosted on api.liferay.com. For example,
It can be tricky to find the fully qualified ZIP name/number for the DXP bundle
you want. You cannot access Liferay’s API site directly to find it, so you must
start to download DXP manually, take note of the file name, and append it to
You must also set the
liferay.workspace.bundle.token.download property to
true to allow your workspace to access Liferay’s API site.
Once you’ve finalized your Gradle properties, navigate to your workspace’s root folder and run
blade server init
This uses workspace’s pre-bundled
Blade CLI tool to download
the version of Liferay DXP you specified in your Gradle properties and installs
your Liferay instance in the
If you want to skip the downloading process, you can create the
manually in your workspace’s ROOT folder and unzip your Liferay DXP bundle to that
You can also produce a distributable Liferay bundle (Zip or Tar) from within a workspace. To do this, navigate to your workspace’s root folder and run the following command:
Your distribution file is available from the workspace’s
The Liferay Workspace is a great development environment for Liferay module development; however, what if you’d like to also stick with developing WAR-style applications? Liferay Workspace can handle that request too!
Gradle Workspace Properties
The following configurable properties are available in your workspace’s
liferay.workspace.bundle.cache.dir: Set the directory where the downloaded bundle Zip files are stored. The default value is the
.liferay/bundlesfolder inside the user home directory.
liferay.workspace.bundle.token.download: Set this to
liferay.workspace.bundle.urlproperty is set to a DXP bundle Zip. This property allows the token residing in the
~/.liferayfolder to be used to validate your user credentials when downloading the bundle. The default value is
liferay.workspace.bundle.token.email.address: Set the email address to use when downloading a DXP bundle. This is used to create the authentication token. The email address must match the one registered for your DXP subscription. If you wish to create a new token without providing your email address and password in this file, you can create a token manually by navigating to your Liferay profile’s Account Setting page and generating a token in the Authentication Tokens menu. Your token must reside in the
liferay.workspace.bundle.token.force: Set this to
trueto override the existing token with a newly generated token created by the
createTokentask. The default value is
liferay.workspace.bundle.token.password: Set the password to use when downloading a DXP bundle. This is used to create the authentication token. The password must match the one registered for your DXP subscription. See the
liferay.workspace.bundle.token.email.addressproperty for more details.
liferay.workspace.bundle.token.password.file: Set the file to hold the Liferay bundle authentication token password. The default file value is
liferay.workspace.bundle.url: Set the URL pointing to the bundle Zip to download. If the URL points to a DXP bundle (e.g., https://api.liferay.com/…), set the
true. The default value is the URL for the latest version of Liferay Portal CE.
liferay.workspace.default.repository.enabled: Set this to
trueto configure Liferay CDN as the default repository in the root project. The default value is
liferay.workspace.environment: Set the environment with the settings appropriate for current development. The
configsfolder is used to hold different environments in the same workspace. You can organize environment settings and generate an environment installation with those settings. There are five environments:
uat. The default value is
liferay.workspace.home.dir: Set the folder that contains the Liferay bundle downloaded from the
liferay.workspace.bundle.urlproperty. The default value is
liferay.workspace.modules.default.repository.enabled: Set this to
trueto configure Liferay CDN as the default repository for module/OSGi projects. The default value is
liferay.workspace.ext.dir: Set the folder that contains all Ext OSGi modules and Ext plugins. The default value is
liferay.workspace.modules.dir: Set the folder that contains all module/OSGi projects. The default value is
liferay.workspace.modules.jsp.precompile.enabled: Set this to
trueto compile the JSP files in OSGi modules and have them added to the distributable Zip/Tar. The default value is
liferay.workspace.plugins.sdk.dir: Set the folder that contains the Plugins SDK environment. The default value is
liferay.workspace.target.platform.version: Set the Liferay Portal or DXP bundle version to develop against. This property enables target platform features such as the OSGi
resolvetask and specialized dependency management. Use
7.1.1for the latest Liferay CE release and
7.1.10for the latest DXP release.
liferay.workspace.themes.dir: Set the folder that contains Node.js-style theme projects, which use the Liferay JS Theme Toolkit. The default value is
liferay.workspace.themes.java.build: Set this to
trueto build the theme projects using the Liferay Portal Tools Theme Builder. The default value is
liferay.workspace.wars.dir: Set the folder that contains classic WAR-style projects. The default value is
That’s it! You now have the knowledge to fully leverage the power of Liferay Workspace!