OpenCms Apache integration

IMPORTANT: If you want to use OpenCms 7 and have a recent Apache (2.2+) at hand, have a look at an updated version on my blog.

Preface
Disclaimer
Tested Environment
Directorys and values
Configuring OpenCms
Configuring Tomcat
Configuring Apache HTTPD
Appendix A: Multi-Site
List of references
Contact
Changelog

Preface

This HowTo describes how to get rid of the /opencms/opencms-prefix (without installing OpenCms as the ROOT-Webapp). It's not fully tested yet so please provide Feedback if this configuration causes any problems for you.

Disclaimer

While reading please bare in mind four facts:

The configuration provided in this HowTo is mostly based upon postings on the opencms-dev mailing-list and i don't deserve the credit for this configuration! I only used the information floating around on the mailinglist and the apache-websites and put it together! Without these postings and tutorials this HowTo wouldn't exists.

This configuration is neither tested very well nor optimised for performance. There are probably many options wich will increase performance or simplify configuration! This HowTo is not the best way but it should provide you with the general ideas how you could solve this problem.

If you have found errors in this tutorials or have any improvements ready feel free send them to the opencms-dev mailing list or post them in the forums (http://www.opencms-forum.de). It will try to add them to this HowTo ASAP.

(English is not my native language so sorry for the bad typo ;-))

What you will get

After following this HowTo you will have the following configuration:

Dynamic OpenCms content served by http://www.yourdomain.com
Static contect served by http://www.yourdomain.com/export

This can easily be changed to another setup!

Tested Environment

The configuration described below was testet with the following system.

Apache Tomcat: 5.5.4, 5.5.7 (Note: At least version 5.5 is required because of the "emptySessionPath" attribute)
Sun JDK 1.5.0_01
Apache HTTPD 2.0.53 (mod_rewrite, mod_ jk 1.2.8)
MySQL: 4.0.21
Server OS: Windows Server 2003 WebEdition
OpenCms Beta 2

Directorys & Values

For this HowTo i will assume you used the following directorys & values:

${WEBAPP_HOME}: The path to your webapps (e.g. d:/webapps/)
${WEBAPP_NAME}: The webapp-name you used for OpenCms (e.g. opencms)
${YOURDOMAIN}: The domain-name wich you want to use for OpenCms

Configuring OpenCms

Install OpenCms using the normal setup-wizard. After restarting Tomcat log into the workplace as the administrator and open '/system/workplace/views/top_fs.jsp'. Search for the line starting with 'this.servpath=' and change the value to:

this.servpath="<%= OpenCms.getStaticExportManager().getVfsPrefix() %>";

Log-off the Workplace and open "WEB-INF\config\opencms-importexport.xml". Look for the following settings:

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

And change them to:

<rfs-prefix>/export</rfs-prefix>
 <vfs-prefix></vfs-prefix>

Save the file and shutdown your Tomcat.

Configuring Tomcat

Open the "server.xml" of your Tomcat distribution and look for the AJP-connector. Change the settings of this connector to have the following values (I have marked the setting that differs from the standard server.xml):

<!-- Define an AJP 1.3 Connector on port 8009 -->
 <Connector port="8009" emptySessionPath="true" enableLookups="false" protocol="AJP/1.3" />

Save the file and start Tomcat.

Configuring Apache HTTPD

