Installing on JBoss EAP

Liferay DXP 2025.Q3+/Portal 2026.Q1+

Note

For pre-Jakarta Liferay versions, see Installing Earlier Versions 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
JBoss 8.0+

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 Dependencies and 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).

Important

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

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.

Note

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:

Locate the closing </extensions> tag. Directly beneath that closing tag, insert the following system properties, if they don’t already exist:

<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" />
</system-properties>

Filter out WFLYSRV0059 and WFLYEE0007 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.
```
<filter-spec value="not(any(match(&quot;WFLYSRV0059&quot;),match(&quot;WFLYEE0007&quot;)))" />
```

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,

<deployment-scanner deployment-timeout="600" path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000" runtime-failure-causes-rollback="${jboss.deployment.scanner.rollback.on.failure:false}"/>

Comment out the welcome content elements from the <subsystem xmlns="urn:jboss:domain:undertow:12.0" ...> element. For example,

<!--<location name="/" handler="welcome-content"/>-->

and

<handlers>
    <!--<file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>-->
</handlers>

If you’re using the IBM JDK with the JBoss server, navigate to the $JBOSS_HOME/modules/system/layers/base/sun/jdk/main/module.xml file. Then, insert these paths inside the <paths>...</paths> element to resolve issues with the portal deployment and image uploads:
```
<path name="com/sun/crypto" />
<path name="com/sun/crypto/provider" />
<path name="com/sun/image/codec/jpeg" />
<path name="com/sun/org/apache/xml/internal/resolver" />
<path name="com/sun/org/apache/xml/internal/resolver/tools" />
```

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 to 600.
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.

Important

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 the JAVA_OPTS assignment. For example, replace this

JAVA_OPTS="-Xms1303m -Xmx1303m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=2560m -Djava.net.preferIPv4Stack=true"

with this:

JAVA_OPTS="-Djava.net.preferIPv4Stack=true"

Add these Java options setting at the end of the file:

JAVA_OPTS="$JAVA_OPTS -Dfile.encoding=UTF-8 -Duser.timezone=GMT -Xms2560m -Xmx2560m -XX:MaxNewSize=1536m -XX:MaxMetaspaceSize=768m -XX:MetaspaceSize=768m -XX:NewSize=1536m -XX:SurvivorRatio=7 -Djboss.as.management.blocking.timeout=1800"

JDK_JAVA_OPTIONS="$JDK_JAVA_OPTIONS --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/sun.net.www.protocol.http=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=jdk.zipfs/jdk.nio.zipfs=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED"

export JDK_JAVA_OPTIONS

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.

Note

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.

Note

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.

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 WAR file includes drivers for MariaDB and PostgreSQL. Earlier WARs don’t have them. If the 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.

Note

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:

<?xml version="1.0"?>

<module name="com.liferay.portal" xmlns="urn:jboss:module:1.5">
    <dependencies>
        <module name="jakarta.servlet.api" optional="true" />
        <module name="jakarta.transaction.api" />
    </dependencies>
</module>

Get the JDBC JAR from your DXP WAR 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. Paste the following snippet after the </dependencies> closing tag:
```
<resources>
    <resource-root path="[place your database vendor's JAR file name here]" />
</resources>
```

Add the data source inside the $JBOSS_HOME/standalone/configuration/standalone.xml file’s the <datasources> element.

<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
    <connection-url>[place the URL to your database here]</connection-url>
    <driver>[place the driver name here]</driver>
    <security>
        <user-name>[place your user name here]</user-name>
        <password>[place your password here]</password>
    </security>
</datasource>

Make sure to replace the database URL, user name, and password with the appropriate values.

Note

If the data source jndi-name must be changed, edit the datasource element in the <default-bindings> tag.

Add the driver to the standalone.xml file’s <drivers> element also found within the <datasources> element.

<drivers>
    <driver name="[name of driver must match name above]" module="com.liferay.portal">
        <driver-class>[place your JDBC driver class here]</driver-class>
    </driver>
</drivers>

A final data source subsystem that uses MySQL should look like this:

<subsystem xmlns="urn:jboss:domain:datasources:5.0">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" jta="true" use-java-context="true" use-ccm="true">
            <connection-url>jdbc:mysql://localhost/lportal</connection-url>
            <driver>mysql</driver>
            <security>
                <user-name>root</user-name>
                <password>root</password>
            </security>
        </datasource>
        <drivers>
            <driver name="mysql" module="com.liferay.portal">
                <driver-class>com.mysql.cj.jdbc.Driver</driver-class>
            </driver>
        </drivers>
    </datasources>
</subsystem>

In a portal-ext.properties file in the Liferay Home, specify your data source. For example,
```
jdbc.default.jndi.name=java:jboss/datasources/ExampleDS
```

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:

<subsystem xmlns="urn:jboss:domain:mail:4.0">
    <mail-session name="java:jboss/mail/MailSession" jndi-name="java:jboss/mail/MailSession" >
        <smtp-server ssl="true"  outbound-socket-binding-ref="mail-smtp">
            <login username="[place user name here]" password="[place password here]"/>
        </smtp-server>
    </mail-session>
</subsystem>
...
<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="[place SMTP mail host here]" port="[place mail port here]"/>
    </outbound-socket-binding>
</socket-binding-group>

In the portal-ext.properties file in Liferay Home, reference the mail session. For example,
```
mail.session.jndi.name=java:jboss/mail/MailSession
```

Deploying DXP

To trigger deployment ROOT.war, create an empty file named ROOT.war.dodeploy in the $JBOSS_HOME/standalone/deployments/ folder.
Start the JBoss application server by navigating to $JBOSS_HOME/bin and running standalone.sh. JBoss detects the ROOT.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.

May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
WARNING: Skipping pass gatherExternProperties
May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
WARNING: Skipping pass checkControlFlow
May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
INFO: pass supports: [ES3 keywords as identifiers, getters, reserved words as properties, setters, string continuation, trailing comma, array pattern rest, arrow function, binary literal, block-scoped function declaration, class, computed property, const declaration, default parameter, destructuring, extended object literal, for-of loop, generator, let declaration, member declaration, new.target, octal literal, RegExp flag 'u', RegExp flag 'y', rest parameter, spread expression, super, template literal, modules, exponent operator (**), async function, trailing comma in param list]
current AST contains: [ES3 keywords as identifiers, getters, reserved words as properties, setters, string continuation, trailing comma, array pattern rest, arrow function, binary literal, block-scoped function declaration, class, computed property, const declaration, default parameter, destructuring, extended object literal, for-of loop, generator, let declaration, member declaration, new.target, octal literal, RegExp flag 'u', RegExp flag 'y', rest parameter, spread expression, super, template literal, exponent operator (**), async function, trailing comma in param list, object literals with spread, object pattern rest]

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.