Installing Liferay DXP on JBoss EAP 6.4

Installing Liferay DXP manually requires these basic steps:

  • Installing Liferay DXP dependencies to your application server
  • Configuring your application server for Liferay DXP
  • Installing the Liferay DXP WAR file to your application server

In this article, you’ll step through these basic steps and install Liferay DXP on your existing JBoss EAP 6.4 application server. Before proceeding, you must download these Additional Files:

  • Liferay DXP WAR file
  • Dependencies ZIP file
  • OSGi Dependencies ZIP file

Liferay Home is one folder above JBoss’s install location. Liferay Home refers to the folder containing your JBoss server folder. When Liferay DXP is installed on JBoss, the Liferay Home folder contains the JBoss server folder as well as data, deploy, logs, and osgi folders. You’ll also see the term $JBOSS_HOME used in this guide. $JBOSS_HOME refers to your JBoss server folder. This folder is usually named jboss-eap-[version].

Installing Liferay DXP Dependencies

Liferay DXP depends on many JARs that are included in the Liferay DXP JBoss bundle. Some JARs in the bundle are not strictly required but can still be useful. You can download the required JARs from third-parties, as described below.

  1. Create the folder $JBOSS_HOME/modules/com/liferay/portal/main. Unzip the the Liferay DXP Dependencies zip file and copy the .jar files to this folder.

  2. Download your database driver .jar file and copy it into the same folder. For example, for MySQL, download the MySQL Connector/J driver. and put its .jar file into the $JBOSS_HOME/modules/com/liferay/portal/main folder.

  3. Download the com.liferay.registry.api.jar JAR and insert it into the same folder.

  4. Create the file module.xml in the $JBOSS_HOME/modules/com/liferay/portal/main folder and insert the following contents:

     <?xml version="1.0"?>
     <module name="com.liferay.portal" xmlns="urn:jboss:module:1.0">
             <resource-root path="com.liferay.registry.api.jar" />
             <resource-root path="mysql-connector-java-[version]-bin.jar" />
             <resource-root path="portal-kernel.jar" />
             <resource-root path="portlet.jar" />
             <module name="javax.api" />
             <module name="javax.mail.api" />
             <module name="javax.servlet.api" />
             <module name="javax.servlet.jsp.api" />
             <module name="javax.transaction.api" />

    Make sure to replace [version] with the correct version of the MySQL JDBC driver. If you are using a different database, replace the MySQL .jar with the driver JAR for your database (e.g., HSQL, PostgreSQL, etc.).

  5. Create an osgi folder in your Liferay Home folder. Then extract the OSGi ZIP file that you downloaded into the osgi folder.

    Liferay DXP requires an OSGi runtime, and the osgi folder provides this with many required JAR files and configuration files.


  1. Inside the $JBOSS_HOME/modules/com/liferay/portal/main folder, verify that the following are present:

    a. com.liferay.registry.api.jar b. portal-kernel.jar c. portlet.jar d. (database of your choice jar) (e.g. MySQL, SQL Server…)

  2. Inside the osgi folder, verify the following folders are present:

    a. configs b. core c. marketplace d. target-platform e. test

Running Liferay DXP on JBoss EAP 6.4 in Standalone Mode vs. Domain Mode

JBoss EAP 6.4 can be launched in either standalone mode or domain mode. Domain mode allows multiple application server instances to be managed from a single control point. A collection of such application servers is known as a domain. For more information on standalone mode vs. domain mode, please refer to the section on this topic in the JBoss EAP 6.4 Administration and Configuration Guide. Liferay DXP fully supports JBoss EAP 6.4 when it runs in standalone mode but not when it runs in domain mode.

You can run Liferay DXP on JBoss EAP 6.4 in domain mode, but this method is not fully supported. In particular, Liferay DXP’s hot-deploy does not work, since JBoss EAP 6.4 cannot deploy non-exploded .war files in domain mode. Instead, .war files are in the domain/data/content directory. Deployments are only possible using the command line interface. This prevents many Liferay DXP plugins from working as intended. For example, JSP hooks don’t work on JBoss EAP 6.4 running in domain mode, since Liferay DXP’s JSP override mechanism relies on the application server reloading customized JSP files from the exploded plugin .war file location. Other plugins, such as service or action hooks, should still work properly since they don’t require JBoss to access anything (such as JSP files) from an exploded .war file on the file system.

