Apache Lenya 1.2 Install instructions

This document explains how to install Lenya 1.2.x 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
  We recommend version 1.4.2 or newer, though 1.4.1 has been reported to work as well. Version 1.5 works with limitations (see Bugzilla).
  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 My Documents)
                `-- src/
                     |-- lenya-1.2.x/            $LENYA_HOME
                     `-- cocoon-2.1.7/           $COCOON_HOME
                          `-- build/
                               `-- webapp/       $COCOON_WEBAPP
       		

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

• Get Apache Lenya
  (see Download Lenya)
  Extract the downloaded Lenya archive in the src/ directory described above. This will create lenya-1.2.x/ inside src/. If you use Subversion, checkout Lenya inside the src/ directory.

• Get Apache Cocoon
  version: 2.1.7
  Get it from http://cocoon.apache.org/mirror.cgi
  Unpack Cocoon in src/.

  
  

  Note that Cocoon is needed to build the source version of Lenya, but the resulting Lenya webapp is completely self contained and therefore does not need the Cocoon webapp to be installed. See the FAQ for details of configuration changes required when running multiple Cocoon based applications.

• Build Cocoon

  Copy the Cocoon build properties supplied by Lenya

  • local.build.properties
  • local.blocks.properties

  from $LENYA_HOME/src/cocoon/ to $COCOON_HOME.

• Compile Cocoon

  MS Windows

              $COCOON_HOME > build.bat
            

  Unix

              $COCOON_HOME > ./build.sh
            

1. Configure Lenya to point to Cocoon

   If your Cocoon source tree is set up as described above, you can skip this step. If your Cocoon source tree is not at ../cocoon-2.1.7 relative to Lenya, you need to edit your build properties. To do this, copy $LENYA_HOME/build.properties to $LENYA_HOME/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.)

   • cocoon.src.dir=$COCOON_HOME

2. Build Lenya

   Execute build.bat or build.sh in your Lenya source directory, depending on your platform.

   MS Windows

               $LENYA_HOME > build.bat
             

   Unix

               $LENYA_HOME > ./build.sh
             

3. Start Lenya

   Execute lenya.bat or lenya.sh servlet 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 servlet
             

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; this version 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.

   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.7 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.3.jar
   • xalan-2.6.0.jar
   • xercesImpl-2.6.2.jar
   • xml-apis.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/