Using mod_proxy

This page explains how to integrate the Apache httpd, Apache Tomcat and OpenCms 7 so that

  • all static resources (e.g. images or binaries) are served directly by the Apache Webserver
  • dynamic resources are served by OpenCms through Tomcat
  • The /opencms/opencms/ prefix usually required for OpenCms will be supressed

This configuration has been tested with the following components:

  • Apache httpd webserver 2.0.54 (should work with all stable versions of Apache httpd 2.0, version 1.3 will not work)
  • Apache Tomcat 5.5.7 (other versions that support the CoyoteConnector should work fine)
  • OpenCms 7

Please note: Make sure that all your server names are correctly configured in your DNS before you continue with this installation. If a server can not be reached with the name(s) used in the configuration files below, the setup will not work.

This document describes the required steps to setup the following scenario:

  1. The OpenCms server is named ${DOMAIN_NAME}
  2. The server will be served from a Tomcat installation located in the directroy ${TOMCAT_HOME}
  3. Tomcat and Apache do run on the same machine (server hardware)

Please note: Replace the previous defined variables for your environment, ie. instead of ${DOMAIN_NAME} use your domain name, ie. www.mycompany.com, and instead of ${TOMCAT_HOME} use your tomcat home path, ie.  /opt/tomcat/.

Please note: This document does not enable the Static-Export feature that needs additional configuration steps, a related Static-Export feature configuration document is available in the com.alkacon.documentation.documentation_staticexport documentation module.

Step 1: Installing OpenCms

Provided that you have a basic setup of Apache Tomcat and Apache httpd, you should install OpenCms in the ${TOMCAT_HOME}/webapps/ directory first, without modifiying the default Tomcat configuration.

In order for this setup to work you must install OpenCms as the ROOT Tomcat servlet context. Read on to learn how to do so. You have to delete or rename the Tomcat default web application  ROOT/ .

Important: Make sure that NO web application named opencms/ is installed in ${TOMCAT_HOME}/webapps/, otherwise this setup will not work.

  1. Delete or rename the Tomcat default web application ROOT/.
  2. Rename the file opencms.war to ROOT.war
  3. Restart Tomcat and proceed as described in the basic installation manual, available e.g. in the org.opencms.welcome module.

This example will install OpenCms on the  ${DOMAIN_NAME} server, so the path to the setup wizard will be http://${DOMAIN_NAME}:8080/setup.

The setup wizard should work fine now and you should be able to login into your OpenCms system. You might note that some images do not appear as they should. We will fix that in the next step.

Step 2: Configuring OpenCms

In the ${TOMCAT_HOME}/webapps/ROOT/WEB-INF/config/opencms-importexport.xml configuration file, into the staticexport/rendersettings/..prefix nodes you have to remove any occurrence of the ${SERVLET_NAME} variable. After editing, it has to look similar to:

  <rendersettings>
      <rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
      <vfs-prefix>${CONTEXT_NAME}</vfs-prefix>
      <userelativelinks>false</userelativelinks>   
      <exporturl>http://127.0.0.1:8081${CONTEXT_NAME}/handle404</exporturl>
      ...
  </rendersettings>

In the ${TOMCAT_HOME}/webapps/ROOT/WEB-INF/config/opencms-system.xml configuration file, into the system/sites node you have to configure your site, in this example it has to look similar to:

  <sites>
      <workplace-server>http://${DOMAIN_NAME}<workplace-server>
      <default-uri>/sites/default/</default-uri>
      <site server="http://${DOMAIN_NAME}" uri="/sites/default/"/>
  </sites>

This is all that you have to do in the OpenCms configuration.

Please note: After you have made these changes, OpenCms will not run properly until you have also made the changes described below in the Tomcat and Apache configuration.

Specifying Aliases

You can have more than one server name pointing to the same root folder by adding an alias to the site node. Take care that you assign every server name only once. An example of such a configuration can be seen from the listing beneath:

<site server="http://${DOMAIN_NAME}" uri="/sites/mysite/">
    <alias server="http://${DOMAIN_NAME1}"/>
    <alias server="http://${DOMAIN_NAME2}"/>
</site>
How to secure a site

You also have the option to secure resources, so that they are transmitted via the https protocol. To activate this feature for your site, you have to add a node secure in the site configuration:

<site server="http://${DOMAIN_NAME}" uri="/sites/mysite/">
    <secure server="https://${SECURE_DOMAIN_NAME}"/>
