1.0 Get the Sakai CLE source code
Sakai source code can also be checked out anonymously from our SVN repository. The latest development work is located in /trunk
; stable releases can be found in /tags
while maintenance and other work is performed in /branches
.
Starting with Sakai 2.6, Sakai common services (e.g., authz, content, event, site, tool, user, etc.) have been repackaged and refactored as the Sakai Kernel (K1). In most cases, you will never have to check out the kernel manually as Sakai kernel dependencies are managed by Maven.
2.8 release tag
To checkout a stable release tag issue the following svn command from the terminal:
svn co https://source.sakaiproject.org/svn/sakai/tags/sakai-2.8.3
2-8-x maintenance branch
The latest bug fixes for a particular release can be found in our maintenance branches. Please note that certain maintenance branch fixes require database schema changes. You can check out the maintenance branch by issuing the following command from the terminal:
svn co https://source.sakaiproject.org/svn/sakai/branches/sakai-2.8.x
2.0 Verify/Install Java 1.6
2.1 Set Java environment variables
3.0 Install Subversion 1.6+
3.1 Set Subversion environment variables
4.0 Install Maven 2.2.1
The Apache Maven project management framework provides Sakai with "a set of build standards, artifact repository model and a software engine that manages and describes projects" (Better Builds, p. 22). As part of the installation process you will use Maven as a build tool in order to compile, test and deploy Sakai to a servlet container such as Apache Tomcat.
Maven 2.2.1 is the required for performing Sakai 2.8 builds.
Maven 3.0 is currently NOT compatible with Sakai 2.8.
You can download Maven at
http://maven.apache.org/download.html
Extract the distribution archive into your installation directory of choice, e.g. /opt/maven/apache-maven-2.2.1
. Confirm that you have installed the correct version of Maven and can start it by issuing mvn --version
from the terminal. At this point your environment is prepared to build and deploy the Sakai source code.
mvn --version
Apache Maven 2.2.1 (r801777; 2009-08-06 15:16:01-0400) Java version: 1.6.0_20 Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home Default locale: en_US, platform encoding: MacRoman OS name: "mac os x" version: "10.6.3" arch: "x86_64" Family: "mac"
4.1 Set Maven environment variables
A number of environment variables must be set for optimal Maven performance. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile
. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables
and set your Maven environment variables via the GUI.
Set the MAVEN_HOME
environment variable to point to the base directory of your Maven installation and add the Maven /bin
directory to your PATH
variable:
Variable |
Unix/Mac |
Windows |
---|---|---|
MAVEN_HOME |
|
|
PATH |
|
|
Windows: append string to the end of the Path
system variable
MAVEN_OPTS
Maven does not read JAVA_OPTS
on start up, resulting occasionally in "Out of Memory" errors when building Sakai. To assure sufficient memory allocation during builds, you should add a MAVEN_OPTS
environment variable as defined below. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile
. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables
and set JAVA_HOME
via the GUI.
export MAVEN_OPTS='-Xms512m -Xmx1024m -XX:PermSize=64m -XX:MaxPermSize=128m'
4.2 Create a local Maven repository
Create a local Maven repository (.m2) in your home directory:
Unix/Mac
cd $HOME mkdir -p .m2/repository
Windows
mkdir %HOMEDRIVE%%HOMEPATH%\.M2\repository
In Windows the default location of your home directory is C:\Documents and Settings\yourusername
. Windows also establishes it through environment variables by combining your "home drive" location and your "home path" location, i.e. %HOMEDRIVE%%HOMEPATH%
. (The %
-sign is how Windows brackets environment variables).
4.3 Create a Maven settings.xml
file
Create a new XML file in your .m2 directory called settings.xml. Add the following lines, specifying the actual location of your Tomcat home directory (in this example /opt/tomcat
).
Do not include trailing / or \ slashes in the directory paths.
Sakai does not use the standard appserver.home
so you must include a <sakai.appserver.home>
element in your settings.xml
file. For Windows users, the sakai.appserver.home
value must be C:\opt\tomcat
.
Unix/Mac |
Windows |
---|---|
<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>tomcat5x</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <appserver.id>tomcat5x</appserver.id> <appserver.home>/opt/tomcat</appserver.home> <maven.tomcat.home>/opt/tomcat</maven.tomcat.home> <sakai.appserver.home>/opt/tomcat</sakai.appserver.home> <surefire.reportFormat>plain</surefire.reportFormat> <surefire.useFile>false</surefire.useFile> </properties> </profile> </profiles> </settings> |
<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>tomcat5x</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <appserver.id>tomcat5x</appserver.id> <appserver.home>c:\opt\tomcat</appserver.home> <maven.tomcat.home>c:\opt\tomcat</maven.tomcat.home> <sakai.appserver.home>c:\opt\tomcat</sakai.appserver.home> <surefire.reportFormat>plain</surefire.reportFormat> <surefire.useFile>false</surefire.useFile> </properties> </profile> </profiles> </settings> |
Optionally, you can specify the Tomcat home to be an environment variable:
<maven.tomcat.home>${env.CATALINA_HOME}</maven.tomcat.home>
Users who utilize a network proxy need to add a <proxies>
section to settings.xml
:
<proxies> <proxy> <active>true</active> <protocol>http</protocol> <host>www.your.proxy.host</host> <port>80</port> <username>your_username</username> <password>your_password</password> <nonProxyHosts>localhost</nonProxyHosts> </proxy> </proxies>
If you do not use a username or password for your proxy exclude the <username>
and <password>
elements. You only need the nonProxyHosts option
if you have a local maven repo that does not require the proxy to be accessed. Maven 2.0 does not support Microsoft's NTLN authentification scheme. If you connect to a proxy like ISA you will need to use a tool such as http://ntlmaps.sourceforge.net/ to proxy your traffic.
5.0 Install Tomcat 5.5.33
Tomcat 5.5: we recommend Tomcat 5.5.33 in order to avoid certain Tomcat security vulnerabilities present in earlier releases.
Tomcat 6.0 / 7.0: Sakai 2.8 has not been tested in Tomcat 6.0 or 7.0 and will not run in either version of Tomcat without configuration changes. Adopters are advised to stay with the Tomcat 5.5. series.
JAVA_OPTS: running Sakai 2.x in Tomcat 5.5.27+ requires JAVA_OPTS
modifications (see below).
Sakai installations should always be accompanied by a fresh install of Tomcat. It provides a clean environment that simplifies troubleshooting if problems are encountered during the startup phase.
The Apache Tomcat servlet container provides an ideal environment for running Sakai as a web application. Tomcat implements both the Java Servlet and JavaServer Pages (JSP) specifications and can be run in standalone mode or in conjunction with a web application server such as the Apache HTTP server or JBoss. Sakai 2.8 works with the Tomcat 5.5 series.
Tomcat can be downloaded as a binary install from http://archive.apache.org/dist/tomcat/tomcat-5/
Choose the core distribution. Windows users have the option of downloading either a Windows Service Installer .exe
or a binary *.zip archive. We recommend the *.zip archive over the installer because configuration and log viewing are easier. You can later convert the .zip install into a service install by running /bin/service.bat
(see below for more details).
Unpack the Tomcat archive into your installation directory of choice, e.g. /opt/
. Unix/Mac users should create a symbolic link (e.g., ln -s apache-tomcat-5.5.33
) while Windows users should simply rename the base Tomcat directory to /tomcat
to simplify the path.
Tomcat pathnames
Windows users should ensure that the Tomcat path includes no spaces as this causes errors with JavaServer Faces (JSF) tools in Sakai.
Good: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\
Bad: C:\program files\tomcat\, C:\opt\apache tomcat 5.5.33\
Tomcat permissions
Unix/Mac users should make sure that they have write permissions to the Tomcat servlet container files and directories before proceeding or startup permission errors may occur.
Tomcat JDK 1.4 Compatibility Package
Do not download and install the JDK 1.4 Compatibility Package. Sakai 2.8 will not run should you install it.
5.1 Set Tomcat environment variables
By convention, the base Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.33
) is referred to as $CATALINA_HOME
. As a convenience, you should create a $CATALINA_HOME
environment variable. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile
. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables
and set your Tomcat environment variables via the GUI.
Set the CATALINA_HOME
environment variable to point to the base directory of your Tomcat installation and add the Tomcat /bin
directory to your PATH
variable:
Variable |
Unix/Mac |
Windows |
---|---|---|
CATALINA_HOME |
|
|
PATH |
|
|
Windows: append string to the end of the Path
system variable.
5.2 Configure Tomcat
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's configuration documentation for more details.
If you plan to run Tomcat as a standalone web server as opposed to running it in conjunction with the Apache HTTP server then you will 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 Tomcat's root URL. If you want users to be re-directed automatically to the Sakai application, you must insert an index.html
file into /webapps/ROOT
that prompts this re-direction. The index.html
file should look something like the following:
<html> <head> <title>Redirecting to /portal</title> <meta http-equiv="Refresh" content="0:URL=/portal"> </head> <body bgcolor="#ffffff" onLoad="javascript:window.location='/portal';"> <div style="margin:18px;width:288px;background-color:#cccc99;padding:18px;border:thin solid #666600;text-align:justify"> <p style="margin-top:0px"> You are being redirected to the Sakai portal. If you are not automatically redirected, use the link below to continue:<br/> <a href="/portal">Take me to the Sakai portal</a> </p> </body> </html>
Neglecting this adjustment will force users to append /portal
to the URL entered to access Sakai each time. If you intend to connect Tomcat with Apache HTTP server you can configure redirections from within Apache, an option that lies outside the scope of this document.
5.3 Tomcat memory management
You can better manage Tomcat memory usage by creating a setenv.sh/.bat file defining JAVA_OPTS
environment variable settings in the tomcat/bin
directory.
Mac/Unix: create a file called setenv.sh and add the following line:
export JAVA_OPTS='-server -Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=512m -XX:NewSize=192m -XX:MaxNewSize=384m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true'
Windows: create a file called setenv.bat and add the following line:
set JAVA_OPTS=-server -Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=512m -XX:NewSize=192m -XX:MaxNewSize=384m -Djava.awt.headless=true -Dhttp.agent=Sakai -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true'
5.4 Set up Tomcat as a Windows service
You can convert the .zip install into a service install by running service.bat
from the /bin
directory:
C:\tomcat\bin> service.bat install
You can add a service name as a second argument to the above script (the default name is "Tomcat5"). You can uninstall the service by replacing "install" with "remove".
After this you need to set the default startup options:
C:\tomcat\bin> tomcat5 //US//Tomcat5 ++JvmOptions "-Xms512m;-Xmx1024m;-XX:PermSize=128m;-XX:MaxPermSize=256m;-Dfile.encoding=UTF-8; -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false"
If you choose to do this in the GUI follow these steps: Open the configuration window, issue the following command:
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).
Windows users that have installed Tomcat as a service can set most Java options through the Tomcat service manager GUI, but not all of them are as straightforward as inclusion in a single environment variable. To achieve the equivalent of the "-server" option, you'll need to change the Java Virtual Machine path from ..\bin\client\jvm.dll
to ..\bin\server\jvm.dll
.
Java 1.6 users will you need add the system property -Dsun.lang.ClassLoader.allowArraySyntax=true
. This option is not required for Java 1.5. Please see the Java section above or SAK-15874 for more details.
Be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI, e.g.:
-Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=256m -Dfile.encoding=UTF-8 -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dsun.lang.ClassLoader.allowArraySyntax=true -Dhttp.agent=Sakai
Samoo has reported that display issues after editing text documents with accented characters using the resources tool. The issue was resolved by adding -Dfile.encoding=UTF-8 as a Java option (open command window -> type "tomcat5w" -> "Java" ->"Java Options:").
You can add additional system properties if needed, e.g., -Dsakai.security=C:\tomcat\security
.
Finally, clear out the Initial Memory Pool and Maximum Memory Pool values, as those might conflict with the options you're putting in the Java Options field. Then click Apply, restart the service, and double-check the service manager to verify that the values have changed.
Java 1.6 users may encounter the unhelpful system log error "The Apache Tomcat service terminated with service-specific error 0 (0x0)". This can be fixed by copying the file msvcr71.dll
from the /bin
directory into the server or client directory with the jvm.dll
file.
To set up remote debugging, please see (Remote Debugging).