Installing on Tomcat

Important

Using a Liferay-Tomcat bundle or Docker image is the fastest way to get started using Liferay DXP. This article is for users who want to have full control over their Tomcat application server’s configuration.

Review the Installing a Liferay-Tomcat Bundle and Configuring a Database articles before continuing.

Installing on Tomcat requires installing the DXP WAR, installing dependencies, configuring Tomcat, and deploying DXP. You must also configure your database and mail server connections.

The simplest and easiest way to accomplish this is by downloading the Liferay Liferay-Tomcat bundle and copying the dependencies, scripts, and ROOT.xml from it to the locations described below. You can otherwise download the dependencies and manually configure Tomcat.

Prerequisites

No matter how you configure Tomcat, you must also download and install 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)

Liferay DXP/Portal requires a supported Java version to run. See JVM Configuration for recommended settings.

The Tomcat server parent folder is Liferay Home. $TOMCAT_HOME refers to Tomcat server folder. It is usually named tomcat-[version] or apache-tomcat-[version].

Installing the DXP WAR

If you’re starting with a clean Tomcat installation, delete the contents of the $CATALINA_BASE/webapps/ROOT folder. This removes the default Tomcat home page.
Extract the DXP .war file contents to $CATALINA_BASE/webapps/ROOT.

Installing Dependencies

DXP depends on many JARs included in Liferay-Tomcat bundle. Some of the bundle’s JARs are not strictly required but can still be useful. If you’re not using a Tomcat bundle, you must use the OSGi Dependencies archive you downloaded and any third-party JAR dependencies as described below.

Unzip the OSGi Dependencies ZIP file contents in the [Liferay Home]/osgi folder (create this folder if it doesn’t exist). Liferay’s OSGi runtime depends on these modules.
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 $CATALINA_BASE/webapps/ROOT/WEB-INF/shielded-container-lib folder.

See the compatibility matrix for a list of supported databases.

Note

A Hypersonic database is bundled with DXP and is useful for testing purposes. Do not use HSQL for production instances.

Note

For DXP 7.3 and earlier, unzip the Dependencies ZIP file to the $TOMCAT_HOME/lib/ext folder (create this folder if it doesn’t exist). Place your database vendor’s JDBC JAR file in that folder too.

Configuring Tomcat

Configuring Tomcat to run DXP includes these tasks:

Setting the JVM options
Specifying a web application context for DXP
Setting properties and descriptors

Copy the setenv.bat, setenv.sh, startup.bat, startup.sh, shutdown.bat, and shutdown.sh files from a DXP bundle to the $CATALINA_BASE/bin folder. Otherwise, create the setenv.bat and setenv.sh scripts.
The setenv.sh script sets JVM options for Catalina, which is Tomcat’s servlet container. Among these options is the location of the Java runtime environment. If this environment is not available on the server globally, set its location in the setenv.sh script so Tomcat can run. Do this by pointing the JAVA_HOME environment variable to a DXP-supported JRE:
```
export JAVA_HOME=/usr/lib/jvm/java-8-jdk
export PATH=$JAVA_HOME/bin:$PATH
```

Then configure Catalina’s JVM options to support DXP.

CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8 -Djava.net.preferIPv4Stack=true -Dlog4j2.formatMsgNoLookups=true -Duser.timezone=GMT -Xms2560m -Xmx2560m -XX:MaxNewSize=1536m -XX:MaxMetaspaceSize=768m -XX:MetaspaceSize=768m -XX:NewSize=1536m -XX:SurvivorRatio=7"

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.
`-Dlog4j2.formatMsgNoLookups=true`	Resolves a remote code execution (RCE) vulnerability. See LPS-143663 for details.
`-Duser.timezone=GMT`	DXP requires the application server JVM to use the GMT time zone.

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

Continue configuring Tomcat.

If you have a Liferay-Tomcat bundle, copy its $CATALINA_BASE/conf/Catalina/localhost/ROOT.xml file to the corresponding location in the application server. Create the file path if it doesn’t exist and create the ROOT.xml file.

The ROOT.xml file specifies a web application context for DXP. For example,
```
<Context crossContext="true">
    <JarScanner className="com.liferay.support.tomcat.util.scan.NOPJarScanner" />

    

    
</Context>
```
Setting crossContext="true" lets multiple web applications use the same class loader. This configuration includes commented instructions and tags for configuring a JAAS realm.

Important

The default Liferay Portal web context can be changed (e.g. localhost:8080/ to localhost:8080/myportal) by changing the XML filename, but this is not recommended.

Make sure to use UTF-8 URI encoding consistently. Copy the $CATALINA_BASE/conf/server.xml file from a Tomcat bundle to the server. Otherwise, open the $CATALINA_BASE/conf/server.xml file and add the attribute URIEncoding="UTF-8" to HTTP and AJP connectors that use redirectPort=8443. Here are examples:

Old:

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" />

New:

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

Old:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

New:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8" />

Refrain from writing access logs (optional) by commenting out the access log Valve element in $CATALINA_BASE/conf/server.xml. It’s commented out here:

<!-- <Valve className="org.apache.catalina.valves.AccessLogValve"
       directory="logs"
       prefix="localhost_access_log" suffix=".txt"
       pattern="%h %l %u %t &quot;%r&quot; %s %b" /> -->

Optionally, set the following log levels in the $CATALINA_HOME/conf/logging.properties file:

org.apache.catalina.startup.Catalina.level=INFO
org.apache.catalina.startup.ClassLoaderFactory.level=SEVERE
org.apache.catalina.startup.VersionLoggerListener.level=WARNING
org.apache.level=WARNING

