Using mod_proxy

This page explains how to integrate the Apache httpd, Apache Tomcat and OpenCms 6.0 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
• without using the usually mandantory /opencms/opencms prefix (i.e. no prefix is visible to the end - user)

This configuration has been tested with the following components:

• Apache httpd webserver 2.0.44 (should work with all stable versions of Apache httpd 2.0, version 1.3 will not work)
• Apache Tomcat 4.1.18 (other versions that support the CoyoteConnector should work fine)
• OpenCms 6.0 beta

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)
4. The /opencms/opencms/ prefix usually required for OpenCms will be supressed

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.

Assuming that OpenCms is the only web application installed in your Tomcat system. Please make sure that the ${TOMCAT_HOME}/webapps/ is empty before you proceed. You probably have to delete or move the Tomcat default web applications examples/, webdav/, tomcat-docs/ and ROOT/ to empty the directoy. In case you want to keep these example web applications, you must at least remove the ROOT/ application.

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

Now use the standard steps required to install OpenCms as described in the basic installation manual, available e.g. in the org.opencms.welcome module. However, before you deploy the file opencms.war as described in step 4 of the basic installation manual, you must rename this file to ROOT.war.

Continue with the OpenCms setup as described in the basic installation manual.

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

Now, open the OpenCms configuration file ${TOMCAT_HOME}/webapps/ROOT/WEB-INF/config/opencms.properties.

And locate the app.name key, and change the value to:

app.name=ROOT

In the ${TOMCAT_HOME}/webapps/ROOT/WEB-INF/config/opencms-importexport.xml configuration file, into the staticexport/rendersettings node you have to remove any occurrence of the ${CONTEXT_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:8080/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 run correctly 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

This section explains how 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 Tomcats server.xml

Locate the file server.xml in the ${TOMCAT_HOME}/conf/ directory. Before making any changes, 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"
            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. 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 Apaches httpd.conf

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>
    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.

This should be 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.