| # 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 |
| Required version: JDK 1.6 |
| Get the JDK at http://java.sun.com |
| |
| * 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. |
| |
| * (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). |