For DXP 7.3 and earlier, open the $CATALINA_HOME/conf/web.xml file and set the JSP compiler to Java 8 and set DXP’s TagHandlerPool class to manage the JSP tag pool by adding the following elements above the jsp servlet element’s <load-on-startup> element.

<init-param>
    <param-name>compilerSourceVM</param-name>
    <param-value>1.8</param-value>
</init-param>
<init-param>
    <param-name>compilerTargetVM</param-name>
    <param-value>1.8</param-value>
</init-param>
<init-param>
    <param-name>tagpoolClassName</param-name>
    <param-value>com.liferay.support.tomcat.jasper.runtime.TagHandlerPool</param-value>
</init-param>

In $CATALINA_HOME/conf/web.xml, specify whether the application server should look for extra metadata, such as annotations in the application’s JARs and classes. Setting web-app element’s attribute metadata-complete="true" tells the application server there’s no extra metadata. The application server starts faster with this setting. The default is to check for extra metadata.
If you’re using Unix, Linux, or Mac OS, make the shell scripts in your $CATALINA_HOME/bin and $CATALINA_BASE/bin folders executable by running this command in each folder:
```
chmod a+x *.sh
```

Liferay’s Tomcat support JAR is part of the DXP web application. DXP uses the JAR’s file scanner. The JAR must be in the common class loader for DXP to use it. Provide Catalina access to the file by opening your $CATALINA_BASE/conf/catalina.properties file and adding this value to the beginning of the common.loader property’s comma-separated value list:

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

For DXP 7.3 and earlier, provide Catalina access to the JARs in $CATALINA_BASE/lib/ext by adding these values to the beginning of the common.loader property’s value list:

"${catalina.home}/lib/ext","${catalina.home}/lib/ext/*.jar",

Checkpoint:

The file encoding, user time-zone, and preferred protocol stack are set in the setenv.sh script.
The default memory available and Metaspace limit are set.
$CATALINA_BASE/conf/Catalina/localhost/ROOT.xml declares the web application context.
$CATALINA_BASE/conf/server.xml sets UTF-8 encoding.
$CATALINA_BASE/conf/server.xml does not declare any value for writing host access logs. (optional)
$CATALINA_HOME/conf/logging.properties sets the desired log levels.
$CATALINA_HOME/conf/web.xml sets the tag handler pool and sets Java 8 as the JSP compiler.
$CATALINA_HOME/conf/web.xml specifies for the application server to refrain from looking for extra metadata. (optional)
The scripts in Tomcat’s bin folders are executable.
The common.loader property in $CATALINA_BASE/conf/catalina.propertiesgrants Catalina access to required JARs.

The application server is configured to run DXP.

Database Configuration

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.

Otherwise, you can configure the data source in Tomcat.

Configuring the Tomcat Data Source

Make sure the database server is installed and working. If it’s installed on a different machine, verify that the DXP machine can access it.
Get the JDBC JAR from your DXP WAR (7.4+) or from the database vendor, and copy it to the $TOMCAT_HOME/lib/ext folder.

Open $CATALINA_BASE/conf/Catalina/localhost/ROOT.xml and add data source as a Resource in the web application Context:

<Context...>
    ...
    <Resource
        name="jdbc/LiferayPool"
        auth="Container"
        factory="com.zaxxer.hikari.HikariJNDIFactory"
        type="javax.sql.DataSource"
        minimumIdle="10"
        maxLifetime="0"
        maximumPoolSize="85"
        driverClassName="com.mysql.jdbc.Driver"
        dataSource.user="[place your user name here]"
        dataSource.password="[place your password here]"
        jdbcUrl="jdbc:mysql://localhost/lportal?characterEncoding=UTF8&amp;dontTrackOpenResources=true&amp;holdResultsOpenOverStatementClose=true&amp;useFastDateParsing=false&amp;useUnicode=true"
    />
</Context>

Make sure to replace the database URL, user name, and password with the appropriate values. Note that Liferay uses Hikari CP by default for the database connection pool.

In a portal-ext.properties file in [Liferay_Home], specify the data source. For example,
```
jdbc.default.jndi.name=jdbc/LiferayPool
```

The data source is configured.

If you are using JNDI connections, see Setting Up JNDI on Tomcat

Mail Configuration

The easiest way to configure mail is to use the DXP built-in mail session. If you use the built-in mail session, you may skip this section.

If you want to use Tomcat to manage the mail session, follow these steps:

Open $CATALINA_BASE/conf/Catalina/localhost/ROOT.xml and define your mail session as a Resource in the web application Context. Replace the example mail session values with your own.

<Context...>
    ...
    <Resource
        name="mail/MailSession"
        auth="Container"
        type="javax.mail.Session"
        mail.pop3.host="[place POP mail host here]"
        mail.pop3.port="110"
        mail.smtp.host="[place SMTP mail host here]"
        mail.smtp.port="465"
        mail.smtp.user="[place user name here]"
        mail.smtp.password="[place password here]"
        mail.smtp.auth="true"
        mail.smtp.starttls.enable="true"
        mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
        mail.imap.host="[place IMAP mail host here]"
        mail.imap.port="993"
        mail.transport.protocol="smtp"
        mail.store.protocol="imap"
    />
</Context>

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

The mail session is configured on Tomcat.

Deploying DXP

Start Tomcat by navigating to $CATALINA_HOME/bin and executing ./startup.sh. Alternatively, execute ./catalina.sh run to tail DXP’s log file. The log audits startup activities and is useful for debugging deployment.

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