Liferay’s official Tomcat installation guide is a useful starting point, but it is not quite enough for installing Liferay DXP 2026.Q1 on Red Hat JBoss Web Server 6.2.3.

The reason is straightforward: JBoss Web Server is Tomcat, but it is Red Hat’s supported Tomcat distribution, and the current Liferay documentation contains a few assumptions that do not line up cleanly with a modern 2026.Q1 install.

In this post, we will install Liferay DXP 2026.Q1 on JWS 6.2.3 using RHEL 10 as the reference operating system. The same pattern applies to other Linux distributions, but the package manager and service integration details will vary.

Why JBoss Web Server?

When someone asks for “JBoss” in the context of a Tomcat-based Liferay deployment, they may not mean JBoss EAP. They may mean Red Hat JBoss Web Server (JWS).

JBoss Web Server is a separate Red Hat middleware product. Under the covers, JWS 6.x includes Apache Tomcat 10.1, Apache HTTP Server integration options, production-ready connectors such as mod_cluster, Tomcat native libraries, APR, OpenSSL integration, and Red Hat’s middleware support lifecycle.

This matters for enterprise environments because many organizations standardize on Red Hat-supported middleware even when the upstream runtime is Apache Tomcat. They may need:

• A fully supported Tomcat 10.1 runtime.
• Longer enterprise compliance windows.
• Red Hat support channels.
• Supported Apache HTTP Server connector integration.
• FIPS or hardened runtime requirements.
• Standardized deployment through RHEL subscriptions, archives, or container images.

For RHEL 10, Red Hat also provides a Tomcat 10.1 package directly through the operating system. JWS is still relevant when the client’s middleware standard is Red Hat Middleware Runtimes rather than base RHEL packages.

Version Alignment

Before touching files, get the compatibility story clear.

Liferay DXP 2026.Q1 supports Tomcat 10.1 and RHEL 10. JWS 6.x provides Tomcat 10.1, so the servlet container version lines up.

The Java version is where older documentation can mislead you. The Liferay Tomcat install page currently shows a Java 8 example in setenv.sh. Do not use that for 2026.Q1. For this installation, use JDK 21.

JWS 6.x supports multiple modern Java versions, but Liferay 2026.Q1 should be run on JDK 21. Do not let the server default to a newer Java such as JDK 25, and do not copy older Java 8 examples from older Liferay documentation.

On RHEL 10:

$ sudo dnf install java-21-openjdk-headless unzip tar
$ sudo alternatives --config java
$ java -version

On other distributions, the equivalent commands are usually:

# Debian or Ubuntu
$ sudo apt install openjdk-21-jdk-headless unzip tar

# SUSE
$ sudo zypper install java-21-openjdk-headless unzip tar

# Fedora
$ sudo dnf install java-21-openjdk-headless unzip tar

The important part is not the package manager. The important part is that the runtime used by JWS is Java 21.

Downloads

Download these Liferay files:

• DXP WAR
• OSGi Dependencies
• Admin Tools
• Bundled with Tomcat

The Tomcat bundle is not the runtime we are deploying, but it is still useful. It shows the directory structure, scripts, ROOT.xml, and runtime assumptions Liferay expects when it owns the Tomcat layout. All of the locations, contents, etc for the Liferay Tomcat bundle works, so if you have local issues, comparing your installation to the Liferay Tomcat bundle can often expose differences that might be contributing to the issues.

For separate installation of JWS, use the Red Hat Customer Portal:

1. Create or use a Red Hat Developer account.
2. Confirm that your account has access to the no-cost Individual Developer Subscription or the client’s Middleware Runtimes subscription.
3. Go to Red Hat Customer Portal downloads.
4. Select Red Hat JBoss Web Server.
5. Download the JWS 6.2.3 application server archive.

I'm testing locally on my Mac, so the generic JWS application server ZIP is usually enough because the Tomcat runtime itself is Java-based. For other Linux platforms, you might want the native component downloads if you are specifically testing platform-native Apache HTTP Server integration, APR, OpenSSL, or connector behavior.

Target Layout