Configuring JBoss

Now you’ll make some adjustments in your configuration to support using Liferay DXP.

You can specify the JBoss server instance’s configuration in the XML file $JBOSS_HOME/standalone/configuration/standalone.xml. You must also make some modifications to your configuration and startup scripts found in the $JBOSS_HOME/bin/ folder. Lastly, you’ll need to make some modifications in your $JBOSS_HOME/modules/. You’ll begin with making changes to standalone.xml.

Make the following modifications to standalone.xml:

  1. Locate the closing </extensions> tag. Directly beneath that tag, insert the following system properties:

         <property name="org.apache.catalina.connector.URI_ENCODING" value="UTF-8" />
         <property name="org.apache.catalina.connector.USE_BODY_ENCODING_FOR_QUERY_STRING" value="true" />
  2. Add a timeout for the deployment scanner by setting deployment-timeout="360" as seen in the excerpt below.

     <subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0">
         <deployment-scanner deployment-timeout="360" path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
  3. Add the following JAAS security domain to the security subsystem <security-domains> defined in element <subsystem xmlns="urn:jboss:domain:security:1.2">.

     <security-domain name="PortalRealm">
             <login-module code="" flag="required" />
  4. Disable the default JBoss Welcome page by setting the enable-welcome-root attribute to false, as seen in the snippet below.

     <subsystem xmlns="urn:jboss:domain:web:2.2" default-virtual-server="default-host" native="false">
         <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
         <virtual-server name="default-host" enable-welcome-root="false">
  5. In the same <subsystem ... /> element that was outlined in the previous step, add the following snippet above the <connector ... /> element:

         <jsp-configuration source-vm="1.8" target-vm="1.8" development="true" />


  1. The standalone.xml has been modified with the following values:

    a. deployment-timeout="360" has been set. The value is in seconds.
    b. The JAAS security domain has been added.
    c. The property enable-welcome-root="false" has been set.
    d. The property jsp-configuration source-vm="1.8" target-vm="1.8" development="true" has been set in the <configuration> element. This is required because Liferay DXP runs on Java JDK 1.8 or else there will be a JasperException and the instance will fail to start.

Now it’s time for some changes to your configuration and startup scripts.

Make the following modifications to your standalone domain’s configuration script file standalone.conf (standalone.conf.bat on Windows) found in your $JBOSS_HOME/bin/ folder.

These modifications change the following options:

  • Set the file encoding
  • Set the user time-zone
  • Set the preferred protocol stack
  • Increase the default amount of memory available.

Make the following edits as applicable to your operating system:

On Windows, comment out the initial JAVA_OPTS assignment as demonstrated in the following line:

rem set "JAVA_OPTS=-Xms1G -Xmx1G -XX:MaxPermSize=256M"

Then add the following JAVA_OPTS assignment one line above the :JAVA_OPTS_SET line found at end of the file:

set "JAVA_OPTS=%JAVA_OPTS% -Dfile.encoding=UTF-8 -Dsecmgr$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m"

On Unix, merge the following values into your settings for JAVA_OPTS, replacing any matching attributes with the ones found in the assignment below:

JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Dsecmgr$JBOSS_HOME/bin/server.policy -Djboss.home.dir=$JBOSS_HOME -Duser.timezone=GMT -Xmx1024m -XX:MaxMetaspaceSize=384m"

Make sure you replace the $JBOSS_HOME references with the appropriate directory. You’ll notice some Java security options. You’ll finish configuring the Java security options in the Security Configuration section.


  1. The standalone.conf.bat file has been updated with the following changes:

    a. UTF-8 file encoding b. The user time-zone c. The preferred protocol stack d. Increased the default amount of memory available.

  2. If using the IBM JDK with the JBoss server, <module name="ibm.jdk" /> has been added to the $JBOSS_HOME/modules/com/liferay/portal/main/module.xml file.

  3. The additional IBM JDK paths have been set in the $JBOSS_HOME/modules/system/layers/base/sun/jdk/main/module.xml file.

The prescribed script modifications are now complete for your Liferay DXP installation on JBoss. Next you’ll configure mail and the database.

Database Configuration

