2. Set up Environment

2.1. Verify Java Installation

Check to see if you have Java (version 1.4.2 or higher) installed on your system by running the following command (sample output from a *nix system):

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

If you're going to be building the source (i.e. if you chose the source install) then you'll want to make sure that you have also installed the full J2SE, and not just the JRE.

JRE vs. JDK vs. J2SE vs. J2EE

If you're unfamiliar with the Java world, you may find the acronyms for various Java environments a little mysterious. The JRE is simply the "runtime environment" which allows you to execute compiled Java bytecode, and for many platforms this is all you usually get by default - for the very good reason that the average user just wants to run programs, and doesn't need to be building code. The JRE is what Tomcat needs to start up, and if all you're installing is the Sakai demo or binary, then the JRE will suffice for you.

To build the Sakai source, however, you'll need the JDK, which stands for "Java Developer's Kit." To both build and run Sakai you'll therefore need a combination of both the JDK and the JRE, and, happily, Sun makes this available as a unit: the J2SE (the "Java 2 Standard Edition").

If you go to the Sun site for a download, you may also run across the J2EE (the "Enterprise Edition"), or even the J2ME (the "Micro Edition"). Don't trouble yourself with these, unless you know of a particular reason why you may want them - neither is necessary for a Sakai installation.

2.2. Verify Java Environment Variables

There are three 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 (depending on your platform), 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, which will enable Tomcat to find it. 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 toStart -> 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):


Set the (or create a new) environment variable JAVA_HOME to C:\jdk1.5.0_06.


export JAVA_HOME=/usr/java/java-current


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 will cover both cases sufficiently.

Next you'll want to append to the PATH variable the location of Java commands:


Append the string ;C:\jdk1.5.0_06\bin to the end of the system variable named Path.


Not necessary.


export PATH=$PATH:$JAVA_HOME/bin/

You should test that these variables are set correctly. In both Windows XP and *nix 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.2.1 was QA'ed with Tomcat 5.5.17, 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, along with the JDK 1.4 Compatibility Package (even if you're using Java 1.5, some portions of the Sakai code will require the compatibility package, and Sakai won't start up without it). The Tomcat 5.5 instructions will tell you that Java 1.5 is required, but it's not, so long as you have the 1.4 Compatibility package.

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.

Unpack the Tomcat archive at your desired location, and unpack the compatibility package directly on top of it. 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:

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

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

Newer versions of Maven

It's important that Maven 1.0.2 be used. There are betas for Maven 1.1 and Maven 2.0 currently available, but neither will work for Sakai 2.2. Many plugins have not yet been adapted for the new Maven architecture.

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:


Create a new MAVEN_HOME environment variable to C:\maven-1.0.2. Then append to the PATH variable ;C:\maven-1.0.2\bin


export MAVEN_HOME=/usr/local/maven; export PATH=$PATH:$MAVEN_HOME/bin

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


install_repo.bat %HOMEDRIVE%%HOMEPATH%\.maven\repository


install_repo.sh $HOME/.maven/repository

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:


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:


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.