OpenCms documentation
OpenCms documentation

Apache proxy configuration

Here we provide some hints on how to run Tomcat behind an Apache proxy server via Tomcat's  AJP (Apache JServ Protocol) and using the module proxy_ajp, that is shipped with Apache by default (from version 2.2 onwards).

We assume you have installed an Apache web server, version 2.2 or higher. In particular, we assume the modules mod_rewrite, mod_proxy and mod_proxy_ajp are present and loaded. All the modules are shipped with Apache in version 2.2 and higher. But you may have to enable them, e.g., using

a2enmod rewrite proxy proxy_ajp

to enable them in the default Apache installation on Ubuntu.

We also assume you already have a default installation of Tomcat running on your server and OpenCms installed on it, according to the requirements for using it on a server in the web. The Tomcat configuration doesn't have to be adjusted for use with Apache yet.

Learn how to install OpenCms on Tomcat correctly for using it on a web server

Once the three modules are loaded, you can add suitable virtual host configurations for your OpenCms websites. OpenCms uses name-based hosting, i.e., the server name is used to identify the website that should be served. Thus multiple sites are reachable under one server with the same IP address.

To configure a site, add a virtual host to your Apache configuration. In the default Apache installation on Ubuntu, this is preferably done via a site configuration. Site configurations are stored as /etc/apache/sites-available and enabled/ via a2ensite. Enabled site configurations are linked in the folder /etc/apache/sites-enabled/. Alternatively, your virtual host configuration can be placed in the httpd.conf file.

Here is a possible configuration that tries to increase performance by calling Tomcat as little as possible and that also involves some configuration to increase security. We configure the web-address www.example.com to be an OpenCms website.

<VirtualHost *:80>

  ServerName www.example.com
  ServerAdmin webmaster@example.com

  # 1. Use the webapp's home as document root
  DocumentRoot "/var/lib/tomcat7/webapps/ROOT"

  # 2. Allow Apache to access the export and resources folders directly
  <Directory "/var/lib/tomcat7/webapps/ROOT/export">
    Options FollowSymlinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Require all granted
  </Directory>

  <Directory "/var/lib/tomcat7/webapps/ROOT/resources">
    Options FollowSymlinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Require all granted
  </Directory>

  # 3. Set logging behavior (optional)
  ErrorLog ${APACHE_LOG_DIR}/errors_www.example.com.log
  CustomLog ${APACHE_LOG_DIR}/access_www.example.com.log combined

  # 4. Enable rewriting
  RewriteEngine On
  LogLevel mod_rewrite.c:trace1

  # 5. (Optional) Allow workplace access only via a secure site
  # Redirect all workplace requests to the secure workplace server (if present)
  # This is only needed if the OpenCms installation has one configured website
  RewriteRule ^/system/login(.*) https://opencms.example.com/system/login$1 [R=301,L]
  RewriteRule ^/system/workplace(.*) https://opencms.example.com/system/workplace$1 [R=301,L]

  # 6. (Optional) Deny access to PHP files
  RewriteCond %{REQUEST_FILENAME} (.+)\.php(.*)
  RewriteRule (.*) / [F]


  # 7. Add opencms/ prefix if required
  RewriteCond %{REQUEST_URI} !^/workplace.*$    # required since OpenCms 10
  RewriteCond %{REQUEST_URI} !^/VAADIN/.*$       # required since OpenCms 10
  RewriteCond %{REQUEST_URI} !^/resources/.*$
  RewriteCond %{REQUEST_URI} !^/export/.*$
  RewriteCond %{REQUEST_URI} !^/webdav.*$
  RewriteRule !^/opencms/(.*)$ /opencms%{REQUEST_URI} [PT]

  # 8. Rewrite rule to make OpenCms' static export working
  RewriteCond %{REQUEST_URI} ^/export/.*$
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}" !-f
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html" !-f
  RewriteRule .* /opencms/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [PT]

  # 9. Connect to Tomcat using proxy_ajp
  ProxyPreserveHost On
  ProxyPass /opencms ajp://localhost:8009/opencms
  ProxyPass /webdav(.*) ajp://localhost:8009/webdav$1
  ProxyPass /VAADIN ajp://localhost:8009/VAADIN    # required since OpenCms 10
  ProxyPass /workplace ajp://localhost:8009/workplace    # required since OpenCms 10
</VirtualHost>

