Apache Lenya 2.0 Installation Instructions

This document explains how to install Lenya 2.0 from source. There are different ways to install and run Lenya:
Choose between

1. Running Lenya standalone using the built-in Jetty servlet container
2. Using Tomcat and have the build process taking care of deploying Lenya in Tomcat

Please note that you can use other servlet containers as well, but Jetty and Tomcat are the tested ones.

In all cases, you will need to meet the following prerequisites, that describe the setup that is tested and recommended.

• Java 2 Platform, Standard Edition
  version 1.4.2 or newer, 1.6.x works with limitations.
  Get it from http://java.sun.com/j2se/1.4.2/download.html.

• Recommended: Create a directory to better organise the various source files
  In this document, we will assume the name src/ for that directory. This directory will contain the Lenya distribution as well as Cocoon.

  After expanding the downloaded archives or after a svn checkout, the directory structure should look like this:

  your_home/                  (or C:\ on Windows, not the "My Documents" folder)
    src/
      lenya-2.0.x/            $LENYA_HOME
        externals/
          cocoon_2_1_x/       $COCOON_HOME
            build/
              webapp/         $COCOON_WEBAPP
            

  The directories inside cocoon_2_1_x/ will be created when you build Cocoon, Cocoon will be built when you build Lenya. The variables will later be used in the local.build.properties file that configures the Lenya build process.

• Get Apache Lenya
  (see Download Lenya)
  Using Subversion, checkout Lenya inside the src/ directory.

1. Configure Lenya

   You need to edit your build properties and write local.build.properties. To do this, execute configure.sh (Unix) or configure.bat (Windows).

   Note

   Cocoon 2.1.x is now included in the Lenya source tree using an svn:externals property; you'll find it in the directory $LENYA_HOME/externals/cocoon_2_1_x. If you want to use Cocoon from another location, you can change the $COCOON_HOME point to your Cocoon source directory.

2. Build Lenya

   Execute build.sh (Unix) or build.bat (Windows) in your Lenya source directory, depending on your platform.

   Note

   Cocoon will be built when you build Lenya. You can manually build or clean Cocoon in $COCOON_HOME with ./build.sh or ./build.sh clean.

   MS Windows

   $LENYA_HOME > build.bat

   Unix

   $LENYA_HOME > ./build.sh

   If your build fails, because it cant delete the file cocoon.xconf.ant_patch, try the following: In $LENYA_HOME/src/targets/webapp-build.xml, line 69, add verbose="true" failonerror="false" to the <delete> tag. In $LENYA_HOME/src/targets/publets-build.xml, line 53, add verbose="true" failonerror="false" to the <delete> tag.

3. Start Lenya

   Execute lenya.sh (Unix) or lenya.bat (Windows) in your Lenya source directory, depending on your platform. Make sure that you have the environment variable JAVA_HOME defined to point to the location of the Java SDK you installed (see Prerequisites).

   MS Windows

   $LENYA_HOME > lenya.bat

   Unix

   $LENYA_HOME > ./lenya.sh

4. Test the installation

   http://localhost:8888/

1. Get Apache Tomcat for JDK 1.4
   Lenya is developed and tested with Tomcat 5.0.28; it is assumed in the following instructions, and we highly recommend it. Tomcat 4.0.0+, 4.1.24+, 5.0.18+ and 5.5.0+ should work too.

   Get it from http://jakarta.apache.org/site/binindex.cgi#tomcat-5.0.

2. Install Apache Tomcat

   See Tomcat 5.0 Setup

   MS Windows:
   Basically you only need to set the JAVA_HOME environment variable and run the Tomcat installer. Decide to run Tomcat as a Windows NT/2000/XP-Service.

3. Configure Lenya

   To install Lenya with Tomcat, you need to edit your build properties. To do this, copy $LENYA_HOME/build.properties to $LENYA_HOME/local.build.properties.

   Note

   You can use the configure.sh or configure.bat to configure your local.build.properties.

   Edit local.build.properties. For the described configuration the following settings will work (MS Windows: Don't use backslashes "\" for directory separation.) It is important that tomcat.home.dir is an absolute path. Replace $TOMCAT_HOME by your Tomcat installation directory. If your Cocoon source directory is not at ../cocoon_2_1_x relative to Lenya, then change the cocoon.webapp.dir, web.app.server and cocoon.src.dir properties.

   • web.app.server=Tomcat
   • cocoon.src.dir=$COCOON_HOME
   • tomcat.home.dir=$TOMCAT_HOME

4. Build Lenya

   Execute build in your Lenya source directory.

5. Checked versions of endorsed libraries

   Lenya and Tomcat will inter-operate correctly only if the proper versions of the Xalan and Xerces libraries are used consistently throughout the deployment. Unfortunately this can be difficult to get to work correctly since both of these libraries are shipped with Java 2 SDK, Tomcat, Cocoon and Lenya.

   The following libraries must be placed in the endorsed library directory for your deployment.

   • jakarta-bcel-20040329.jar
   • jakarta-regexp-1.5.jar
   • xalan-2.7.0.jar
   • xercesImpl-2.9.0.jar
   • xml-apis-1.3.04.jar

   They are placed by the build process in the directory specified by tomcat.endorsed.dir in build.properties. You should validate that these files are indeed in the proper location for your deployment. You must then validate that no other instances of these libraries exist in any of the following directories:

   • The Java 2 SDK endorsed standards directories. This is usually ${JAVA_HOME}/lib/endorsed/.
   • Any other location in your Tomcat deployment. Specifically, check shared/lib/, common/lib/ and server/lib/.
   • Any other location in your Lenya deployment. Specifically, check webapps/lenya/WEB-INF/lib/.

   A common symptom of incorrect library version are blank pages after starting Lenya. Try carefully checking the location and version numbers of each of the libraries.

   References:

   • Tomcat Class Loader HOWTO (http://jakarta.apache.org/tomcat/tomcat-5.0-doc/class-loader-howto.html)
   • Java 2 Endorsed Standards Override Mechanism (http://java.sun.com/j2se/1.4.2/docs/guide/standards/index.html)

6. Clear Tomcat work directory

   Tomcat's work cache may not be consistent with your newly installed Lenya. This can lead to any number of errors and exceptions. To prevent this, clear the work directory by executing build.bat or build.sh in your Lenya source directory, depending on your platform.

   MS Windows

   $LENYA_HOME > build.bat clean

   Unix

   $LENYA_HOME > ./build.sh clean

7. Restart Tomcat

   Restart Tomcat to load the Lenya webapp.

8. Test the installation

   http://localhost:8080/lenya/