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 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

Note

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/.