Check to see if you have Java (version 1.5) 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)
You'll want to make sure that you have also installed the full J2SE, and not just the JRE (Sakai includes .jsp and .jws files which require some compilation).
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.
To run Sakai, however, you'll also need the JDK (Sakai includes some .jws and .jsp files which are not pre-compiled), 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.
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):
| Windows: |
Set the (or create a new) environment variable JAVA_HOME to C:\jdk1.5.0_06. |
| Mac/*nix: |
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:
| Windows: |
Append the string ;C:\jdk1.5.0_06\bin to the end of the system variable named Path. |
| Mac: |
Not necessary. |
| *nix: |
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.
Sakai 2.3.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 though you're using Java 1.5, some Sakai dependencies will require the compatibility package, and Sakai won't start up without it).
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.
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.
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
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.
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:
| Windows: |
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 |
| Mac/*nix: |
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:
| Windows: |
install_repo.bat %HOMEDRIVE%%HOMEPATH%\.maven\repository |
| Mac/*nix: |
install_repo.sh $HOME/.maven/repository |
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/
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.