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
- The /opencms/opencms/
prefix usually required for OpenCms will be supressed
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.0
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:
- The OpenCms server is named ${DOMAIN_NAME}
- The server will be served from a Tomcat installation located
in the directroy ${TOMCAT_HOME}
- Tomcat and Apache do run on the same machine (server
hardware)
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. You have to delete or rename the
Tomcat default web application ROOT/ .
Important: Make sure that NO web application named opencms/
is installed in ${TOMCAT_HOME}/webapps/, otherwise this setup will not work.
- Delete or rename the Tomcat default web application ROOT/.
- Rename the file opencms.war
to ROOT.war
- Restart Tomcat and proceed as described in the basic installation manual,
available e.g. in the org.opencms.welcome module.
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
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 ${SERVLET_NAME} variable. After editing, it has to look similar to: <rendersettings> <rfs-prefix>/export</rfs-prefix> <vfs-prefix>${SERVLET_NAME}</vfs-prefix> <userelativelinks>false</userelativelinks> <exporturl>http://127.0.0.1:8080${SERVLET_NAME}/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 not run properly 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
You also have the option 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,
please 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> <Directory "${TOMCAT_HOME}/webapps/ROOT/">
Order allow,deny
Allow from all
</Directory> 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.
That's 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.
|