If you want JBoss to manage your data source, follow the instructions in this section. If you want to use the built-in Liferay DXP data source, you can skip this section.

Modify standalone.xml and add your data source and driver in the <datasources> element of your data sources subsystem.

  1. First, add your data source inside the <datasources> element.

     <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">

    Be sure to replace the database name (i.e. lportal), user name, and password with the appropriate values.

  2. Add your driver to the <drivers> element also found within the <datasources> element.

         <driver name="mysql" module="com.liferay.portal"/>

Your final data sources subsystem should look like this:

    <subsystem xmlns="urn:jboss:domain:datasources:1.2">
            <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
                <driver name="mysql" module="com.liferay.portal"/>

Now that you’ve configured your data source, the mail session is next.

Mail Configuration

If you want JBoss to manage your mail session, use the following instructions. If you want to use the built-in Liferay DXP mail session, you can skip this section.

Specify your mail subsystem in standalone.xml as in the following example:

<subsystem xmlns="urn:jboss:domain:mail:1.2">
    <mail-session jndi-name="java:jboss/mail/MailSession" >
        <smtp-server ssl="true" outbound-socket-binding-ref="mail-smtp">
            <login username="USERNAME" password="PASSWORD"/>
<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
<outbound-socket-binding name="mail-smtp">
        <remote-destination host="" port="465"/>

You’ve got mail! Next, you’ll make sure Liferay DXP can connect using your new mail session and database.

Configuring data sources and mail sessions

Now that your data source and mail session are set up, you need to ensure Liferay DXP 7.0 can access them.

  1. First, navigate to the Liferay Home folder, which is one folder above JBoss’s install location (i.e. $JBOSS_HOME/..).

  2. If you’re using JBoss to manage your data source, add the following configuration to your file in your Liferay Home to refer to your data source:

    If you’re using Liferay DXP 7.0 to manage your data source, follow the instructions for using the setup wizard.

  3. If you’re using Liferay DXP 7.0 to manage your mail session, this configuration is done in Liferay DXP 7.0. That is, after starting your portal as described in the Deploy Liferay DXP section, go to Control PanelServer AdministrationMail and enter the settings for your mail session.

    If you’re using JBoss to manage your mail session, add the following configuration to your file to reference that mail session:

Before you deploy Liferay DXP 7.0 on your JBoss app server, you should enable and configure Java security so you can use Liferay DXP’s plugin security manager with your downloaded Liferay DXP applications.

Security Configuration

When you’re ready to begin using other people’s apps from Marketplace, you’ll want to protect your Liferay DXP instance and your JBoss server from security threats. To do so, you can enable Java Security on your JBoss server and specify a security policy to grant your Liferay DXP instance access to your server.

Remember, you set the -Dsecmgr and Java options in the standalone.conf.bat file earlier in the Configuring JBoss section. The -Dsecmgr Java option enables security on JBoss. Likewise, the Java option lists the permissions for your server’s Java security policy. If you have not set these options, you’ll need to do so before using Java security.

This configuration opens up all permissions. You can tune the permissions in your policy later. Create the $JBOSS_HOME/bin/server.policy file and add the following contents:

grant {

For extensive information on Java SE Security Architecture, see its specification documents at Also, see the Plugin Security and PACL tutorial to learn how to configure Liferay DXP plugin access to resources.

Deploy Liferay DXP

  1. If the folder $JBOSS_HOME/standalone/deployments/ROOT.war already exists in your JBoss installation, delete all of its subfolders and files. Otherwise, create a new folder $JBOSS_HOME/standalone/deployments/ROOT.war.

  2. Unzip the Liferay DXP .war file into the ROOT.war folder.

  3. To trigger deployment of ROOT.war, create an empty file named ROOT.war.dodeploy in your $JBOSS_HOME/standalone/deployments/ folder. On startup, JBoss detects the presence of this file and deploys it as a web application.

  4. Start the JBoss application server by navigating to $JBOSS_HOME/bin and running standalone.bat or

The JBoss application server starts and deploys Liferay DXP.

You’re now an expert when it comes to deploying Liferay DXP on JBoss!

« Installing Liferay DXP on WildflyInstalling Liferay DXP on tc Server »
Was this article helpful?
0 out of 0 found this helpful