Skip to content
OpenCms documentation
OpenCms documentation

Tomcat configuration

This chapter describes how Tomcat can be configured optimally for OpenCms.

OpenCms can be deployed by copy and pasting the opencms.war file into Tomcat's webapps/ directory.

If you copy it with the standard name opencms.war, OpenCms will be reachable under the /opencms/ context path, e.g., on http://localhost:8080/opencms/.

To get rid of the /opencms/ context path, rename the opencms.war file into ROOT.war before copying the war file into Tomcat's webapps/ directory. In this way, OpenCms will be reachable as the root application, e.g., at http://localhost:8080/.

It is possible to change to port in Tomcat's conf/server.xml configuration file.

After the OpenCms war file is deployed, there are two ways to set up OpenCms: manual installation via the install wizard or the headless installation. Do not forget to find your optimal database settings before running the setup.

Sometimes OpenCms is not the only web application running in a Tomcat installation. In order to keep other applications reachable even if OpenCms is deployed as the root application, OpenCms provides a special servlet filter named OpenCmsUrlServletFilter which can be configured in the WEB-INF/web.xml configuration file in your Tomcat installation. Add the context paths of your web applications you want to be still reachable as follows:

<init-param>
  <param-name>additionalExcludePrefixes</param-name>
  <param-value>/my-servlet-1|/my-servlet-2</param-value>
</init-param>

Some less OpenCms users have reported poor XML unmarshalling performance. When OpenCms is the only web application in your servlet container, there is the possibility to improve this.

To do so, alter the SAX parser configuration by adding the optional configuration node <sax-impl-system-properties> with value true, below the sites configuration in the opencms-system.xml, as shown below.

<opencms>
  <system>
    <!-- ... -->
    <sites>
      <!-- ... -->
    </sites>
    <!-- ADD THE FOLLOWING LINE below the "sites" node or replace value "false" with "true" -->
    <sax-impl-system-properties>true</sax-impl-system-properties>
    <!-- ... -->
  </system>
</opencms>

If you set the option to true, the SAX parser implementation classes that are used by OpenCms are stored in Java system properties when OpenCms starts. If the properties are set, these implementations are directly used. If not, for each unmarshal process the implementations is detected at runtime.

Use the option only when you have no other webapp in your Tomcat. Other webapps will not start anymore, since Tomcat is unable to unmarshal any web.xml file once OpenCms has manipulated the Java system properties.

Since Tomcat 8.5 files written by Tomcat are not readable by "the world":

Tighten up the default file permissions for the .tar.gz distribution so no files or directories are world readable by default. Configure Tomcat to run with a default umask of 0027 which may be overridden by setting UMASK in setenv.sh.  (Tomcat 8.5 change log)

To remedy the situation, use the suggested override option.

The connectors that are predefined by default, e.g., the connector for port 8080, should be removed or at least commented out.

To make the changes work, restart Tomcat.

In order to run Tomcat behind an Apache proxy, configure an AJP connector.

Edit the file conf/server.xml in Tomcat's home directory and, if not already there, add an AJP connector as shown in the line below:

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

The connectors that are predefined by default, e.g., the connector for port 8080, should be removed or at least commented out.

To make the changes work, restart Tomcat.