Running Lenya Behind Apache with mod_proxy
- Introduction
- Declaring the Hosts
- Configuring the Apache Web Server
- Configuring Tomcat's Cookie Path
- Configuring the Publication for Proxying
- Configuring the Global Proxies
- Testing the Settings
Introduction
This tutorial aims at getting you started with a proxy environment. We're using Apache HTTPD 2.2 with the mod_proxy module. You'll find a lot of documentation on the web how to set up the web server on your machine.
Our goal is to run two virtual servers on your local machine:
- cms.example.com - the authoring environment of your publication
- www.example.com - the actual live site
Your administrators, editors etc. will use the URL http://cms.example.com to connect to the authoring environment. We'll require an SSL connection for the login usecase. Once you have established an SSL connection, your connection will stay encrypted.
The live area is mapped directly to the root of the www.example.com host. Since the authoring environment comprises different areas (for instance authoring, archive, trash), the publication root is mapped to the root of cms.example.com:
/pub/authoring <-> cms.example.com/authoring /pub/archive <-> cms.example.com/archive /pub/trash <-> cms.example.com/trash /pub/live <-> www.example.com
Declaring the Hosts
To tell your system that the example.com domains run on your local machine,
open your hosts file, usually located at /etc/hosts,
and add the following lines:
127.0.0.1 cms.example.com 127.0.0.1 www.example.com
Configuring the Apache Web Server
There are multiple options to connect the Apache web server, which acts as the reverse proxy, to the Tomcat servlet container. The two most common ways are
- mod_proxy
- mod_proxy_ajp
- mod_jk
mod_proxy is the classic, proven approach. The AJP protocol is newer, easier to set up and provides seamless SSL integration. For more information on which connector to choose, refer to the Tomcat connectors FAQ.
After configuring the Apache web server, you can restart it using
$ sudo apachectl restart
Configuring Tomcat's Cookie Path
You'll certainly run into cookie problems when using a non-empty context path
(like lenya14 in the example above) instead of running Lenya in the root context.
This causes errors like "The session doesn't contain the identity.".
To avoid these problems, edit $TOMCAT_HOME/conf/server.xml and set the
emptySessionPath attribute of the Tomcat connector configuration to true.
You find more information in the Apache
Tomcat configuration reference.
Configuring the Publication for Proxying
When you use a proxy, Lenya has to convert all internal links accordingly.
Therefore you have to tell the publication about the proxy configuration.
Open the file $PUBLICATION_HOME/config/publication.xml and uncomment
and modify the <proxy/> elements:
<proxies> <proxy area="authoring" ssl="true" url="https://cms.example.com/authoring"/> <proxy area="authoring" ssl="false" url="http://cms.example.com/authoring"/> <proxy area="trash" ssl="true" url="https://cms.example.com/trash"/> <proxy area="trash" ssl="false" url="http://cms.example.com/trash"/> <proxy area="archive" ssl="true" url="https://cms.example.com/archive"/> <proxy area="archive" ssl="false" url="http://cms.example.com/archive"/> <proxy area="live" ssl="true" url="https://www.example.com"/> <proxy area="live" ssl="false" url="http://www.example.com"/> </proxies>
Configuring the Global Proxies
The application-wide (publication independent) proxies are configured in
WEB-INF/cocoon.xconf. Look for the declaration of the GlobalProxies
service and update this entry:
<component logger="lenya.proxy"
role="org.apache.lenya.cms.linking.GlobalProxies"
class="org.apache.lenya.cms.linking.impl.GlobalProxiesImpl">
<proxy ssl="false" url="http://cms.host.com"/>
<proxy ssl="true" url="https://cms.host.com"/>
</component>
Testing the Settings
After re-deploying the publication and restarting your servlet container, you should be able to access the authoring environment of the default publication at the URL http://cms.example.com/.