The official Liferay Tomcat page assumes that Liferay Home is the parent directory of the Tomcat folder. That works for the Liferay-provided Tomcat bundle, but it is not always the best fit for JWS.

For this install, use explicit paths:

/opt/jws-6.2.3              JBoss Web Server installation
/opt/jws-6.2.3/tomcat       Tomcat runtime
/opt/liferay                Liferay Home

As indicated earlier, I'm using Apache Tomcat 10.1 since I can't get a JWS download. I manually created the /opt/jws-6.2.3 directory, exploded the apache-tomcat-10.1.57.tar.gz file I downloaded and renamed the directory to tomcat to match what JWS would have.

I prefer /opt/liferay for Liferay Home because it keeps Liferay’s mutable runtime data separate from the application server installation. Because of the runtime directory updates, you might also consider /var/run/liferay or something similar.

Create the Liferay Home structure:

$ sudo mkdir -p /opt/liferay/{data,deploy,license}
$ sudo mkdir -p /opt/liferay/{logs,osgi,tools}
$ sudo chown -R tomcat:tomcat /opt/liferay

If the tomcat user does not exist yet, create it first:

$ sudo groupadd -g 53 -r tomcat
$ sudo useradd -c "tomcat" -u 53 -g tomcat \
  -s /sbin/nologin -r tomcat

Red Hat’s JWS post-install scripts can also create and configure the service user when using the archive installation flow.

Install JBoss Web Server

Extract the archive:

$ sudo unzip jws-6.2.3-application-server.zip -d /opt
$ sudo chown -R tomcat:tomcat /opt/jws-6.2.3

Set a few working variables while installing:

$ export JWS_HOME=/opt/jws-6.2.3
$ export CATALINA_HOME=$JWS_HOME/tomcat
$ export CATALINA_BASE=$CATALINA_HOME
$ export LIFERAY_HOME=/opt/liferay

If you want systemd management on RHEL, run the JWS post-install script:

$ cd /opt/jws-6.2.3/tomcat
$ sudo sh .postinstall.systemd
$ sudo systemctl enable jws6-tomcat.service

If you're using your package manager to install JWS, you may actually have pieces installed in separate locations. The CATALINA_HOME environment variable where the static files and binaries are installed and CATALINA_BASE environment variable where dynamic, changeable components are installed (like the web apps that are deployed) will be set up by the installation, you won't have to set them yourself, but you'll have to know about them to install the right parts in the right places. It will also handle the systemd service setup, but you'll need to do the service enabling.

You'll still do the LIFERAY_HOME setup stuff.

JWS Tomcat Cleanup

We're going to be replacing the ROOT web application with Liferay's app, so if there's an $CATALINA_BASE/webapps/ROOT folder, you're going to want to delete it. Check out the other web apps that might be in that folder, you may want to purge those as well.

Install Liferay Files

Expand the OSGi dependencies into Liferay Home:

$ sudo unzip liferay-dxp-osgi-*.zip -d /opt/liferay/osgi
$ sudo chown -R tomcat:tomcat /opt/liferay/osgi

Install the tools somewhere predictable:

$ sudo unzip liferay-dxp-tools-*.zip \
  -d /opt/liferay
$ sudo chown -R tomcat:tomcat /opt/liferay/tools

If you have artifacts to deploy such as a DXP license file, OSGi modules or portlet war files, themes, etc. you can put them in /opt/liferay/deploy for Liferay to pick up when it starts.

Now deploy the DXP WAR as the root web application:

$ sudo rm -rf $CATALINA_BASE/webapps/ROOT
$ sudo mkdir -p $CATALINA_BASE/webapps/ROOT
$ sudo unzip liferay-dxp-*.war -d $CATALINA_BASE/webapps/ROOT
$ sudo chown -R tomcat:tomcat $CATALINA_BASE/webapps/ROOT

Configure Liferay Home Explicitly

Do not rely on Liferay guessing the correct home directory.

Create /opt/liferay/portal-ext.properties:

liferay.home=/opt/liferay

Then pass the same value as a JVM system property (in setenv.sh as shown below). This avoids startup timing problems and makes the location obvious from the process definition:

