Deploying Liferay 7.0 on to Tomcat 8.5

Tomcat 8.5 is an in-between version of Apache Tomcat 8.0 and 9.0. According to the Apache site, it contains some features in 9.0 that have been backported to 8.0. This version of Tomcat is currently in the "Supported" matrix of the Liferay DXP Compatibility Matrix, and of course, the question is: How do I set up Liferay CE/DE 7.0 with Tomcat 8.5?

The short answer is: Exactly like you would on Tomcat 8.0, which can be found here. Much of this entry will be a reproduction of those steps. The order of the steps will be a little different.

This blog post will cover the bare minimum to get Liferay CE/DE 7.0 working on Tomcat 8.5, skipping some of the extraneous steps or providing alternate steps. These steps were run on a Windows 10 machine, but should be generally applicable to Linux environments as well. Differences will be noted. Despite having been done in Windows, "forward" slashes aka "/" will be used, as that is how Tomcat wants directories to be marked.

Terminology

$TOMCAT_HOME - location of the Tomcat 8.5 directory, usually inside $LIFERAY_HOME

$LIFERAY_HOME - location of the Liferay directory that will contain Tomcat, and all the usual Liferay directories, like data, deploy, logs, osgi, etc... This directory can be located anywhere.

Step 0 - Prerequisites
- Install Java JDK 8, and configure the JAVA_HOME variable if not done already.
- Test the validity of the path by using the command "java -version" in the command prompt/terminal
- If there is a JRE_HOME variable set, remove it.

Step 1 - Acquire all the necessary files
- There are 3 required files provided by Liferay: the Liferay WAR, the Liferay dependencies, and Liferay OSGI dependencies.
- These steps were performed using Liferay DE 7.0 SP6, the portal portion of Liferay DXP. If you have a Liferay subscription and wish to also do the same, the files are available from Customer Portal, here. The files for Liferay CE 7.0 GA 5 can be found here. The individual files can be found down at the bottom of the page.
- There are a number of JAR files that are not included in default Tomcat that need to be acquired. They can either be copied over from a Liferay Tomcat bundle, or downloaded individually.

  • activation.jar
  • ccpp.jar
  • com.liferay.osgi.service.tracker.collections.jar
  • jms.jar
  • jta.jar
  • jutf7.jar
  • mail.jar
  • persistence.jar

Locations on where to get these files can be found in the regular Tomcat 8.0 steps.

REMINDER: Don't forget the database driver JAR file.

Step 2 - Extract dependency files
- Extract the Liferay dependency JARs to $TOMCAT_HOME/lib/ext. It will be necessary to create the "ext" directory.
- Extract the "osgi" directory from the OSGI dependency ZIP into $LIFERAY_HOME

Step 3 - Configure catalina.properties
- In $TOMCAT_HOME/conf/catalina.properties, find the "common.loader" property.
- Add the following to the end:

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

OR

Replace the whole property

common.loader="${catalina.base}/lib","${catalina.base}/lib/*.jar","${catalina.home}/lib","${catalina.home}/lib/*.jar","${catalina.home}/lib/ext/global","${catalina.home}/lib/ext/global/*.jar","${catalina.home}/lib/ext","${catalina.home}/lib/ext/*.jar"

- This tells Tomcat that there are extra JAR files that it needs to recognize.

Step 4 - Configure catalina.policy
- Delete the contents of catalina.policy and replace it with:

grant {
    permission java.security.AllPermission;
};
 
- Yes, delete the contents of the file and replace it with the above 3 lines.

Step 5 - Configure server.xml
- In $TOMCAT_HOME/conf/server.xml, the URIEncoding needs to be set te UTF-8 for Tomcat. Add the property URIEncoding="UTF-8" into the 2 <Connector> sections. In the default server.xml, it will be on line 69 and 116. 

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

Step 6 - Configure ROOT.xml
- In $TOMCAT_HOME/conf, create Catalina/localhost/ROOT.xml
- Add the following to ROOT.xml

<Context path="" crossContext="true">

</Context>

- Note that in the original Tomcat 8.0 steps, there is a significant chunk of commented out settings. They are not used in this basic, minimal setup. If you are using JAAS, then yes, the commented out section is necessary.

Step 7 - Extract Liferay WAR
- Delete all the directories in $TOMCAT_HOME/webapps except for ROOT. These are just sample applications.
- Delete the contents of the ROOT directory. Alternatively, ROOT can be deleted along with the other sample directories and remade as empty.
- Unzip the contents of the Liferay WAR file into the now-empty ROOT directory.

Step 8 - Configure JVM
- This is where Windows and Linux diverge.
- In $TOMCAT_HOME/bin, create setenv.bat or setenv.sh, depending on OS.
- In setenv.bat, paste the following:

set "CATALINA_OPTS=%CATALINA_OPTS% -Dfile.encoding=UTF8 -Djava.net.preferIPv4Stack=true  -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx2048m -XX:MaxMetaspaceSize=1024m"

- In setenv.sh, paste the following:

CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF8 -Djava.net.preferIPv4Stack=true  -Dorg.apache.catalina.loader.WebappClassLoader.ENABLE_CLEAR_REFERENCES=false -Duser.timezone=GMT -Xmx2048m -XX:MaxMetaspaceSize=1024m"

Note the following properties:
"-Xmx2048m" - Liferay 7.0 CAN be run with the default 1024m of JVM space, but it's not fun. I would suggest at least 2048m (2 GB) or higher for development work.

"-XX:MaxMetaspaceSize=1024m" - In Java 8, the property -XX:MaxPermSize was deprecated and is ignored. PermGen was replaced with Metaspace, which by default is unlimited. Setting it to 1024m is fine for development work.

Step 9 - portal-ext.properties (optional)
- In $LIFERAY_HOME, create or copy over a portal-ext.properties file. In the file, you can set various configurations like the database connection, and disabling of the setup-wizard.

Step 10 - Start it up
- There are 2 ways to start Tomcat from a command line/terminal.
- Executing startup.sh or startup.bat will have the process run in the background and will not output log into the current window.
- Executing catalina.sh run or catalina.bat run will have the process run in the current command line and will output log into the window. If the window is closed, or the terminal session disconnected, then the process will stop.

Skipped Steps
- In comparison to the original Tomcat 8.0 setup steps, the following sections were skipped:
JNDI database configuration
Mail configuration
PACL
Mojarra

- The database and mail configuration can also be done via portal-ext.properties, in Step 9 above.

Conclusion
There are no specific steps that differ between Tomcat 8.0 and Tomcat 8.5. Essentially, steps are the same for a basic configuration of Tomcat 8.5 with Liferay 7.0 CE/DE. PACL and Mojarra may have some differences, but I've never used them. I believe Tomcat 8.5 is just a hair faster than Tomcat 8.0, but that's a subjective topic.