Search the documentation
 Show GitHub edit links  Hide GitHub edit links
Documented since: 9.5 Latest revision for: 9.5 Valid for OpenCms: 10.5.2

To make OpenCms work as expected on your server you should follow the hints given on this page.

In particular, we say how to

  • get rid of the first "/opencms" in the "/opencms/opencms/" part in URLs of OpenCms webpages,
  • configure OpenCms to work with the Apache web server

We assume you have already installed Tomcat as the servlet container.

Deployment

To make OpenCms work properly with Apache, install it as the ROOT web application. To do so, rename the opencms.war file to ROOT.war. This is necessary to remove all OpenCms specific path parts (i.e., http://www.example.com/opencms/opencms/index.html) from the visible URLs.

After renaming the war file, deploy it by pasting it into Tomcat's webapps/ folder.

Setup

When OpenCms is deployed, it has to be set up. For a typical local installation, the setup wizard is used. If you can reach this wizard on your web server, you can use it as well. Therefore, follow theĀ instructions for the local installation and adjust the database configuration accordingly.

The more convienent way will be to use the setup script for setting up OpenCms. You provide a configuration and then run the script. Here you can learn about the details.

Configuration without additional webserver

Since OpenCms 10.5, OpenCms provides a special servlet filter, named OpenCmsUrlServletFilter and configured in the WEB-INF/web.xml. It will add the "/opencms" servlet name in URLs when necessary. It is already configured by default. Hence you don't have to alter your configuration. You may only need to adjust the filter configuration if for some URLs the opencms servlet should not be called. These are typically URL prefixed with names of additionally installed servlets. In that case, add the following init-param to the filter configuration.

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

Additionally, you may want to change the port your servlet container listens to 80. For Tomcat the default is 8080. You can adjust the port in the server.xml under the folder {Tomcat home}/conf/.

Configuration when using Apache

This configuration is only suitable if OpenCms has been installed as the ROOT web application in Tomcat and Apache is configured as suggested.

For OpenCms versions < 10.5, edit the file WEB-INF/config/opencms-importexport.xml in your OpenCms installation. Remove the ${SERVLET_NAME} macro, such that the original containing the macro looks as shown below:

<rendersettings>
    <rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
    <vfs-prefix>${CONTEXT_NAME}</vfs-prefix>
    ...
</rendersettings>

For OpenCms versions >= 10.5 a servlet filter (OpenCmsUrlServletFilter) is configured in the WEB-INF/web.xml. Remove the filter and the corresponding mapping. The job the filter does, is done by your Apache web server in the described configuration.

Now, the site configuration in the file WEB-INF/config/opencms-system.xml has to be adjusted. As configured below, you have a secure site to access the workplace server and an unsecured site for accessing the default site. The configuration corresponds to theĀ Apache web server configuration described in the documentation.

<sites>
    <workplace-server>https://opencms.example.com</workplace-server>
    <default-uri>/sites/default/</default-uri>
    <site server="http://www.example.com" uri="/sites/default/"/>
    ...
</sites>
If you entered the correct settings using the auto-setup, no adjustment will be necessary (as long as you stay with the one default site).

For each configured site virtual hosts have to be configured in the Apache web server. Note that you need to configure only one virtual host for secure, and one for unsecure sites. All sites can be added as aliases to that virtual host.

The OpenCms workplace should be accessed using a specific URL for the workplace. We recommend securing the OpenCms workplace using SSL.

Improving XML unmarshalling performance

When OpenCms is the only webapp in your servlet container, you can 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 are detected over and over again.

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.

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.