I assume you have already configured Apache to load mod_rewrite and mod_jk. If not, checkout the following pages to get further information (these issues are more than well documented so you shouldn't have any problems).

Creating a workers.properties-file

Create a file named "workers.properties" in the conf-directory of your Apache-directory and insert the following text:

worker.list=ocms
 worker.ocms.type=ajp13
 worker.ocms.host=localhost
 worker.ocms.port=8009
 worker.ocms.lbfactor=1

Instead of "ocms" you can choose any other value but you have to change this in the following sections accordingly.

Loading the workers.properties into Apache

The Workers are used to connect your Apache to the Tomcat but you still have to tell Apache to do so. Insert the follwing into your httpd.conf (after the LoadModule-section).

JkWorkersFile conf/workers.properties
 JkLogFile logs/mod_jk.log
 JkLogLevel info
 JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
 JkOptions +ForwardKeySize +ForwardURICompat

Defining the virtual hosts

At this point you're almost finished. The last Step is to connect your domain to the OpenCms-Webapp. I assume you already have created the virtual host "${YOURDOMAIN}". Here are the settings for this virtual host:

${YOURDOMAIN}:

# If the requested URI is located in the resources folder, do not forward the request
 SetEnvIfNoCase Request_URI ^/${WEBAPP_NAME}/resources/.*$ no-jk
 
 # If the requested URI is static content do not forward the request
 SetEnvIfNoCase Request_URI ^/export/.*$ no-jk
 
 RewriteEngine on
 
 # If the requested URI is NOT located in the resources folder.
 # Prepend an /${WEBAPP_NAME}/opencms to everything that does not already starts with it
 # and force the result to be handled by the next URI-handler ([PT]) (JkMount in this case)
 
 RewriteCond %{REQUEST_URI} !^/${WEBAPP_NAME}/resources/.*$
 RewriteCond %{REQUEST_URI} !^/export/.*
 RewriteRule !^/${WEBAPP_NAME}/opencms/(.*)$ /${WEBAPP_NAME}/opencms%{REQUEST_URI} [PT]
 
 # These are the settings for static export. If the requested resource is not already
 # statically exported create a new request to the opencms404 handler. This has to be
 # a new request, because the current would net get through mod_jk because of the "no-jk" var.
 
 RewriteCond %{REQUEST_URI} ^/export/.*$
 RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}" !-f
 RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html" !-f
 RewriteRule .* /${WEBAPP_NAME}/opencms/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [P]
 
 # If the request starts with /${WEBAPP_NAME}/resources, delete the /${WEBAPP_NAME} prefix
 RewriteCond %{REQUEST_URI} ^/${WEBAPP_NAME}/resources/.*$
 RewriteRule ^/${WEBAPP_NAME}/(.*)$ /$1
 
 DocumentRoot "${WEBAPP_HOME}/${WEBAPP_NAME}/"
 JkMount /* ocms

Restart your Apache and you're done.

Appendix A: Multi-Site configuration

One nice feature of mod_jk is that, in opposite to mod_proxy, the request is forwarded to the Tomcat using the AJP protocol. This allows the Tomcat to access internal data from the original HTTP-Request sent to apache to e.g. read the HTTP_HOST header. This header can be used by OpenCms to determine wich Site is requested by the user. So it's easily possible to add a new OpenCms-Site by:

Adding a new Domain (e.g. ${YOURDOMAIN2}) as a new VirtualHost or append it to an existing VirtualHost using theServerAlias directive.
Adding a new site to the opencms e.g. adding "<site server="http://www.${YOURDOMAIN2}" uri="/sites/${YOURDOMAIN2}/"/>" to the sites configuration

Example of Sites configuration (OpenCms: opencms-importexport.xml)

<sites>
 <workplace-server>http://workplace.sitec.de</workplace-server>
 <default-uri>/sites/default/</default-uri><br />
 <site server="http://www.sitea.de" uri="/sites/default">
 <alias server="http://sitea.de"/>
 </site>
 <site server="http://www.siteb.de" uri="/sites/siteb/">
 <alias server="http://siteb.de"/>
 </site>
 ... more sites ...
 </sites>

Example of Sites configuration (Apache HTTPD: httpd.conf)

<VirtualHost *:80>
 ServerAdmin administrator@site.com
 ServerName www.sitea.de
 ServerAlias www.sitea.de www.siteb.de sitea.de siteb.de workplace.sitec.de
 ErrorLog /var/log/foo/site_error.log
 CustomLog /var/log/foo/site_custom.foo
 
 ${insert the virtual host stuff from above}
 </VirtualHost>

Note: You don't have to add new Tomcat Connectors as required using mod_proxy but the AJP Connector from above.

List of references

Contact

Please contact me at: "sebastian dot himberger at gmx dot de"

Changelog

24.04.2005
- Rewrote HowTo to work with OpenCms 6 beta 3 (First draft)
- Added Appendix about Multi-Site configuration
- Removed "Fedora Core" and "MySQL 4.1" from the list of tested systems because of drastical configuration changes.
24.02.2005:
- Added "Fedora Core", "MySQL 4.1" and "Tomcat 5.5.7" to the list of tested systems (thanks to Cherif)
- Added note, that at least "Tomcat 5.5" is required because of the "emptySessionPath" attribute
18.12.2004
- First draft released

To Top
Home