Here is a short description for each of the parts of the host configuration (numbers correspond to the config-file parts):

  1. To use the webapp's home folder as the document root is not necessarily required. But it allows the avoidance of passing queries to Tomcat. All files statically exported by OpenCms reside in the webapp's home folder. Using it as the document root for your Apache virtual host allows Apache to access and serve these files directly without consulting Tomcat. This will increase performance
  2. To allow Apache to access the webapp's home directory, appropriate rights have to be granted. Note in particular the "Require all granted" line - that was not necessary in old Apache versions.
  3. Logging configuration is not necessary, but typically advantageous.
  4. URL rewriting is essential. Enable the rewrite engine - the log configuration is optional (and different in Apache < 2.4).
  5. Redirecting to a secure site for accessing the workplace is not necessary, but useful to increase security. Note that the secure site that you redirect to has to be set up separately.
  6. Forbidding access to php file is also an optional security setting not directly tied to OpenCms. With the given configuration, a "403 Forbidden" error is returned.
  7. These rewrite rules are used to remove the second "opencms/" part in typical OpenCms URLs (e.g., from the typical URL "www.example.com/opencms/opencms/index.html"  the highlighted "opencms/"
    Note the rewrite conditions: statically exported files are accessed without the "opencms/"-prefix anyway, so they must not be rewritten. The same holds for URLs that direct to OpenCms' WEBDav interface.
    OpenCms 10 requires two more exceptions to this rule to leave URLs starting with "/workplace" or "/VAADIN/" unchanged.
  8. OpenCms has a special 404-Handler that handles static export. If a file is not already exported, it is not found on the RFS and then the 404-handler is called. The file is exported and served. Thus, if a file that should be exported is not available, it is necessary to redirect to the OpenCms 404-handler.
  9. Using the module proxy_ajp, Tomcat is connected like a usual reverse proxy. Note, that the ajp protocol is used for the connection and that the URLs that Apache should handle directly are not passed. ProxyPreserveHost is enabled, because OpenCms detects the site to serve also by host name.

Secure site configuration is very similar to the configuration of an unsecured site. But some extra steps are necessary.

To use secure sites with Apache, the module mod_ssl is required. Enable it via

a2enmod ssl

SSL has to be configured and typically a self-signed or a CA-signed certificate has to be created. To generate a self-signed certificate you can use (if openssl is installed):

openssl req -new -x509 -days 365 -out server-cert.pem -keyout server-rsa-key.pem

To generate a CA-signed certificate you can use

openssl req -new -keyout server-rsa-key.pem -out server-req.pem -days 365

Place your certificates and keys in a folder of your choice, typically in Apache's conf/ folder, or in a sub-folder of /etc/ssl/, e.g. the folder /etc/ssl/localcerts/apache/. If configuring such a folder, make sure to set the permissions on the folder/certificate-files accordingly.

For more information on SSL key generation and Apache configuration, please consult some of the various good tutorials and descriptions available online.

If not already done, Apache must also be configured to listen on the SSL-port 443. Therefore, add the line

Listen 443

in the file /etc/apache2/ports.conf.

Configuring a secure virtual host is nearly identical to the configuration of a non-secure one. The differences are:

  1. The port has to be changed to 443.
  2. The SSL engine has to be configured.

In contrast to the configuration of the non-secure site above, of course you should not redirect to a secure site again (part 5).

Below, we provide the configuration of a secure site, in particular of the site where the non-secure site configured above redirects to for workplace access. It nearly mirrors the config file from the unsecured site. Only two spots are important:

  1. The port in the VirtualHost node has changed to the SSL port 443.
  2. Part 5 is replaced. Formerly, we redirected to the secured site. Now we set up the SSL engine.
<VirtualHost *:443>

  ServerName opencms.example.com
  ServerAdmin webmaster@example.com

  # 1. Use the webapp's home as document root
  DocumentRoot "/var/lib/tomcat7/webapps/ROOT"

  # 2. Allow Apache to access the export and resources folders directly
  <Directory "/var/lib/tomcat7/webapps/ROOT/export">
    Options FollowSymlinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Require all granted
  </Directory>

  <Directory "/var/lib/tomcat7/webapps/ROOT/resources">
    Options FollowSymlinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Require all granted
  </Directory>

  # 3. Set logging behavior (optional)
  ErrorLog ${APACHE_LOG_DIR}/errors_opencms.example.com.log
  CustomLog ${APACHE_LOG_DIR}/access_opencms.example.com.log combined

  # 4. Enable rewriting
  RewriteEngine On
  LogLevel mod_rewrite.c:trace1

  # 5. Enable the SSLEngine
  SSLEngine On
  SSLProxyEngine On
  SSLCertificateFile /etc/ssl/localcerts/apache/server-cert.pem
  SSLCertificateKeyFile /etc/ssl/localcerts/apache/server-rsa-key.pem

  # 6. (Optional) Deny access to PHP files
  RewriteCond %{REQUEST_FILENAME} (.+)\.php(.*)
  RewriteRule (.*) / [F]


  # 7. Add opencms/ prefix if required
  RewriteCond %{REQUEST_URI} !^/workplace.*$    # required since OpenCms 10
  RewriteCond %{REQUEST_URI} !^/VAADIN/.*$       # required since OpenCms 10
  RewriteCond %{REQUEST_URI} !^/resources/.*$
  RewriteCond %{REQUEST_URI} !^/export/.*$
  RewriteCond %{REQUEST_URI} !^/webdav.*$
  RewriteRule !^/opencms/(.*)$ /opencms%{REQUEST_URI} [PT]

  # 8. Rewrite rule to make OpenCms' static export working
  RewriteCond %{REQUEST_URI} ^/export/.*$
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}" !-f
  RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html" !-f
  RewriteRule .* /opencms/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [PT]

  # 9. Connect to Tomcat using proxy_ajp
  ProxyPreserveHost On
  ProxyPass /opencms ajp://localhost:8009/opencms
  ProxyPass /webdav(.*) ajp://localhost:8009/webdav$1
  ProxyPass /VAADIN ajp://localhost:8009/VAADIN    # required since OpenCms 10
  ProxyPass /workplace ajp://localhost:8009/workplace    # required since OpenCms 10
</VirtualHost>

In case the complete website should run on HTTPS, you can add a redirect rule to the global Apache configuration to redirect all HTTP requests immediately to the secure URL. Just add the following lines (not in a Virtual Host section):

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

You do not need to define a new virtual host or an new AJP-connector in Tomcat for each of your sites. Only add the server name through which the site should be reached to your existing virtual hosts (for secure/unsecure connections) as the server alias. Which site is served for which server name is configured in OpenCms.

Here's how to add a server alias to a virtual host:

<VirtualHost *:80>
  ServerName www.example.com
  ServerAdmin webmaster@example.com
  ServerAlias www.example.org
  ...
</VirtualHost>