Install Guide - Environment (2.4)

2. Set up Environment

2.1. Verify Java Installation

Check to see if you have Java (version 1.5) installed on your system by running the following command (sample output from a Linux system):

$ java -version
java version "1.5.0_09"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b05)
Java HotSpot(TM) Server VM (build 1.5.0_09-b05, mixed mode)

You'll want to make sure that you have also installed the full Java SE, and not just the JRE (Sakai includes .jsp and .jws files which require some compilation).

2.2. Verify Java Environment Variables

There are two Java environment variables you'll want to set for everything to function as it should, and though some of them may have already been set by your Java installation, you'll want to double-check them all. You can also look at the Sun Java Installation Instructions page at the Java web site for further details.

First you'll need to set the JAVA_HOME environment variable to point to the base directory of your Java installation. In UNIX operating systems you typically modify a startup file like ~/.bash_login to set and export these shell variables, while for Windows XP you would go to Start -> Control Panel -> System -> Advanced -> Environment Variables and then set them to point to the correct locations through the text fields of the GUI (samples below):

JRE_HOME If your machine has already set JRE_HOME for any reason, or if you want to be sure to be using a particular JRE - in the event that you have more than one JRE installed on your machine - then you'll want to set the JRE_HOME variable as well. JRE_HOME is what Tomcat uses when it starts up, but it defaults to use JAVA_HOME if JRE_HOME is not set. For most people, then, setting JAVA_HOME should cover both cases sufficiently.

Next you'll want to add Java to the PATH:

You should test that these variables are set correctly. In both Windows XP and Unix/Linux operating systems you can simply start a new shell and type the set command to see your environment variables.

2.3. Install Tomcat

Sakai 2.4.0 was QA'ed with Tomcat 5.5.23, and so that's the version we recommend, although the latest stable version will most likely not present problems. Tomcat can be downloaded as a binary from http://tomcat.apache.org/download-55.cgi. The distribution you want is the one labeled Core. Please note that the 1.4 compatibility packge will break some items and should not be installed.

Tomcat on Windows Windows users have the option of either downloading an .exe Tomcat installer (for installing Tomcat as a service) or a .zip binary. Although either may serve, they are however not entirely equivalent when it comes to operational details, and for control and brevity's sake the main instructions will assume that you grabbed the .zip. You can turn the .zip install into a service install later, however, by running service.bat from the bin directory, e.g. C:\tomcat\bin> service.bat install You can add a service name as a second argument to that script. The default is "Tomcat5". You can likewise uninstall the service by replacing "install" with "remove". Then to get the configuration window, just run this at the command prompt: C:\tomcat\bin> tomcat5w //ES//Tomcat5 Replace "Tomcat5" with whatever service name you chose for the install. You'll want to set the service to startup automatically ("Startup Type" under the General tab). Also be sure to read the Windows note in the JVM Tuning section of Post-Installation Configuration. Finally, you will likely have problems if the path to Tomcat includes spaces, as it typically does on Windows. It will be best to install it at the root level, e.g. C:\tomcat\ .

Unpack the Tomcat archive at your desired location. From this point forward these instructions will refer to the top-level Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.17) as $CATALINA_HOME. You may set this as an environment variable for convenience's sake, but this is not required. Make sure that you have write permissions to the Tomcat files and directories before proceeding, or you may later run into errors during the build phase.

2.4. Configure Tomcat

Sakai supports UTF-8, allowing for non-Roman characters, but this requires that Tomcat be configured to accept UTF-8 URLs since it ships with ISO-8859-1 as the default URL encoding. To change this setting, edit $CATALINA_HOME/conf/server.xml. Add the attribute URIEncoding="UTF-8" to the <connector> element. For example:

<Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100" debug="0"
connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>

If you want to run Tomcat on different ports than the defaults, this would also be a good time to make those changes in the server.xml file. See Tomcat configuration documentation for more details.

If you're going to run Tomcat as a standalone web server (i.e. if you're not going to connect it to the Apache web server) then you'll want to make a further minor change that may spare some confusion later. The ROOT webapp is the one served up when a request is made to your Tomcat's root URL, and so if you want users to be re-directed automatically to the Sakai application, you'll want to insert an index.html file into webapps/ROOT that prompts this re-direction. It should look something like:

<html>
    <head>
        <meta http-equiv="refresh" content="0;url=/portal">
    </head>
    <body>
        redirecting to /portal ...
    </body>
</html>

If you don't make this change you (and your users) will need to append '/portal' to the URL entered to access Sakai each time. If you intend to connect Tomcat with Apache you can handle this issue as a matter of Apache configuration, which is however outside the scope of this document.

2.5. Install Maven

Maven is the build tool used by Sakai, and the latest stable release (currently 1.0.2) can be downloaded from http://maven.apache.org/maven-1.x/start/download.html

Maven versions It's safest to use Maven 1.0.2 for now. The work for supporting Maven 2 has been introduced in Sakai 2.4, but is not yet recommended.

Choose a location for Maven, and unpack the archive there. You will have a top-level directory named maven-1.0.2.

2.6. Configure Maven

To use Maven you'll need to set two more environment variables and then create a local repository using a script provided by Maven. Just as with the Java variables, MAVEN_HOME should be set, and then Maven's binary commands should be added to the Path:

Next you'll want to create your local maven repository in your home directory by running the following command:

Home Directories in Windows You may not often deal with the notion of the home directory on Windows systems, but it's still there. By default its location is C:\Documents and Settings\yourusername. Windows also establishes it through environment variables which you've just seen above - the combination of your "home drive" location and your "home path" location: %HOMEDRIVE%%HOMEPATH% (The %-sign is how Windows brackets environment variables).

Finally, you'll need to create a build properties file in your home directory which will define some basic parameters for your Sakai build. Simply create a new text file with the filename build.properties in your home directory, and paste in the following contents:

maven.repo.remote=http://source.sakaiproject.org/maven/
maven.tomcat.home=/usr/local/tomcat/

build.properties syntax Maven is very sensitive to the syntax of the build.properties file. Be sure not to omit the trailing slashes as shown above, and be sure to change the value of maven.tomcat.home to match the path to your Tomcat installation. Further, if you are running on Windows special care is needed in identifying your tomcat home. Maven wants Unix-style forward slashes, "/", and is confused by Windows-style backslashes "\". If you have your tomcat located in c:\tomcat, for example, you need to identify it like this: maven.tomcat.home=c:/tomcat/

Finally, to confirm that you can start Maven, run the command maven -v. This should start maven and cause it to report its version. At this point your environment is prepared to build and deploy the Sakai source code.