</site>

Of course, aliases and a secure site can be combined in one site node. However, you can have only one secure server. To secure a file, select the export/secure option in the context-menu of your resource. Now, you get a dialog with a radio inputs for securing a resouce, for activating the static export, and for marking the resource as internal, so that the page cannot be requested any more. If the secure page contains external data like images, stylesheets or javascripts, they need to be located in the /system folder, so that they can be transmitted via a secure and a normal server. Flags given to a folder are valid for all resources that are inside this folder.

Step 3: Configuring Tomcat

Locate the file server.xml in the ${TOMCAT_HOME}/conf/ directory. Before making any changes, please make a backup copy of this file.

Here is how the server.xml file looks after making all required changes to it:

<Server port="8005" shutdown="SHUTDOWN" debug="0">                    
    <Service name="Tomcat-Standalone">

        <!-- Define a connector for the "public visible" server name -->
        <Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
            port="8081" minProcessors="5" maxProcessors="75"
            proxyName="${DOMAIN_NAME}" proxyPort="80"
            useBodyEncodingForURI="true" enableLookups="true" redirectPort="8443"
            acceptCount="100" debug="0" connectionTimeout="20000"
            useURIValidationHack="false" disableUploadTimeout="true" />    

        <Engine name="Standalone" defaultHost="localhost" debug="0">
            <Host name="localhost" debug="0" appBase="webapps" unpackWARs="true" autoDeploy="true">
            <!-- You can change "unpackWARs" and "autoDeploy" to false after the installation is finished -->        
                <Logger className="org.apache.catalina.logger.FileLogger"
                    directory="logs"  prefix="localhost_log." suffix=".txt"
                    timestamp="true"/>
            </Host>        
        </Engine>    
    </Service>    
</Server>

You should copy and paste this code to your server.xml and change the server name ${DOMAIN_NAME} to your own server name.

This should be all you need to configure Tomcat.

Setting useBodyEncodingForURI to true ensures that GET-Requests are decoded in the appropriate encoding of the target page. Otherwise, passing parameters using GET Requests will lead to wrong parameter values if the encoding is not done with ISO-8859-1 (typically, Browsers will encode values using UTF-8). Alternatively, you can specify the encoding by setting the Attribute URIEncoding to UTF-8 or the appropriate value.

Please note that the "standard" standalone connector usually available at port 8080 has been removed, and so is not longer available. Also, all Tomcat options unrelated to OpenCms have been removed. In case you are using other Tomcat web applications that require further settings for in your server.xml , you must merge these with the OpenCms settings decribed above.

Please note: You must first finish the Apache configuration described in the next step to check if Tomcat and OpenCms work correctly.

Step 4: Configuring Apache

Locate the file httpd.conf in the ${APACHE_HOME}/conf/ directory. Before making any changes, please make a backup copy of this file.

First, make sure you have the following Apache modules enabled (around line 130 in the Apache httpd.conf ). 

LoadModule alias_module modules/mod_alias.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Now you have to configure the <VirtualHost> entries for your OpenCms installation. In this example, you have to add a <VirtualHost> entry like this:

<VirtualHost *:80>
    <Directory "${TOMCAT_HOME}/webapps/ROOT/">
	Order allow,deny
	Allow from all
    </Directory> 
    ServerName ${DOMAIN_NAME}
    ServerAdmin webmaster@alkacon.com
    DocumentRoot "${TOMCAT_HOME}/webapps/ROOT/"
    ErrorLog logs/error.log
    
    # Log only non-redirect requests in "normal" log file
    SetEnvIf Request_URI "\/opencms\/*" redirect
    CustomLog logs/localhost-access.log common env=!redirect

    ProxyPass         /opencms/                 !
    RedirectPermanent /opencms/                 http://${DOMAIN_NAME}/

    ProxyPass         /resources/               !
    ProxyPass         /export/                  !
    
    ProxyPass         /                         http://localhost:8081/opencms/
    ProxyPassReverse  /                         http://localhost:8081/opencms/
</VirtualHost>

Again, you must adjust the names of the server to your environment, and also adjust other variables like the ServerAdmin or the DocumentRoot to match your system.

That's it! Start Tomcat and Apache and see if you can log in to your OpenCms system.

Another unofficial approach using mod_jk is described in a short How-To written by Sebastian Himberger and posted at the OpenCms Forum.de.