-Dliferay.home=/opt/liferay

In production, portal-ext.properties will usually also contain database settings, mail settings, clustering-related settings, and environment-specific configuration.

liferay.home=/opt/liferay

jdbc.default.driverClassName=org.postgresql.Driver
jdbc.default.url=jdbc:postgresql://db.example.com:5432/lportal
jdbc.default.username=liferay
jdbc.default.password=change-me

Do not use the bundled Hypersonic database outside local testing.

Configure setenv.sh

This is one of the places where the official documentation is incomplete for modern Java.

Your JWS Tomcat bin/setenv.sh should include the normal Liferay memory and runtime options, but it also needs the Java module access flags required by Liferay on Java 21.

Create or update:

/opt/jws-6.2.3/tomcat/bin/setenv.sh

Use this as a starting point:

# Ensure use of JDK21 for Liferay/Tomcat
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
export PATH="$JAVA_HOME/bin:$PATH"

# Set this to your real liferay home. Exporting as
# an environment var ensures visibility within the
# running process.
export LIFERAY_HOME=/opt/liferay

CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8"
CATALINA_OPTS="$CATALINA_OPTS -Djava.net.preferIPv4Stack=true"
CATALINA_OPTS="$CATALINA_OPTS -Duser.timezone=GMT"
CATALINA_OPTS="$CATALINA_OPTS -Dliferay.home=$LIFERAY_HOME"

CATALINA_OPTS="$CATALINA_OPTS -Xms2560m -Xmx2560m"
CATALINA_OPTS="$CATALINA_OPTS -XX:NewSize=1536m" 
CATALINA_OPTS="$CATALINA_OPTS -XX:MaxNewSize=1536m"
CATALINA_OPTS="$CATALINA_OPTS -XX:MetaspaceSize=768m"
CATALINA_OPTS="$CATALINA_OPTS -XX:MaxMetaspaceSize=768m"
CATALINA_OPTS="$CATALINA_OPTS -XX:SurvivorRatio=7"

export 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/java.util=ALL-UNNAMED \
 --add-opens=java.base/sun.net.www.protocol.http=ALL-UNNAMED \
 --add-opens=java.base/sun.net.www.protocol.https=ALL-UNNAMED \
 --add-opens=java.base/sun.util.calendar=ALL-UNNAMED \
 --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED \
 --add-opens=jdk.zipfs/jdk.nio.zipfs=ALL-UNNAMED"

Make it executable:

$ sudo chmod 750 /opt/jws-6.2.3/tomcat/bin/setenv.sh
$ sudo chown tomcat:tomcat /opt/jws-6.2.3/tomcat/bin/setenv.sh

Two things to note here...

First, the memory settings are just what Liferay uses for a vanilla demo environment. You may need to increase those to handle your expected capacity and load. Liferay provides a performance white paper where they provide a suitable starting set of JVM parameters for a production environment, but of course load testing and tuning are necessary to get the right settings for your environment.

Secondly, if you're using the systemd service to start/stop JWS, you might expect that you'd manage the environment and JVM parameters "the systemd way", but you'd be wrong. Per the Red Hat JWS 6.2 Installation Guide, you still apply Tomcat environment variables and JVM parameters in the setenv.sh script. 

Configure Tomcat for Liferay

The Liferay Tomcat bundle is useful here. Compare its configuration files against the JWS Tomcat configuration and copy the relevant Liferay-specific pieces.

The important items are:

• conf/Catalina/localhost/ROOT.xml
• conf/catalina.properties
• conf/server.xml
• conf/web.xml
• conf/logging.properties
• scripts in bin/

The most important JWS-specific check is conf/catalina.properties.

Liferay’s support-tomcat.jar must be visible to Tomcat’s common class loader. Add it at the beginning of common.loader:

common.loader="${catalina.home}/webapps/ROOT/WEB-INF/
  lib/support-tomcat.jar",...

Also confirm that the HTTP connector in server.xml uses UTF-8:

<Connector
    port="8080"
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="8443"
    URIEncoding="UTF-8" />

