Installing on JBoss EAP
Installing on JBoss EAP requires installing the DXP WAR, installing dependencies, configuring JBoss, and deploying DXP on JBoss. You must also configure your database and mail server connections.
Prerequisites
Liferay DXP/Portal requires a supported Java version to run. See JVM Configuration for more information.
Download these files from the Help Center (subscription) or from Liferay Community Downloads:
- DXP WAR file
- OSGi Dependencies ZIP file
- Dependencies ZIP file (DXP 7.3 and earlier)
The installation steps use these terms:
[Liferay Home]
: The folder containing the JBoss server folder (referred to as $JBOSS_HOME
). After installing and deploying DXP, it generates data
, deploy
, and logs
folders.
$JBOSS_HOME
: The JBoss server folder. It is usually named jboss-eap-[version]
.
Installing the DXP WAR
-
If you’re starting with a clean JBoss installation and a
$JBOSS_HOME/standalone/deployments/ROOT.war
folder exists, delete all of its subfolders and files. -
Unzip the DXP WAR file into the
$JBOSS_HOME/standalone/deployments/ROOT.war
folder (create this folder if it doesn’t exist).
The default Liferay Portal web context can be changed (e.g. localhost:8080/
to localhost:8080/myportal
) by changing the WAR filename, but this is not recommended.
Installing Dependencies
Unzip the OSGi Dependencies ZIP file into the [Liferay Home]/osgi
folder (create this folder if it doesn’t exist). Liferay’s OSGi runtime depends on these modules.
Install Dependencies Using JBoss’ Global Classpath Location
For DXP 7.3 and earlier, follow these additional steps:
-
Unzip the Dependencies ZIP file to a folder called
$JBOSS_HOME/modules/com/liferay/portal/main
(create this folder if it doesn’t exist). -
Create a file called
module.xml
in the$JBOSS_HOME/modules/com/liferay/portal/main
folder. In the file, declare the portal module and all of its required resources and dependencies:Replace
[place your database vendor's JAR file name here]
with the driver JAR for your database.For each JAR in the Liferay dependencies ZIP, add a
resource-root
element with itspath
attribute set to the JAR name. For example, add aresource-root
element like this for thecom.liferay.petra.concurrent.jar
file:
Running DXP on JBoss EAP in Standalone Mode vs. Domain Mode
JBoss EAP 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 Product Documentation.
DXP supports JBoss EAP when it runs in standalone mode but not when it runs in domain mode. DXP’s auto-deploy does not work with a managed deployment, since JBoss manages the content of a managed deployment by copying files (exploded or non-exploded). This prevents JSP hooks and Ext plugins from working as intended. For example, JSP hooks don’t work on JBoss EAP running in managed domain mode, since DXP’s JSP override mechanism relies on the application server. Since JSP hooks and Ext plugins are deprecated, however, you may not be using them.
If you use domain mode deployment, use the command line interface.
This does not prevent DXP from running in a clustered environment on multiple JBoss servers. You can set up a cluster of DXP instances running on JBoss EAP servers running in standalone mode. Please refer to the clustering articles for more information.
Configuring JBoss
Here are the JBoss configuration steps:
- Set environment variables
- Specify properties and descriptors
- Remove unnecessary configurations
Make the following modifications to $JBOSS_HOME/standalone/configuration/standalone.xml
:
-
Configure the servlet container to use Java 8 VM compatibility with JSPs. Locate the default servlet container
<servlet-container name="default">
in the<subsystem xmlns="urn:jboss:domain:undertow:12.0" ...
element. In the servlet container’s<jsp-config>
element, setdevelopment
,source-vm
, andtarget-vm
attributes like this: -
Locate the closing
</extensions>
tag. Directly beneath that closing tag, insert the following system properties, if they don’t already exist: -
Filter out
WFLYSRV0059
andWFLYEE0007
messages from the log. In the<subsystem xmlns="urn:jboss:domain:logging:8.0">
element’s<console-handler>
tag, add the following<filter-spec>
tag directly below the<level name="INFO"/>
tag. -
Add a deployment scanner timeout by adding a
deployment-timeout="600"
setting to the<deployment-scanner>
tag in the<subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0">
element. For example, -
Add Liferay’s JAAS security domain to the
<subsystem xmlns="urn:jboss:domain:security:2.0">
’s<security-domains>
element. Here is the domain code to add: -
Comment out the welcome content elements from the
<subsystem xmlns="urn:jboss:domain:undertow:12.0" ...>
element. For example,and
Checkpoint:
Before continuing, verify the following properties have been set in the standalone.xml
file:
- The new
<system-property>
is added. - The new
<filter-spec>
is added. - The
<deployment-timeout>
is set to600
. - The new
<security-domain>
is created. - Welcome content is disabled.
Next, configure the JVM and startup scripts:
In the $JBOSS_HOME/bin/
folder, modify the standalone domain’s configuration script file standalone.conf
:
- Set the file encoding to
UTF-8
- Set the user time zone to
GMT
- Set the preferred protocol stack
- Increase the default amount of memory available.
DXP requires the application server JVM to use the GMT
time zone and UTF-8
file encoding.
Make the following edits to your standalone.conf
script.
-
Below the
if [ "x$JAVA_OPTS" = "x" ];
statement, remove the JVM sizing options from theJAVA_OPTS
assignment. For example, replace thiswith this:
-
Add these Java options setting at the end of the file:
The Java options and memory arguments are explained below.
JVM Options Explained
Option | Explanation |
---|---|
-Dfile.encoding=UTF-8 | DXP requires UTF-8 file encoding. |
-Djava.net.preferIPv4Stack=true | Prefers an IPv4 stack over IPv6. |
-Djboss.as.management.blocking.timeout=1800 | Set timeout to retry in case JBoss fails to start. |
-Duser.timezone=GMT | DXP requires the application server JVM to use the GMT time zone. |
The deep reflection options are necessary for some components in Liferay to function.
Memory Arguments Explained
Memory Arguments | Explanation |
---|---|
-Xms | Initial space for the heap. |
-Xmx | Maximum space for the heap. |
-XX:NewSize | Initial new space. Setting the new size to half of the total heap typically provides better performance than using a smaller new size. |
-XX:MaxNewSize | Maximum new space. |
-XX:MetaspaceSize | Initial space for static content. |
-XX:MaxMetaspaceSize | Maximum space for static content. |
-XX:SurvivorRatio | Ratio of the new space to the survivor space. The survivor space holds young generation objects before being promoted to old generation space. |
After installing DXP, these configurations (including these JVM options) can be further tuned for improved performance. Please see Tuning Liferay and Tuning Your JVM for more information.
Using the IBM JDK
If you’re using the IBM JDK with the JBoss server, complete these additional steps:
-
For DXP 7.3 and earlier, navigate to the
$JBOSS_HOME/modules/com/liferay/portal/main/module.xml
file and insert this dependency within the<dependencies>
element:<module name="ibm.jdk" />
-
Navigate to the
$JBOSS_HOME/modules/system/layers/base/sun/jdk/main/module.xml
file and insert these paths inside the<paths>...</paths>
element:
The added paths resolve issues with portal deployment exceptions and image uploading problems.
Data Source Configuration in Liferay
DXP contains a built-in Hypersonic database which is great for demonstration purposes but should not be used in production. For production, use a full-featured, supported RDBMS. See Configure a Database to set up your database.
Liferay DXP can connect with your database using DXP’s built-in data source (recommended) or using a data source you create on your app server.
You can configure DXP’s built-in data source with your database the first time you run DXP by using the Setup Wizard. Or you can configure the data source in a portal-ext.properties
file based on the Database Template for your database.
Data Source Configuration in JBoss EAP
If you’re using JBoss to manage the data source, follow these steps:
-
The DXP 7.4+ WAR file includes drivers for MariaDB and PostgreSQL. Earlier WARs don’t have them. If the 7.4+ WAR doesn’t have the driver for the supported database you’re using, download your database vendor’s JDBC JAR file and place it in the
$JBOSS_HOME/standalone/deployments/ROOT.war/WEB-INF/shielded-container-lib
folder. This is the recommended method for adding dependencies that are only needed by Liferay on JBoss. Alternatively, you can install dependencies using JBoss’ global classpath location.See the compatibility matrix for a list of supported databases.
DXP includes a Hypersonic database that is useful for testing purposes. Do not use HSQL for production instances.
-
If you haven’t already, create a file called
module.xml
in the$JBOSS_HOME/modules/com/liferay/portal/main
folder. In the file, declare the portal module and all of its required dependencies: -
Get the JDBC JAR from your DXP WAR (7.4+) or from the database vendor and copy it to the
$JBOSS_HOME/modules/com/liferay/portal/main
folder. -
Update
module.xml
in the$JBOSS_HOME/modules/com/liferay/portal/main
folder to declare the portal module and the JDBC JAR. -
Add the data source inside the
$JBOSS_HOME/standalone/configuration/standalone.xml
file’s the<datasources>
element.Make sure to replace the database URL, user name, and password with the appropriate values.
NoteIf the data source
jndi-name
must be changed, edit thedatasource
element in the<default-bindings>
tag. -
Add the driver to the
standalone.xml
file’s<drivers>
element also found within the<datasources>
element.A final data source subsystem that uses MySQL should look like this:
-
In a
portal-ext.properties
file in the Liferay Home, specify your data source. For example,
The data source is now configured and ready to connect to the database.
Connect to a Mail Server
As with database configuration, the easiest mail session to configure is DXP’s. If you want to use DXP’s built-in mail session, skip this section and connect to a mail server in the Control Panel.
If you want to configure the mail session in JBoss, follow these steps:
-
Specify the mail subsystem in the
$JBOSS_HOME/standalone/configuration/standalone.xml
file like this: -
In the
portal-ext.properties
file in Liferay Home, reference the mail session. For example,
Deploying DXP
-
To trigger deployment
ROOT.war
, create an empty file namedROOT.war.dodeploy
in the$JBOSS_HOME/standalone/deployments/
folder. -
Start the JBoss application server by navigating to
$JBOSS_HOME/bin
and runningstandalone.sh
. JBoss detects theROOT.war.dodeploy
file and deploys the web application matching the file prefix (i.e.,ROOT.war
).
After deploying DXP, you may see excessive warnings and log messages such as the ones below, involving PhaseOptimizer
. These are benign and can be ignored. You can turn off these messages by adjusting the app server’s logging level or log filters.
If you have a Liferay DXP Enterprise subscription, DXP requests your activation key. See Activating Liferay DXP for more information.
Congratulations! You’re running DXP on JBoss EAP.
Next Steps
You can sign in as your administrator user and start building a solution on DXP. Or you can explore additional Liferay DXP setup topics: