Configuring a Liferay Workspace

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 configs folder, 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 wars folder, 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 theme project template).
• 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 Maven Workspace 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 than [ROOT]/modules, uncomment the liferay.workspace.modules.dir variable 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 gradle-local.properties file.

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 workspace’s generated gradle.properties file. You can also visit the Gradle Workspace Properties section for a list of these properties.

Note: Liferay Workspace provides many subprojects for you behind the scenes, which hides some complexities of Gradle. You can learn more about this in the Building Modules section.

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 liferay.workspace.bundle.url property (e.g., https://releases-cdn.liferay.com/portal/7.1.0-ga1/liferay-ce-portal-tomcat-7.1.0-ga1-20180703012531655.zip). 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,

liferay.workspace.bundle.url=https://api.liferay.com/downloads/portal/7.1.10/liferay-dxp-tomcat-7.1.10-ga1-20180703090613030.zip

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 https://api.liferay.com/downloads/portal/.

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 bundles folder.

If you want to skip the downloading process, you can create the bundles folder manually in your workspace’s ROOT folder and unzip your Liferay DXP bundle to that folder.

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:

./gradlew distBundle[Zip|Tar]

Your distribution file is available from the workspace’s /build folder.

Note: You can define different environments for your Liferay bundle for easy testing. You can learn more about this in the Testing Modules section.

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 gradle.properties file:

• liferay.workspace.bundle.cache.dir: Set the directory where the downloaded bundle Zip files are stored. The default value is the .liferay/bundles folder inside the user home directory.
• liferay.workspace.bundle.token.download: Set this to true if the liferay.workspace.bundle.url property is set to a DXP bundle Zip. This property allows the token residing in the ~/.liferay folder to be used to validate your user credentials when downloading the bundle. The default value is false.
• 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 folder.
• liferay.workspace.bundle.token.force: Set this to true to override the existing token with a newly generated token created by the createToken task. The default value is false.
• 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.address property 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/token.
• 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 liferay.workspace.bundle.token.download property to true. The default value is the URL for the latest version of Liferay Portal CE.
• liferay.workspace.default.repository.enabled: Set this to true to configure Liferay CDN as the default repository in the root project. The default value is true.
• liferay.workspace.environment: Set the environment with the settings appropriate for current development. The configs folder 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: common, dev, local, prod, and uat. The default value is local.
• liferay.workspace.home.dir: Set the folder that contains the Liferay bundle downloaded from the liferay.workspace.bundle.url property. The default value is bundles.
• liferay.workspace.modules.default.repository.enabled: Set this to true to configure Liferay CDN as the default repository for module/OSGi projects. The default value is true.
• liferay.workspace.ext.dir: Set the folder that contains all Ext OSGi modules and Ext plugins. The default value is ext.
• liferay.workspace.modules.dir: Set the folder that contains all module/OSGi projects. The default value is modules.
• liferay.workspace.modules.jsp.precompile.enabled: Set this to true to compile the JSP files in OSGi modules and have them added to the distributable Zip/Tar. The default value is false.
• liferay.workspace.plugins.sdk.dir: Set the folder that contains the Plugins SDK environment. The default value is plugins-sdk.
• 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 resolve task and specialized dependency management. Use 7.1.1 for the latest Liferay CE release and 7.1.10 for 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 themes.
• liferay.workspace.themes.java.build: Set this to true to build the theme projects using the Liferay Portal Tools Theme Builder. The default value is false.
• liferay.workspace.wars.dir: Set the folder that contains classic WAR-style projects. The default value is wars.

That’s it! You now have the knowledge to fully leverage the power of Liferay Workspace!