If you are fronting JWS with Apache HTTP Server, a load balancer, or OpenShift routing, also review proxy headers, secure scheme handling, and the connector strategy before putting the node behind real traffic.

Start and Validate

Start JWS:

$ sudo systemctl start jws6-tomcat.service
$ sudo systemctl status jws6-tomcat.service

Watch the logs:

$ sudo tail -f /opt/jws-6.2.3/tomcat/logs/catalina.out

Confirm these items during first startup:

• Java reports version 21.
• Liferay Home resolves to /opt/liferay.
• OSGi modules are loaded from /opt/liferay/osgi.
• The database connection is not using Hypersonic in production.
• No startup failure points to missing Java module access.
• support-tomcat.jar is visible through common.loader.
• The portal is deployed as ROOT.

After logging in, confirm the resolved Liferay Home path from Control Panel:

Global Menu -> Control Panel -> Server Administration 
  -> Properties -> System Properties

Search for:

liferay.home

It should point to /opt/liferay.

Operational Notes

For production, the application server install is only part of the work.

You still need to decide how to manage:

• Database backup and restore.
• Document Library storage.
• Search engine configuration.
• TLS termination.
• Reverse proxy headers.
• Session strategy (Sticky sessions still recommended).
• Clustering.
• Marketplace and hot deploy policies.
• Patch and quarterly update workflow.
• SELinux context and filesystem permissions.
• Systemd restart behavior and memory limits.

On RHEL systems with SELinux enabled, do not treat permissions as only Unix ownership. Validate SELinux contexts for any directory JWS needs to read or write, especially /opt/liferay, log directories, custom mounts, and shared storage.

Tradeoffs

Installing Liferay on JWS gives you a supported enterprise Tomcat runtime, but it also means you own more of the assembly.

The Liferay Tomcat bundle is easier because Liferay has already made the runtime decisions for you. JWS is more appropriate when the client’s platform standards require Red Hat middleware support, Red Hat packaging, or a supported Tomcat distribution that fits existing operational controls.

The cost is that you must be explicit:

• Explicit Java version.
• Explicit Liferay Home.
• Explicit JVM options.
• Explicit Tomcat common class loader configuration.
• Explicit ownership and service management.

That is not a bad tradeoff, but it should be intentional.

Upgrades

So this is a considerable tradeoff. Using a Liferay Tomcat Bundle or Docker Image makes upgrading Liferay software "easy" (excludes work necessary for addressing your own customizations).

Under JWS, you're going to be doing much of this manually, but its not too complicated.

You still download the Liferay DXP war file, the OSGi dependencies zip and the tools zip.

Delete the contents of the $CATALINA_BASE/webapps/ROOT dir and expand the new war file like we did above.

The OSGi dependencies zip has to be handled with care. Delete the marketplace, portal, portal-war, state and static directories from /opt/liferay/osgi. The other folders will contain your own artifacts, you don't want to delete them or you discard your own deployed work. Unzip the OSGi dependencies zip like we did above.

Tools will also need to be handled with care. Your property files in the various /opt/liferay/tools directory will get clobbered when you unzip the tools zip. Copy them and restore them after unzipping the tools zip file.

You might also want to check the Liferay Tomcat bundle for changes in other key files like setenv.sh, catalina.properties, etc.

Final Thoughts

The main mistake to avoid is treating the Liferay Tomcat documentation as a complete JWS installation guide. It is a good reference, but for Liferay DXP 2026.Q1 on JWS 6.2.3 you need to correct three assumptions:

1. Use JDK 21, not the older Java examples.
2. Add the required Java --add-opens options.
3. Define Liferay Home explicitly instead of relying on the Tomcat parent directory.

Once those are handled, the deployment model is familiar: JWS supplies Tomcat 10.1, Liferay supplies the WAR and OSGi dependencies, and /opt/liferay becomes the stable runtime home for configuration, modules, logs, data, and operational tooling.

References

• Liferay Tomcat install guide
• Liferay DXP 2026.Q1 compatibility matrix
• Liferay JVM configuration
• Liferay Home reference
• Red Hat JBoss Web Server 6.2 installation guide