Sakai CLE 2.8 install guide (source)

1.0 Get the Sakai CLE source code

There are two ways to acquire Sakai source code. You can choose to download a packaged *.zip or *tar.gz file from Sakai's release page or check out the code directly from our code repository using Subversion's (SVN) source control management system.

Packaged releases are available at http://source.sakaiproject.org/release/.

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

Unable to render {include} The included page could not be found.

2.1 Set Java environment variables

Several environment variables and related properties must be set for Java. 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.

Set the JAVA_HOME environment variable to point to the base directory of your Java installation and add Java's /bin directory to the PATH environment variable.

 If the variable JRE_HOME is already set or if you want to use a particular JRE if 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 Apache Tomcat uses when it starts up, but it defaults to use JAVA_HOME if JRE_HOME is not set. In most cases, setting JAVA_HOME should cover both cases sufficiently.

 Windows: append the string to the end of the Path system variable

Set JAVA_OPTS

The default Java virtual machine (JVM) settings are insufficient for an application of Sakai's size. As a result several JVM parameters must be increased for Sakai to run, while others may need to be adjusted for optimal performance. At a minimum add the following property settings to your JAVA_OPTS environment variable.

 We recommend that you define these settings in Tomcat's /bin directory in a file named setenv.sh (Unix/Mac) or setenv.bat (Windows). See the Tomcat section below for more details.

Unix/Mac:

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:

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

 Additional required settings

Certain JSF tools (chat, portfolios, test & quizzes) do not compile properly in Java 1.6. The workaround requires adding the system property allowArraySyntax in order to avoid deserialization bottlenecks in arrays (see 

SAK-17578 - Compiling with Java 1.6 breaks tools in Sakai CLOSED ). Second, Tomcat 5.5.27+ enforces strict quote escaping, a change in *.jsp handling that has yet to be addressed in certain tools such as portfolios (see 

SAK-15736 - NPE when trying to preview portfolios when running in tomcat 5.5.27 and websphere CLOSED ). Finally, specify an HTTP user agent other than "Java/xxxxx" in order to resolve Google and other RSS feeds (see 

SAK-10159 - Unable to interpret RSS from Google News CLOSED , 

SAK-13353 - Unable to render news from Times Higher Education Supplement (THES) CLOSED and 

SAK-18044 - Add -Dhttp.agent=Sakai to demo startup scripts to resolve Google RSS feed issues CLOSED ).

-Dsun.lang.ClassLoader.allowArraySyntax=true -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false -Dhttp.agent=Sakai

Specify a Language and Locale (optional)

You can define the default language/locale when starting Sakai by setting the system properties -Duser.language and -Duser.region. For information on supported languages see the release notes or visit the i18N Work Group space.

-Duser.language=pt -Duser.region=PT

In the case your locale were not fully supported in Java (as it happens with Basque or Mongolian languages) you should read this information:
Endorsed I18n Project 

Specify an HTTP Proxy (optional)

In environments where local network policy or firewalls require use of an upstream HTTP proxy/cache, Sakai needs to be configured accordingly. Otherwise components or services which use HTTP requests, such as the BasicNewsService for RSS feeds in the News tool, cannot retrieve data from the target URLs. This can be fixed with the following JAVA_OPTS arguments:

-Dhttp.proxyHost=cache.some.domain -Dhttp.proxyPort=8080

3.0 Install Subversion 1.6+

The Sakai Community uses Apache Subversion (SVN) as its source control management (SCM) system. We recommend SVN version 1.6.5+. You can obtain binary packages for a variety of operating systems (Mac, Windows and several flavors of Unix). If you plan on checking out Sakai source from our SVN repository you will need to install a Subversion client. For a listing see:

http://subversion.apache.org/

If no binaries are available for your platform, get the source and use the configuration options --with-ssl and --with-libs.

Extract the distribution archive into your installation directory of choice, e.g. /opt/subversion/. Confirm that you have installed the correct version of SVN by issuing svn --version from the command line.

svn --version

svn, version 1.6.9 (r901367) compiled Jan 25 2010, 22:25:43 . . . .

3.1 Set Subversion environment variables

Set the SUBVERSION_HOME environment variable to point to the base directory of your SVN installation and Subversion's /bin directory to the PATH environment variable.

 Windows: append the string to the end of the Path system variable

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:

 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.

Optionally, you can specify the Tomcat home to be an environment variable:

Users who utilize a network proxy need to add a <proxies> section to settings.xml:

 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: