Installation of the Source Version * Prerequisites * Standalone Installation (using the built-in Jetty) * Installation with Apache Tomcat Prerequisites The following list describes the setup that is tested and recommended. Please note that you can use other servlet containers as well, but Jetty and Tomcat are the tested ones. * Java 2 Platform, Standard Edition version: 1.4.2 or newer, 1.5.x not tested. source: http://java.sun.com/j2se/1.4.2/download.html * Apache Cocoon version: 2.1.5.1 source: http://cocoon.apache.org/mirror.cgi Note that Cocoon is needed when building the source version of Lenya, but the resulting Lenya webapp is completely self contained and therefore it does not need the Cocoon webapp to be installed. See the FAQ for details of configuration changes required when running multiple Cocoon based applications. * (optional) Apache Tomcat for JDK 1.4 version: 5.0.28 or newer, 5.5.x not tested. source: http://jakarta.apache.org/site/binindex.cgi Note that Lenya ships with Jetty and therefore does not need a servlet container to be installed. Standalone Installation (using the built-in Jetty) 1. Get the Java SDK (see Prerequisites) 2. Get Apache Cocoon (see Prerequisites) 3. Get Apache Lenya (see Download Lenya) 4. Extract the downloaded Lenya archive to the lenya-trunk directory as described below. If you use Subversion, create your Lenya checkout inside the src directory as described below. It is recommended to use the following directory structure for an easier build experience. your_home/ (or c:\ on Windows, NOT My Documents) `-- src/ |-- lenya-trunk/ $LENYA_HOME `-- cocoon/ $COCOON_HOME `-- build/ `-- webapp/ $COCOON_WEBAPP 5. Configure Lenya 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 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 * tomcat.home.dir=$TOMCAT_HOME 6. 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 7. 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 8. Test the installation http://localhost:8888/ Installation with Apache Tomcat Installing Lenya with Tomcat is mostly the same procedure. Follow Steps 1-4, then do the steps below. 1. get Apache Tomcat (see Prerequisites) 2. Install Apache Tomcat See Tomcat 5.0 Setup MS Windows: Basically this is setting the JAVA_HOME environment variable and running the Tomcat installer. Decide to run Tomcat as a Windows NT/2000/XP-Service. Warning Make sure you do not install at a location with spaces in the path. 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 relative to Lenya, then change the cocoon.webapp.dir and cocoon.src.dir properties. * cocoon.src.dir=$COCOON_HOME * tomcat.home.dir=$TOMCAT_HOME 4. Build Lenya Execute build install 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. Restart Tomcat Restart Tomcat to load the Lenya webapp. 7. Test the installation http://localhost:8080/lenya/