Liferay DXP 7.2 bundled with Tomcat 9 is available on the Help Center (DXP) or the Community Downloads page (Portal CE). The Tomcat bundle contains JARs, scripts, and configuration files required for deploying Liferay DXP 7.2. Copying these files from the Liferay DXP Tomcat bundle facilitates installing Liferay DXP on an existing Tomcat application server.
Whether you copy bundle files (recommended) or download and create the files, you must download these files for DXP or Portal CE:
- Liferay DXP WAR file
- Dependencies ZIP file
- OSGi Dependencies ZIP file
Here are the basic steps for installing Liferay DXP on Tomcat:
- Installing dependencies to your application server
- Configuring your application server for Liferay DXP
- Deploying the Liferay DXP WAR file to your application server
Liferay Home
is Tomcat server’s parent folder. $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, you can download the Liferay JARs by downloading the Dependencies archive and the OSGi Dependencies archive, and you can download the third-party JARs as described below.
-
Create the folder
$TOMCAT_HOME/lib/ext
if it doesn’t exist and extract the JARs from the dependencies ZIP to it. -
Copy the following JARs from a Liferay DXP Tomcat bundle (or download them) to the
$TOMCAT_HOME/lib/ext
folder: -
Copy the JDBC driver for your database to the
$CATALINA_BASE/lib/ext
folder. -
Create an
osgi
folder in your Liferay Home. Extract the folders (i.e.,configs
,core
, and more) from OSGi ZIP file to theosgi
folder. Theosgi
folder provides the necessary modules for Liferay DXP’s OSGi runtime.
Configuring Tomcat
Configuring Tomcat to run Liferay DXP includes
- Setting environment variables
- Specifying a web application context for Liferay DXP
- Setting properties and descriptors
Optionally, if you’re not using Liferay DXP’s built-in data source or mail session, you can configure Tomcat to manage them:
Start with configuring Tomcat to run Liferay DXP.
-
If you have a Liferay DXP Tomcat bundle, copy the
setenv.bat
,setenv.sh
,startup.bat
,startup.sh
,shutdown.bat
, andshutdown.sh
files from it to your$CATALINA_BASE/bin
folder. If not, create thesetenv.bat
andsetenv.sh
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.
Unix:
CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8 -Djava.net.preferIPv4Stack=true -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xms2560m -Xmx2560m -XX:MaxMetaspaceSize=512m"
Windows:
set "CATALINA_OPTS=%CATALINA_OPTS% -Dfile.encoding=UTF-8 -Djava.net.preferIPv4Stack=true -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xms2560m -Xmx2560m -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 512MB.
After installation, tune your system (including these JVM options) for performance.
-
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 aROOT.xml
file.The
ROOT.xml
file specifies a web application context for Liferay DXP.ROOT.xml
looks like this:<Context crossContext="true" path=""> <!-- JAAS --> <!--<Realm className="org.apache.catalina.realm.JAASRealm" appName="PortalRealm" userClassNames="com.liferay.portal.kernel.security.jaas.PortalPrincipal" roleClassNames="com.liferay.portal.kernel.security.jaas.PortalRole" />--> <!-- Uncomment the following to disable persistent sessions across reboots. --> <!--<Manager pathname="" />--> <!-- Uncomment the following to not use sessions. See the property "session.disabled" in portal.properties. --> <!--<Manager className="com.liferay.support.tomcat.session.SessionLessManagerBase" />--> <Resources> <PreResources base="${catalina.base}/lib/ext/portal" className="com.liferay.support.tomcat.webresources.ExtResourceSet" webAppMount="/WEB-INF/lib" /> </Resources> </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, disabling persistent sessions, and disabling sessions entirely. -
Provide Catalina access to the JARs in
$CATALINA_BASE/lib/ext
by opening your$CATALINA_BASE/conf/catalina.properties
file and appending this value to thecommon.loader
property:,"${catalina.home}/lib/ext/global","${catalina.home}/lib/ext/global/*.jar","${catalina.home}/lib/ext","${catalina.home}/lib/ext/*.jar"
-
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 attributeURIEncoding="UTF-8"
to HTTP and AJP connectors that useredirectPort=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 "%r" %s %b" /> -->
-
Optionally, set the following log levels in your
$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
-
In
$CATALINA_HOME/conf/web.xml
, set the JSP compiler to Java 8 and set Liferay DXP’sTagHandlerPool
class to manage the JSP tag pool. Do this by adding the following elements above thejsp
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. Settingweb-app
element’s attributemetadata-complete="true"
tells the application server there’s no extra metadata. The application server starts up faster this way. The default is to check for extra metadata. -
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
Checkpoint:
Your application server is configured to run Liferay DXP.
-
The file encoding, user time-zone, and preferred protocol stack are set in your
setenv.sh
. -
The default memory available and Metaspace limit are set.
-
$CATALINA_BASE/conf/Catalina/localhost/ROOT.xml
declares the web application context. -
The
common.loader
property in$CATALINA_BASE/conf/catalina.properties
grants Catalina access to the JARs in$CATALINA_BASE/lib/ext
. -
$CATALINA_BASE/conf/server.xml
sets UTF-8 encoding. -
$CATALINA_BASE/conf/server.xml
doesn’t declare any valve 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.
Database Configuration
The easiest way to handle your database configuration is to let Liferay DXP manage your data source. If you want to use the built-in data source (recommended), skip this section.
If you want Tomcat to manage your data source, follow these steps:
-
Make sure your database server is installed and working. If it’s installed on a different machine, make sure your Liferay DXP machine can access it.
-
Open
$CATALINA_BASE/conf/Catalina/localhost/ROOT.xml
and add your data source as aResource
in your web applicationContext
:<Context...> ... <Resource name="jdbc/LiferayPool" auth="Container" type="javax.sql.DataSource" driverClassName="[place the database driver class here]" url="[place the URL to your database here]" username="[place your user name here]" password="[place your password here]" maxTotal="100" maxIdle="30" maxWaitMillis="10000" /> </Context>
Make sure to replace the database URL, user name, and password with the appropriate values. For example JDBC connection values, please see Database Templates
-
In a
portal-ext.properties
file in your Liferay Home, specify your data source:jdbc.default.jndi.name=jdbc/LiferayPool
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.
If you want to manage your mail session with Tomcat, follow these steps:
-
Open
$CATALINA_BASE/conf/Catalina/localhost/ROOT.xml
and add your mail session as aResource
in your web applicationContext
. Make sure to replace the example mail session values with your own.<Context...> ... <Resource name="mail/MailSession" auth="Container" type="javax.mail.Session" mail.pop3.host="pop.gmail.com" mail.pop3.port="110" mail.smtp.host="smtp.gmail.com" mail.smtp.port="465" mail.smtp.user="user" mail.smtp.password="password" mail.smtp.auth="true" mail.smtp.starttls.enable="true" mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory" mail.imap.host="imap.gmail.com" mail.imap.port="993" mail.transport.protocol="smtp" mail.store.protocol="imap" /> </Context>
-
In your
portal-ext.properties
file in Liferay Home, reference your mail session:mail.session.jndi.name=mail/MailSession
You’ve created a mail session for Tomcat to manage and configured Liferay DXP to use it.
Deploying Liferay DXP
Now you’re ready to deploy Liferay DXP using the Liferay DXP WAR file.
-
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. -
Extract the Liferay DXP
.war
file contents to$CATALINA_BASE/webapps/ROOT
.It’s time to launch Liferay DXP on Tomcat!
-
Start Tomcat by navigating to
$CATALINA_HOME/bin
and executing./startup.sh
. Alternatively, execute./catalina.sh 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!