trunk/tools/proxytest/README

How to use Jetty 6.x with Lenya
===============================

If you want to play with Lenya in Jetty 6.1.6, please take a look at jetty6.xml
and follow the instructions in the comment header. In a nutshell:

  $LENYA_HOME:> wget http://dist.codehaus.org/jetty/jetty-6.1.6/jetty-6.1.6rc0.zip
  $LENYA_HOME:> cd tools/
  $LENYA_HOME/tools:> unzip ../jetty-6.1.6rc0.zip
  $LENYA_HOME/tools:> cd jetty-6.1.6
  $LENYA_HOME/tools/jetty-6.1.6:> java \
         -Djava.endorsed.dirs="../../externals/cocoon_2_1_x/lib/endorsed/" \
         -jar start.jar ../proxytest/jetty6.xml

It would be nice to upgrade our included Jetty to 6.x real soon now, since
the current version has a broken AJP connector that makes effective proxy
testing impossible (it basically means you have to install Tomcat).

Note that test-driving Jetty 6.1.6 is orthogonal to proxy testing; the server 
configuration includes both ajp://localhost:8009 and http://localhost:8888, 
so you can just drop it in, replacing the old version, without bothering about the
proxy stuff. 

Please follow up on bug
   http://issues.apache.org/bugzilla/show_bug.cgi?id=43729 
with success and problem reports.



How to build a proxy test scaffold
==================================

The proxy example setting simulates the following situation:

* A customer wants a company hostname and URLs without Lenya-specific
  path components for the live site.

* The server uses name-based virtual hosting with just one IP, i.e.
  there can only be one SSL vhost, which is shared among several
  customers. This implies the need for sub-directories in the proxy
  URL.

* "authoring" should be ssl-protected. There is no need for a
  customer hostname here, since it's not publicly visible.

* Any SSL-protected documents in "live" can be handled by the SSL
  vhost (not using the company hostname is ok in this case).

The desired customer hostname is customer.example.com, the live site will be
available as http://customer.example.com.

The SSL vhost is called www.example.com.

The Lenya CMS for our customer is reachable as
http[s]://www.example.com/lenya/customer/authoring/.

The global proxy for non-publication-specific resources shall be
http://www.example.com/lenya/.



FIXME: The instructions below are currently Linux-specific. 
Please contribute Windows and MacOS instructions!



First of all, start Jetty6 as described above.
Next get an Apache httpd server 2.2.x or later installed (your distro's 
packages should be fine). Then apply the following tweaks:

1. Install the bogus SSL keys:

      $LENYA_HOME/tools/proxytest:> cp *.pem /tmp 

   (yes, /tmp. it's just for testing, no need to clutter up your apache ssl 
   directory)

2. Configure some virtual hosts in your Apache HTTPD server:
   Locate an active configuration file (distribution-dependent), and add the line

      "Include $LENYA_HOME/tools/proxytest/apache_vhosts.conf"

   to it.

3. Append some fake host entries to your local resolver:

      $LENYA_HOME/tools/proxytest:> cat hosts_fake >> /etc/hosts

4. Make sure apache2 is configured to run SSL by passing it the -DSSL flag.
   The best way to do it depends on your distribution. If in doubt, omit SSL
   for now and try to add it later.

5. Restart apache2:

      $LENYA_HOME:> /etc/init.d/apache2 restart

6. Uncomment the proxy settings in the default publication config
   (src/pubs/default/config/publication.xml) and the global proxy settings
   (src/modules-core/linking/config/cocoon-xconf/global-proxies.xconf).
   You can use the patch provided in this directory:

      $LENYA_HOME:> patch -p0 < tools/proxytest/activate_proxy.diff

7. Build Lenya:

      $LENYA_HOME:> ./build.sh clean && ./build.sh

8. Surf to http://localhost:8888/webapp to check what the proxy does (look
   at the page source frequently). Then try
   http://www.example.com/lenya/default/authoring/ (authoring) and 
   http://customer.example.com (live).

9. Watch the logs in /tmp/LenyaTest_*.

This should give you a working proxy setup.