We recommend to use the Apache webserver and the Tomcat servlet container for running OpenCms. Here is how to configure Apache to communicate with Tomcat via AJP (Apache JServ Protocol) using the module proxy_ajp, that is shipped with Apache by default (from version 2.2 onwards).
We assume, you have installed an Apache webserver, version 2.2 or higher. In particular, we assume the modules mod_rewrite
, mod_proxy
and mod_proxy_ajp
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 has not to be adjusted for the use with Apache yet.
Once the three modules are loaded, you can add suitable virtual hosts configurations for your OpenCms websites. OpenCms uses name-based hosting, i.e., the server name is used to identify the website that should be servered. 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 few as possible and that also involves some configurations 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 document root directory
<Directory "/var/lib/tomcat7/webapps/ROOT/">
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} !^/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
</VirtualHost>
Here is a short description for each of the parts of the host configuration (numbers correspond to the config-file parts):
Require all granted
" line - that was not necessary in old Apache versions.ProxyPreserveHost
is enabled, because OpenCms detects the site to server 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 at 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:
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:
VirtualHost
node has changed to the SSL port 443
.<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 document root directory
<Directory "/var/lib/tomcat7/webapps/ROOT/">
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} !^/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
</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 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>