Built with Apache Lenya

Apache Lenya 1.2 Install instructions

Table of Contents

Introduction
Prerequisites
Standalone Install
Install with Tomcat

Introduction

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

running Lenya standalone using the built-in Jetty servlet container
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.

Prerequisites

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

Standalone Install

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

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

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
Test the installation

http://localhost:8888/

Install with Tomcat

warning

The installation path may not contain spaces, otherwise you may get a java.net.URISyntaxException error.

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
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.
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
Build Lenya

Execute build in your Lenya source directory.
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)
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
          
```
Restart Tomcat

Restart Tomcat to load the Lenya webapp.
Test the installation

http://localhost:8080/lenya/