Installing Liferay DXP on Tomcat

Liferay DXP 7.1 bundled with Tomcat 9 is available on the Help Center (DXP) or Liferay Downloads (Portal CE). The Tomcat bundle contains JARs, scripts, and configuration files required for installing Liferay DXP on a clean Tomcat 9 application server. Copying these files from a Liferay DXP Tomcat bundle facilitates installing Liferay DXP on Tomcat.

Whether you copy bundle files (recommended) or download and create the files, you must download these Additional Files for DXP or Portal CE:

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

Liferay DXP requires a Java JDK 8 or 11.

Here are the basic steps for installing Liferay DXP on Tomcat:

Liferay Home is the folder containing your Tomcat server folder. After installing and deploying Liferay DXP, Liferay Home contains data, deploy, license, and osgi folders. $TOMCAT_HOME refers to your Tomcat server folder. It is usually named tomcat-[version] or apache-tomcat-[version].

Installing Dependencies

Liferay DXP depends on many JARs included by Liferay DXP Tomcat bundle. Some of the bundle’s JARs are not strictly required but can still be useful. If you don’t have a bundle, download the required JARs from third-parties, as described below.

  1. Unzip the Dependencies ZIP file contents in the $TOMCAT_HOME/lib/ext folder (create this folder if it doesn’t exist).

  2. Download a database driver .jar file and copy it to the $CATALINA_BASE/lib/ext folder. For a list of supported databases, see Liferay’s compatibility matrix

  3. Download the following JARs or copy them from a Liferay DXP Tomcat bundle to the $TOMCAT_HOME/lib/ext folder:

  4. Unzip the OSGi Dependencies ZIP file contents in the [Liferay Home]/osgi folder (create this folder if it doesn’t exist).

Configuring Tomcat

Configuring Tomcat to run Liferay DXP includes these things:

  • Setting environment variables
  • Specifying a web application context for Liferay DXP
  • Setting properties and descriptors

Optionally, you can configure Tomcat to manage these things for Liferay DXP:

Start with configuring Tomcat to run Liferay DXP.

  1. If you have a Liferay DXP Tomcat bundle, copy the setenv.bat and files from it to your $CATALINA_BASE/bin folder. If not, create these scripts.

    The scripts set 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 your server globally, you must set its location in in these files so Tomcat can run. Do this by pointing the JAVA_HOME environment variable to a Liferay 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 Liferay DXP.


    CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8 -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx2048m -XX:MaxMetaspaceSize=512m"


    set "CATALINA_OPTS=%CATALINA_OPTS% -Dfile.encoding=UTF-8 -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx2048m -XX:MaxMetaspaceSize=512m"

    This sets the file encoding to UTF-8, prefers an IPv4 stack over IPv6, prevents Tomcat from working around garbage collection bugs relating to static or final fields (these bugs don’t exist in Liferay DXP and working around them causes problems with the logging system), sets the time zone to GMT, gives the JVM 2GB of RAM, and limits Metaspace to 500MB.

    After installation, tune your system (including these JVM options) for performance.

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

    The ROOT.xml file specifies a web application context for Liferay DXP. ROOT.xml looks like this:

    <Context crossContext="true" path="">
        <!-- JAAS -->
        Uncomment the following to disable persistent sessions across reboots.
        <!--<Manager pathname="" />-->
        Uncomment the following to not use sessions. See the property
        "session.disabled" in
        <!--<Manager className="" />-->

    Setting crossContext="true" lets multiple web applications use the same class loader. This configuration includes commented instructions and tags for configuring a JAAS realm, disabling persistent sessions, and disabling sessions entirely.

  3. Provide Catalina access to the JARs in $CATALINA_BASE/lib/ext by opening your $CATALINA_BASE/conf/ file and appending this value to the common.loader property:

  4. Make sure to use UTF-8 URI encoding consistently. If you have a Liferay DXP Tomcat bundle, copy the $CATALINA_BASE/conf/server.xml file to your server. If not, open your $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:


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


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


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


    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8" />
  5. If you’re on 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


Your application server is configured to run Liferay DXP.

  1. The file encoding, user time-zone, and preferred protocol stack are set in

  2. The default memory available and Metaspace limit are set.

  3. $CATALINA_BASE/conf/Catalina/localhost/ROOT.xml declares the web application context.

  4. The common.loader property in $CATALINA_BASE/conf/ grants Catalina access to the JARs in $CATALINA_BASE/lib/ext.

  5. $CATALINA_BASE/conf/server.xml sets UTF-8 encoding.

  6. The scripts in Tomcat’s bin folders are executable.

Database Configuration

The easiest way to handle your database configuration is to let Liferay DXP manage your data source. Liferay DXP’s Basic Configuration page lets you configure Liferay DXP’s built-in data source. If you want to use the built-in data source, skip this section.

If you want Tomcat to manage your data source, follow these steps:

  1. Make sure your database server is installed and working. If it’s installed on a different machine, make sure it’s accessible from your Liferay DXP machine.

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


    The resource definition above is for a MySQL database named lportal that has a user named root whose password is root. Replace these values with your own.

  3. In a file in your Liferay Home, specify your data source:

You created a data source for Tomcat to manage and configured Liferay DXP to use it. Mail session configuration is next.

Mail Configuration

As with database configuration, the easiest way to configure mail is to let Liferay DXP handle your mail session. If you want to use Liferay DXP’s built-in mail session, skip this section and configure the mail session in the Control Panel.

If you want to manage your mail session with Tomcat, follow these steps:

  1. Open $CATALINA_BASE/conf/Catalina/localhost/ROOT.xml and add your mail session as a Resource in your web application Context. Make sure to replace the example mail session values with your own.

  2. In your file in Liferay Home, reference your mail session:

You’ve created a mail session for Tomcat to manage and configured Liferay DXP to use it.

Deploying Liferay

Now you’re ready to deploy Liferay DXP using the Liferay DXP WAR file.

  1. If you are manually installing Liferay DXP on a clean Tomcat server, delete the contents of the $CATALINA_BASE/webapps/ROOT folder. This removes the default Tomcat home page.

  2. Extract the Liferay DXP .war file to $CATALINA_BASE/webapps/ROOT.

    It’s time to launch Liferay DXP on Tomcat!

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

Congratulations on successfully installing and deploying Liferay DXP on Tomcat!

« Installing Liferay DXP ManuallyInstalling Liferay DXP on Wildfly »
Was this article helpful?
0 out of 0 found this helpful