# FIXME: this file duplicates the contents of
# docu/src/documentation/content/xdocs/docs/2_0_x/installation/ (which is
# currently out of date)
# It would make a lot of sense to only maintain the xdocs and generate this
# file with an xslt.

Installation of the Source Version

    * Prerequisites
    * Standalone Installation (using the built-in Jetty)
    * Installation with Apache Tomcat
    * Security considerations

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). Java 1.4.2 or later should also
      work, and people are using Java 1.6 successfully in day-to-day operation.
      Get the JDK at http://java.sun.com/javase/downloads/index_jdk5.jsp.

      WARNING: There have been numerous reports of spurious VM crashes with Java versions from 
      1.5.0-07 to 1.5.0-11 both on Windows and Linux. Make sure you are using the latest available Java
      5 package for your operating system (-13 as of this writing). 
      If you encounter such crashes with more current revisions, please re-open 
      http://issues.apache.org/bugzilla/show_bug.cgi?id=42493 .

    * Apache Cocoon
      Apache Cocoon is included in the Lenya distribution. In the SVN version of Lenya, Cocoon is
      included using svn:externals. You do not have 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.

    * The patch utility
      Patch takes a patch file containing a difference listing produced by
      the diff program and applies those differences to one or more original
      files, producing patched versions. 
      All Linux distributions come with patch. Under Windows, you can download
      the utility from http://gnuwin32.sourceforge.net/packages/patch.htm .

    * (optional) An SVN client
      SVN (or subversion) is a software revision control system that is used by the Lenya community to 
      manage the development tree. If you want to use the latest development version, 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.5, version: 5.5.20 or later (earlier versions may work as well, 
      but they are not tested).
      Get the source at 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. Download Lenya (in case you don't have it already), and compute the
      MD5 checksum of the Lenya distribution file:

        md5sum <apache-lenya file>

      Then visit http://people.apache.org/~henkp/cgi-bin/md5.cgi and follow the instructions
      to verify the integrity of the file you have downloaded.

      Change into the directory where you want your Lenya sources to be.
      IMPORTANT: The pathname of this directory must not contain spaces
      or other special characters (more precisely: characters that must be
      encoded in a URL must be avoided). This is because of the following
      bug in xalan 2.7.1:

        https://issues.apache.org/jira/browse/XALANJ-2461

      Unpack the source:
 
        tar xvzf <apache-lenya>.tar.gz (for the tarball)
        unzip <apache-lenya>.zip (for the zip archive)

      OR
      
      * Check out Apache Lenya from SVN:
  
        svn checkout http://svn.apache.org/repos/asf/lenya/trunk lenya-2.0.x

   3. Configure Lenya:

      In the newly created lenya-2.0.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.
          * xalan-2.7.1.jar
          * xerces-2.9.1-xercesImpl.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/


Security Considerations

   Prior to compilation, you should verify the integrity of the file you
   just downloaded, by following the instructions at
     
     http://people.apache.org/~henkp/cgi-bin/md5.cgi
 
   In case of doubt, please ask on the mailing lists before proceeding.  

   It is advisable to run Lenya's servlet container with limited privileges,
   to reduce the impact of a possible exploit.
   You might want to create a user "lenya" with default group "lenya" for
   this, change the rights of the build/ tree accordingly, and start the
   server as that user.
   
   Additionally, you might want to consider tightening the write privileges 
   of the servlet container. At run-time, it only needs write access to
   WEB-INF/* and the publication's content and access-control store.
   While not strictly necessary, disallowing write access to other parts
   makes it harder for an attacker to manipulate the system.
   FIXME: this needs more detailed documentation.


Performing automated tests

  If you are hacking Lenya (or you have healthy paranoia levels), you might want to run automated unit
  and web tests on your Lenya checkout, especially after modifications. 
  In the lenya-2.0.x directory, do
  ./build.sh test    (to run the junit tests, requires a successful build), and
  ./build.sh modules.test.canoo  (to run the canoo web tests, requires a running servlet engine).