Deploying Liferay 7.0 on to Tomcat 8.5

Technical Blogs February 23, 2018 By Jonas Choi Staff

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.

Amendment to LDAP in 7.0/DXP entry

Technical Blogs July 28, 2017 By Jonas Choi Staff

The other day I posted a blog entry about LDAP settings in 7.0/DXP and how generating the hash values precludes the ability to have the files configured without having to go into the UI. You can read it here.

In discussion with other technical resources and through further testing, it is, in fact, possible to create the files without the need for a hash. Instead of the hash value, we replace it with the word "default" so the files look like this:

com.liferay.portal.security.ldap.authenticator.configuration.LDAPAuthConfiguration-default.config
com.liferay.portal.security.ldap.configuration.LDAPServerConfiguration-default.config
com.liferay.portal.security.ldap.exportimport.configuration.LDAPExportConfiguration-default.config
com.liferay.portal.security.ldap.exportimport.configuration.LDAPImportConfiguration-default.config

Now since we're not generating those files, we need to know what to put in them, right? Here are the necessary contents. Values marked <LIKE-THIS> are values that need to be filled in at the very least, and these are only in the LDAPServerConfiguration file.

LDAPAuthConfiguration

companyId="0"
enabled="true"
passwordEncryptionAlgorithm="NONE"
passwordPolicyEnabled="false"
required="false"
method="bind"
LDAPServerConfiguration
contactMappings=""
groupSearchFilterEnabled="true"
authSearchFilter="(&(objectCategory\=person)(mail\=@email_address@))"
userIgnoreAttributes=""
baseProviderURL="<LDAP-SERVER-HERE>"
baseDN="<LDAP-BASE-DN>"
securityPrincipal="<LDAP-PRINCIPAL>"
serverName="<SERVER-NAME>"
ldapServerId="0"
userSearchFilter="<USER-SEARCH-FILTER>"
groupMappings=["description\=description","groupName\=cn","user\=member"]
groupDefaultObjectClasses=["top","group"]
securityCredential="<LDAP-PRINCIPAL-PW>"
userDefaultObjectClasses=["top","person","inetOrgPerson","organizationalPerson"]
companyId="0"
groupsDN=""
userMappings=["emailAddress\=mail","firstName\=givenName","group\=memberOf","jobTitle\=title","lastName\=sn","password\=unicodePwd","screenName\=sAMAccountName"]
groupSearchFilter="<USER-SEARCH-FILTER>"
contactCustomMappings=""
usersDN=""
userCustomMappings=""

(Optional) LDAPExportConfiguration

companyId="0"
exportEnabled="false"
exportGroupEnabled="false"
(Optional) LDAPImportConfiguration
importGroupCacheEnabled="true"
importUserPasswordEnabled="false"
importUserPasswordAutogenerated="true"
importUserPasswordDefault="test"
importCreateRolePerGroup="false"
importOnStartup="false"
importLockExpirationTime="86400000"
companyId="0"
importEnabled="false"
importInterval="10"
importUserSyncStrategy="auth-type"
importMethod="user"
Again, once those files are filled in, they can be placed in the ${LIFERAY_HOME}/osgi/modules, or ${LIFERAY_HOME}/osgi/configs. No restart needed.
 
One final thing to note is *.cfg vs *.config. Which one is the correct one, and why? I tested this on DE 7.0 SP4 (DXP SP4), and at least from that version onward, *.config files are the correct way to go. They're a bit more versatile than *.cfg files.

LDAP Configuration in 7.0/DXP

Technical Blogs July 26, 2017 By Jonas Choi Staff

There are a great number of changes in Liferay 7.0/DXP, and one of them is how LDAP settings are managed when dealing with configuration files. In 6.2 and earlier, one could simply copy all the relevant settings into portal-ext.properties and have that load on startup. However, in 7.0, the old LDAP settings are no longer present in portal.properties, and the old way doesn't work. So how is that done?

What we need here is a *.config file. In fact, we need 4 of them.

com.liferay.portal.security.ldap.authenticator.configuration.LDAPAuthConfiguration-${HASH_VALUE}.config
com.liferay.portal.security.ldap.configuration.LDAPServerConfiguration-${HASH_VALUE}.config
com.liferay.portal.security.ldap.exportimport.configuration.LDAPExportConfiguration-${HASH_VALUE}.config
com.liferay.portal.security.ldap.exportimport.configuration.LDAPImportConfiguration-${HASH_VALUE}.config

Those are some very long filenames, and once the hash value is added in, it gets longer. This begs the question: where does the hash value come from? There are two possible ways to get a filename with a hash value: get the file from someone else, or use the UI.

Here is a straightforward way of using the UI to generate the config files.

  1. In a running Liferay system, go to Control Panel -> System Settings -> Foundation. One could search for "LDAP" from the System Settings panel as well.
  2. Edit the values as desired for LDAP Auth, LDAP Servers, and if desired, LDAP Export and LDAP Import configs. 
  3. From the Control Panel -> System Settings -> Foundation page, use the 3-dot menu (aka ellipsis menu etc...) to export the settings and save the file. These files now have the hash value along with the file name.
  4. Copy these files into the Liferay system to be configured and place them at ${LIFERAY_HOME}/osgi/modules.
  5. (Optional) To revert the LDAP settings back to default values and have them be read from the config files, use the 3-dot menu and select "Revert to Default".

Long time Liferay users will recognize the fact that once something has been entered into the UI, it will always supercede config files. The "Revert to Default" option is a new feature that allows for the config files to be read once again even after something has been entered into the UI. In short, to have LDAP be read by config files, the settings have to be entered into the UI to generate the config files.

The hash value is not unique to the system and can be used across multiple systems.

Some things to note:

  • The hash value is necessary. Liferay will not read the file properly without the hash value.
  • The file content can be edited without changing the hash value.
  • Changes to the file content are picked up without a restart.

The last note above is the major difference between the old way via portal-ext.properties, and the new way with OSGi. Changes to the files do not require a restart. No longer does a single typo cost several minutes (or more) of time waiting for the system to restart once it has been fixed!

LDAP setup via config files in Liferay 7.0/DXP has consumed my last 2.5 days, and I hope I have saved you some time and frustration.

Showing 3 results.