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:
- 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 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.
-
Unzip the Dependencies ZIP file contents in the
$TOMCAT_HOME/lib/ext
folder (create this folder if it doesn’t exist). -
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 -
Download the following JARs or copy them from a Liferay DXP Tomcat bundle to the
$TOMCAT_HOME/lib/ext
folder: -
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.
-
If you have a Liferay DXP Tomcat bundle, copy the
setenv.bat
andsetenv.sh
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.
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 -Xmx2048m -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 -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.
-
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" />
-
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
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. -
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:
-
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.
-
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="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8" username="root" password="root" maxTotal="100" maxIdle="30" maxWaitMillis="10000" /> </Context>
The resource definition above is for a MySQL database named
lportal
that has a user namedroot
whose password isroot
. Replace these values with your own. -
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 and configure the mail session in the Control Panel.
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
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 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!