blob: 290a197b9c278075424ecf97c4d1887d0d3570b4 [file] [log] [blame]
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
Recommended version: JDK 1.5 (used by most developers, 1.4.2 or later should also work).
JDK 6 has not been tested yet, feedback is welcome.
Get the JDK at http://java.sun.com/javase/downloads/index_jdk5.jsp
* Apache Cocoon
Recommended version: BRANCH_2_1_X (https://svn.apache.org/repos/asf/cocoon/branches/BRANCH_2_1_X)
When you check out Lenya 1.4 from svn, Cocoon will be included as an svn external
and you don't need to download it separately.
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.
* A SVN client
SVN (or subversion) is a software revision control system that is used by the Lenya community to
manage the development tree. You will need to install a client in order to check out your local
copy of Lenya.
All Linux distributions come with svn (or subversion) packages. Under Windows, you can either use
TortoiseSVN (see http://tortoisesvn.tigris.org) or the svn package included in Cygwin (http://cygwin.com).
* (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)
This is the recommended mode of installation that is used by most
developers.
1. Get the Java SDK (see Prerequisites): e.g. J2SDK_1.5.0-11
and set JAVA_HOME
(Windows: start -> Control Panel -> System -> Advanced -> Environment Variables -> User variables
...)
2. Check out Apache Lenya from SVN:
Change into the directory where you want your Lenya sources to be, and do
svn checkout http://svn.apache.org/repos/asf/lenya/trunk lenya-1.4.x
3. Configure Lenya:
In the newly created lenya-1.4.x directory, copy build.properties to local.build.properties
and edit it to taste or use the configure script:
* Linux: configure.sh (works also on Windows with Cygwin)
* Windows: configure.bat
4. Build Lenya:
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: http://support.microsoft.com/default.aspx?scid=kb;en-us;310519&sd=tech
Linux/Unix: export JAVA_HOME=/usr/local/jdk-1.5.0 (or wherever your JDK is)
Start the build process:
* Linux: ./build.sh (works also on Windows with Cygwin)
* Windows: build.bat
5. Start Lenya:
* Linux: ./lenya.sh
* Windows: lenya.bat
6. Test the installation by pointing your browser to
http://localhost:8888/
Installation with Apache Tomcat
Watch out: Tomcat integration has not been tested much yet. You are welcome
to direct questions at or point out problems to the lenya developer mailing
list.
Installing Lenya with Tomcat is similar to stand-alone mode. Follow Steps 1-3
above, then do the steps below.
1. Get Apache Tomcat (see Prerequisites)
2. Install Apache Tomcat as per the Tomcat docs.
Important: Make sure you do not install at a location with spaces in the path, such as
C:\Tomcat Webapps\Lenya - some components in Lenya/Cocoon don't play well with such paths.
3. Configure Lenya for Tomcat
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 (see "Standalone Installation" above)
5. Check 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
7. Test the installation by pointing your browser to
http://localhost:8080/lenya/