<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>OpenCms - </title>
<meta HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; CHARSET=ISO-8859-1">
<meta name="description" content="OpenCms welcome page and release notes">
<meta name="keywords" content="OpenCms, Demo, Application, Content Management">
</head>
<body>
<h1>HowTo: Get rid of the /opencms/opencms-prefix (without installing OpenCms as
ROOT-Webapp) </h1>
<p>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.</p>
<p><strong>Table of Contents </strong></p>
<ol>
<li><a target="_self" href="#disclaimer">Disclaimer and important notes</a>
</li><li><a target="_self" href="#testedsystems">Tested Environment</a>
</li><li><a target="_self" href="#dirsandvars">Directorys and values</a>
</li>
<li><a target="_self" href="#opencms">Step 1: Configuring OpenCms</a>
</li><li><a target="_self" href="#tomcat">Step 2: Configuring Tomcat</a>
</li><li><a target="_self" href="#apache">Step 3: Configuring Apache HTTPD</a>
</li><li><a target="_self" href="#appendixa">Appendix A: Multi-Site Configuration</a>
</li><li><a target="_self" href="#lor">List of references</a>
</li><li><a target="_self" href="#contact">Contact</a>
</li><li><a target="_self" href="#changelog">Changelog</a> </li>
</ol><h2><a name="disclaimer">Disclaimer and important notes (please read)</a></h2>
<p><a name="disclaimer">While reading please bare in mind four facts:</a></p>
<ol>
<li>The configuration provided in this HowTo is mostly
based upon postings on the<a href="http://www.opencms.org/opencms/en/development/mailinglist.html">opencms-dev mailing-list</a> 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.
</li><li>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.</li><li>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
(<a href="http://www.opencms-forum.de">http://www.opencms-forum.de</a>). It will try to add them
to this HowTo ASAP.
</li><li>(English is not my native language so sorry for the bad typo ;-)) </li>
</ol>
<h3>What you will get</h3>
<p>After following this HowTo you will have the following configuration:</p>
<ul>
<li>Dynamic OpenCms content served by
http://www.yourdomain.com
</li><li>Static contect served by http://www.yourdomain.com/export</li>
</ul>
<p>This can easily be changed to another setup!</p><h2><a name="testedsystems">Tested Environment</a></h2>
<p><a name="testedsystems">The configuration described below was testet with the following system.</a></p>
<ul>
<a name="testedsystems"> </a><li>Apache Tomcat: 5.5.4, 5.5.7 (Note: At least version
5.5 is required because of the "emptySessionPath" attribute)</li><li>Sun JDK 1.5.0_01
</li><li>Apache HTTPD 2.0.53 (mod_rewrite, mod_ jk 1.2.8)
</li><li>MySQL: 4.0.21
</li><li>Server OS: Windows Server 2003 WebEdition
</li><li>OpenCms Beta 2 </li>
</ul><h2><a name="dirsandvars">Directorys & Values</a></h2>
<p><a name="dirsandvars">For this HowTo i will assume you used the following directorys & values:</a></p>
<ul>
<a name="dirsandvars"> </a><li>${WEBAPP_HOME}: The path to your webapps (e.g.
d:/webapps/)</li><li>${WEBAPP_NAME}: The webapp-name you used for OpenCms
(e.g. opencms)</li><li>${YOURDOMAIN}: The domain-name wich you want to use for OpenCms </li></ul><h2><a name="opencms">Step 1: Configuring OpenCms </a></h2>
<p><a name="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:</a></p>
<pre><a name="opencms">this.servpath="<%= OpenCms.getStaticExportManager().getVfsPrefix() %>"; </a></pre>
<p><a name="opencms">Log-off the Workplace and open "WEB-INF\config\opencms-importexport.xml".
Look for the following settings:</a></p><pre><a name="opencms"><rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix><br /><vfs-prefix>${CONTEXT_NAME}${SERVLET_NAME}</vfs-prefix></a></pre>
<p><a name="opencms">And change them to:</a></p>
<pre><a name="opencms"><rfs-prefix>/export</rfs-prefix><br /><vfs-prefix></vfs-prefix> </a></pre>
<p><a name="opencms">Save the file and shutdown your Tomcat.</a></p><h2><a name="tomcat">Step 2: Configuring Tomcat </a></h2>
<p><a name="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):</a></p><pre><a name="tomcat"> <!-- Define an AJP 1.3 Connector on port 8009 --><br /> <Connector port="8009" <strong>emptySessionPath="true"</strong> enableLookups="false" protocol="AJP/1.3" /> </a></pre>
<p><a name="tomcat">Save the file and start Tomcat.</a></p><h2><a name="apache">Step 3: Configuring Apache HTTPD </a></h2>
<p><a name="apache">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).</a></p>
<ul>
<li><a href="http://httpd.apache.org/docs-2.0/mod/mod_so.html#loadmodule">http://httpd.apache.org/docs-2.0/mod/mod_so.html#loadmodule</a>
</li><li><a href="http://jakarta.apache.org/tomcat/connectors-doc/install/apache2.html">http://jakarta.apache.org/tomcat/connectors-doc/install/apache2.html</a>
</li></ul>
<h3>Creating a workers.properties-file </h3>
<p>Create a file named "workers.properties" in the conf-directory of your
Apache-directory and insert the following text:</p><pre>worker.list=ocms<br />worker.ocms.type=ajp13<br />worker.ocms.host=localhost<br />worker.ocms.port=8009<br />worker.ocms.lbfactor=1<br /></pre>
<p>Instead of "ocms" you can choose any other value but you have to change this
in the following sections accordingly.</p>
<h3>Loading the workers.properties into Apache </h3>
<p>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).</p><pre>JkWorkersFile conf/workers.properties<br />JkLogFile logs/mod_jk.log<br />JkLogLevel info<br />JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "<br />JkOptions +ForwardKeySize +ForwardURICompat </pre>
<h3>Defining the virtual hosts </h3>
<p>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:</p>
<p><strong>${YOURDOMAIN}:</strong></p>
<pre><p># If the requested URI is located in the resources folder, do not forward the request<br />SetEnvIfNoCase Request_URI ^/${WEBAPP_NAME}/resources/.*$ no-jk<br />
# If the requested URI is static content do not forward the request
SetEnvIfNoCase Request_URI ^/export/.*$ no-jk </p><p>RewriteEngine on<br />
# If the requested URI is NOT located in the resources folder. <br /># Prepend an /${WEBAPP_NAME}/opencms to everything that does not already starts with it<br /># and force the result to be handled by the next URI-handler ([PT]) (JkMount in this case)<br />
RewriteCond %{REQUEST_URI} !^/${WEBAPP_NAME}/resources/.*$ <br />RewriteCond %{REQUEST_URI} !^/export/.*$ <br />RewriteRule !^/${WEBAPP_NAME}/opencms/(.*)$ /${WEBAPP_NAME}/opencms%{REQUEST_URI} [PT] </p><p># These are the settings for static export. If the requested resource is not already<br /># statically exported create a new request to the opencms404 handler. This has to be<br /># a new request, because the current would net get through mod_jk because of the "no-jk" var.<br />
RewriteCond %{REQUEST_URI} ^/export/.*$<br />RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}" !-f<br />RewriteCond "%{DOCUMENT_ROOT}%{REQUEST_FILENAME}/index_export.html" !-f<br />RewriteRule .* /${WEBAPP_NAME}/opencms/handle404?exporturi=%{REQUEST_URI}&%{QUERY_STRING} [P] <br />
# If the request starts with /${WEBAPP_NAME}/resources, delete the /${WEBAPP_NAME} prefix<br />RewriteCond %{REQUEST_URI} ^/${WEBAPP_NAME}/resources/.*$<br />RewriteRule ^/${WEBAPP_NAME}/(.*)$ /$1 </p><p>DocumentRoot "${WEBAPP_HOME}/${WEBAPP_NAME}/" <br />JkMount /* ocms</p></pre>
<p>Restart your Apache and you're done.
</p><h2><a name="appendixa">Appendix A: Multi-Site configuration </a></h2>
<p><a name="appendixa">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:</a></p>
<ol>
<a name="appendixa"> </a><li>Adding a new Domain (e.g. ${YOURDOMAIN2}) as a new
VirtualHost or append it to an existing VirtualHost using the<a href="http://httpd.apache.org/docs-2.0/de/mod/core.html#serveralias">ServerAlias</a> directive.
</li><li>Adding a new site to the opencms e.g. adding "<site server="http://www.${YOURDOMAIN2}" uri="/sites/${YOURDOMAIN2}/"/>"
to the sites configuration</li>
</ol>
<p><strong>Example of Sites configuration (OpenCms: opencms-importexport.xml) </strong></p>
<pre><sites><br /> <workplace-server>http://workplace.sitec.de</workplace-server><br /> <default-uri>/sites/default/</default-uri><br /><br /> <site server="http://www.sitea.de" uri="/sites/default"><br /> <alias server="http://sitea.de"/><br /> </site><br /> <site server="http://www.siteb.de" uri="/sites/siteb/"><br /> <alias server="http://siteb.de"/><br /> </site> <br /> ...<br /></sites><br /></pre>
<p><strong>Example of Sites configuration (Apache HTTPD: httpd.conf) </strong></p>
<pre><VirtualHost *:80></pre>
<pre> ServerAdmin administrator@site.com<br /> ServerName www.sitea.de<br /> ServerAlias www.sitea.de www.siteb.de sitea.de siteb.de workplace.sitec.de<br /> ErrorLog /var/log/foo/site_error.log<br /> CustomLog /var/log/foo/site_custom.foo</pre>
<pre> ${insert the virtual host stuff from above}</pre>
<pre></VirtualHost></pre>
<p><strong>Note:</strong> You don't have to add new Tomcat Connectors as required
using mod_proxy but the AJP Connector from above.
</p>
<h2><a name="lor">List of references</a></h2>
<ul>
<li><a href="http://gagne.homedns.org/%7Etgagne/articles/ProxyOpenCMS/">http://gagne.homedns.org/~tgagne/articles/ProxyOpenCMS/
</a>
</li><li><a href="http://mail.opencms.org/pipermail/opencms-dev/2004q1/010335.html">http://mail.opencms.org/pipermail/opencms-dev/2004q1/010335.html</a></li><li><a href="http://mail.opencms.org/pipermail/opencms-dev/2004q4/014121.html">http://mail.opencms.org/pipermail/opencms-dev/2004q4/014121.html</a></li><li><a href="http://jakarta.apache.org/tomcat/connectors-doc/index.html">http://jakarta.apache.org/tomcat/connectors-doc/index.html</a></li><li><a href="http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html">http://httpd.apache.org/docs-2.0/mod/mod_rewrite.html</a>
</li></ul>
<h2><a name="contact">Contact</a></h2>
<p><a name="contact">Please contact me at: "sebastian dot himberger at gmx dot de"<br /></a></p><h2><a name="changelog">Changelog</a></h2><ul>
<a name="changelog"> </a><li>24.04.2005
<ul>
<li>Rewrote HowTo to work with OpenCms 6 beta 3 (First draft)<br />
</li><li>Added Appendix about Multi-Site configuration
</li><li>Removed "Fedora Core" and "MySQL 4.1" from the list of tested systems
because of drastical configuration changes. </li>
</ul>
</li><li>24.02.2005:
<ul><li><a name="changelog">Added "Fedora Core", "MySQL 4.1" and "Tomcat 5.5.7" to the list of tested systems (thanks to Cherif)</a></li><li><a name="changelog">Added note, that at least "Tomcat 5.5" is required because of the "emptySessionPath" attribute</a></li></ul></li><li><a name="changelog">18.12.2004</a><ul><li><a name="changelog">First draft released<br /></a></li></ul></li></ul>
</body>
</html>