Install Guide - Source Install (2.6)

Environment Setup

Java

Java Verification, Installation and Environment Variables

Sun Microsystem's Java 2 Platform Standard Edition 5.0 (J2SE 5.0), a.k.a Java 1.5, is required to build and run Sakai. Certain files, such as *.jsp and *.jws, require compilation so downloading and attempting to use only the runtime environment (JRE 5.0) will not suffice.

Sakai 2.6 is not compatible with Java Platform, Standard Edition 6 (Java SE 6), otherwise known as Java 1.6. Compilation errors have been reported by members of the Community experimenting with Sakai and Java SE 6. Use Java 2 Platform Standard Edition 5.0 (J2SE 5.0) instead.

Sun Microsystems has reported security vulnerabilities in JDK/JRE 5.0 updates 1.5.0_17 and earlier. Sun recommends that you install JDK/JRE 5.0 Update 18.

If you find Sun's version and naming conventions confusing, see Sun Java SE Naming and Versions for an outline of their practices.

Mac OS X includes the full version of Java J2SE 5.0, pre-installed with the Java Development Kit (JDK) and the HotSpot virtual machine (VM), so Mac users should not need to install Java.

To confirm that Java is both installed on your system and is the correct version for Sakai, run java -version from the command line:

$ java -version

If Java is installed, the version command will output basic version and build information. Note that Java's "internal" version number will be displayed:

java version "1.5.0_18"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_18)
Java HotSpot(TM) Client VM (build 1.5.0_18, mixed mode, sharing)

If Java is not installed or if you are running the wrong version you can download the latest J2SE 5.0 JDK release from Sun's archive:

Release: http://java.sun.com/javase/downloads/index_jdk5.jsp
Installation Notes: http://java.sun.com/j2se/1.5.0/install.html

Install the SDK, typically in the /opt directory, i.e. /opt/java.

Install the JRE to a different directory (usually the default directory, especially if running Windows) or you may experience runtime issues.

JAVA environment variables

Java requires two environment variables be set for optimal operation. 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 (samples below).

JAVA_HOME

Set the JAVA_HOME environment variable to point to the base directory of your Java installation.

Linux/Unix/: export JAVA_HOME=/usr/java/java-current
Mac: export JAVA_HOME=/Library/Java/Home
Windows: JAVA_HOME=C:\j2sdk1.5.0_xx ("xx" = the maintenance/revision number, e.g. "j2sdk1.5.0_13")

If your machine has already set the variable JRE_HOME 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.

PATH

Next, add Java's /bin directory to the PATH environment variable:

Linux/Unix/Mac: export PATH=$PATH:$JAVA_HOME/bin/
Windows: append the string ;C:\jdk1.5.0_xx\bin to the end of the system variable named Path ("xx" = the maintenance/revision number, e.g. "j2sdk1.5.0_13")

You should check that you have set your environment variables correctly. For both Windows XP and Unix/Linux/Mac operating systems start a new shell and run the set command to see your environment variables.

$ set

[excerpt]
 
JAVA_HOME=/Library/Java/Home
JAVA_OPTS='-server -Xms512m -Xmx1024m -XX:PermSize=128m -XX:MaxPermSize=196m -XX:NewSize=192m -XX:MaxNewSize=384m'
...
PATH=/Library/Java/Home/bin [etc]
....

JVM Tuning

The default Java virtual machine is not adequate to run an application of Sakai's size, and several JVM parameters must be increased to a certain threshold for Sakai to run, while some may be further adjusted for optimal performance on your machines.

JVM tuning is, as a general rule, something of a black art, and we recommend that you take the time to experiment with different memory and garbage collection settings and see what works best in your environment. We can make some minimal recommendations that should serve as a foundation for further experimentation and testing, but the following details are however offered only as samples or suggestions, and we recommend that you consult a systems administrator or local Java guru before making any such changes to a production system.

The standard way to control the JVM options when Tomcat starts up is to have an environment variable JAVA_OPTS defined with JVM startup options. Since any given Sakai instance may be deployed for a variety of purposes - ranging from developers doing private testing to large-scale deployments - it's hard to recommend a single set of such options as the preferred ones for every case. We can, however, start with a bare minimum which will at least avoid "Out of Memory" errors, and be suitable for developer installs of the software:

JAVA_OPTS="-server -Xms768m -Xmx768m -XX:PermSize=128m -XX:MaxPermSize=256m -XX:NewSize=192m -XX:MaxNewSize=384m"

This is an adequate - if minimal - starting point: it selects server mode, sets an adequate heap size, and sizes the permanent generation to accommodate more longer-persisting objects. These settings will allow things to be functional for testing and development, but for pilot or production deployments you'll want to give closer attention to the appropriate values for your server. See the [Sys Admin Guide] for more detailed tips.

Once you set JAVA_OPTS Tomcat will see this environment variable upon startup and use it. Instead of putting this in an environment variable you might create your own startup script to do so.

If you choose to run Tomcat as a service, review the [Tomcat Installation and Configuration] section for additional tuning recommendations.

HTTP Proxy

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:

export JAVA_OPTS="-Dhttp.proxyHost=cache.some.domain -Dhttp.proxyPort=8080"

Tomcat

Apache Tomcat Servlet Container

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.6.0 was tested using Apache Tomcat 5.5.26. You can learn more about Tomcat by visiting http://tomcat.apache.org/.

Download and Install Tomcat

Getting Tomcat

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 later 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 while Windows users should simply rename the base Tomcat directory to /tomcat to simplify the path.

ln -s apache-tomcat-5.5.26 tomcat

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.26\

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.

Sakai - Tomcat Gotchas

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.

Tomcat 6.0+. Sakai 2.6 out-of-the box (OOTB) will not run inside Tomcat 6.0+.

Tomcat 5.5.27. This version of Tomcat enforces strict quote escaping which impacts negatively Sakai tools that use the JavaServer Faces UI framework. See https://issues.apache.org/bugzilla/show_bug.cgi?id=45015 for more details. If you deploy Sakai using Tomcat 5.5.27 add the following parameter to your JAVA_OPTS environment settings:

-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false 

Do not download and install the JDK 1.4 Compatibility Package. Sakai 2.6 will not run should you install it.

Tomcat Environment Variables

By convention, the base Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.26) is referred to as $CATALINA_HOME. As a convenience, you should set $CATALINA_HOME as an 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.

CATALINA_HOME

Set the CATALINA_HOME environment variable to point to the base directory of your Tomcat installation.

Unix/Mac: export CATALINA_HOME=/opt/tomcat
Windows: CATALINA_HOME=C:\tomcat

PATH

Add the Tomcat /bin directory to your PATH variable:

Unix/Mac: export PATH=$PATH:$CATALINA_HOME/bin
Windows: append the string ;C:\tomcat\bin to the end of the system variable named Path

Tomcat Configuration

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 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>

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 HTTP server you can configure redirections from within Apache, an option that lies outside the scope of this document.

Tomcat Memory Settings

You can better manage Tomcat memory usage by creating a SETENV 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 -XX:+UseParallelGC -Xmx768m -XX:MaxPermSize=160m -Djava.awt.headless=true"

Windows: create a file called setenv.bat and add the following line:

set JAVA_OPTS=-server -XX:+UseParallelGC -Xmx768m -XX:MaxPermSize=160m -Djava.awt.headless=true

Tomcat as a Windows Service

You can convert the .zip install into a service install 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 the above script (the default name is "Tomcat5"). You can uninstall the service by replacing "install" with "remove".

To 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, for example, you'll need to change the Java Virtual Machine path from ..\bin\client\jvm.dll to ..\bin\server\jvm.dll. Then be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI. e.g.:

-Xmx768m
-Xms768m
-XX:PermSize=128m
-XX:MaxPermSize=256m

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.

Websphere

Websphere Application Server Container

As an alternative to Tomcat, Sakai also supports the IBM Websphere Application Server. Websphere 6.1 is a J2EE 1.4 compliant application server. It supports Java Standard Edition 1.5 and provides an enterprise-level platform for hosting the Sakai CLE in a secure, scalable, and highly available application server environment. To install Websphere, follow these detailed instructions.

Maven

Maven Installation

Sakai uses Apache's Maven build tool to compile and deploy its project modules. There are three steps in the process: clean, install and deploy. These steps, otherwise known as Maven goals, perform the following actions:

clean flushes the target for each Sakai project module prior to building
install installs the output of each Sakai project module into the repository
sakai:deploy deploys Sakai project modules from the repository to the target $CATALINA_HOME/webapps folder.

For more information on Maven visit http://maven.apache.org/.

Download and Install Maven

If you have not installed Maven, download the latest Maven 2.0 build from http://maven.apache.org/download.html and extract the distribution archive into your installation directory of choice, e.g. /opt/maven-2.0.8.

Maven Environment Variables

Maven requires that a number of environment variables be set for optimal operation. 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.

MAVEN_HOME

Set the MAVEN_HOME environment variable to point to the base directory of your Maven installation.

Unix/Mac: export MAVEN_HOME=/opt/maven-2.0.xx
Windows: MAVEN_HOME=C:\maven-2.0.xx ("xx" = the maintenance/revision number, e.g. "maven-2.0.8")

PATH

Add the Maven /bin directory to your PATH variable:

Unix/Mac: export PATH=$PATH:$MAVEN_HOME/bin
Windows: append the string ;C:\maven-2.0.xx\bin to the end of the system variable named Path ("xx" = the maintenance/revision number, e.g. "maven-2.0.8")

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='-Xms256m -Xmx512m -XX:PermSize=64m -XX:MaxPermSize=128m'

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).

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). If you are using Websphere, then create and/or specify a directory that Websphere will have read/write access to.

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

<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>

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>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 the following to their file:

...
<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>
</settings>

If you do not use a username or password for your proxy exclude <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.

Verify Maven

Finally, confirm that you can start Maven, run the command mvn --version. 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.

mvn --version

Sakai Installation

Sakai Source Distribution

The Sakai Foundation and Community issues new versions of the Sakai Collaboration and Learning Environment (CLE) software on a regular basis. To obtain the latest Sakai demo, binary or source distribution visit the Sakai release site:

http://source.sakaiproject.org/release/

The Sakai Community manages its source code utilizing the open-source Subversion (SVN) version control system. Sakai source code is also available from our SVN repository located at

https://source.sakaiproject.org/svn/

The latest development work is located in /sakai/trunk; stable releases can be retrieved from the {/sakai/tags}} folder organized by release version. Maintenance branches may be created in the /sakai/branches folder for additional work on current or previous tagged releases.

Trunk: https://source.sakaiproject.org/svn/sakai/trunk/

Tags: https://source.sakaiproject.org/svn/sakai/tags

Branches: https://source.sakaiproject.org/svn/sakai/branches/

In addition, Sakai's SVN repository includes a number of projects that are not included in official Sakai releases that can be checked out and installed in the Sakai CLE. Code for these projects (known within the Sakai Community as contributed or "contrib" projects) is located at the following address:

Contrib: https://source.sakaiproject.org/contrib/

Once you have installed an SVN client you can check out Sakai source code (in the case below, trunk) by issuing the following command from a terminal window:

svn co https://source.sakaiproject.org/svn/sakai/trunk/ trunk

2-6-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; see the Sakai Confluence Wiki 2-6-x branch summary for more information.

You can download the branch by issuing the following SVN command from a terminal window:

svn co https://source.sakaiproject.org/svn/sakai/branches/sakai_2-6-x/ sakai_2-6-x

Post-Release 2.6 Branches

At various times, Sakai project teams make available for the current release new functionality destined for a future release. For more information on these interim releases visit our Release Management space in our Confluence Wiki. For 2.6 post-release work see http://confluence.sakaiproject.org/confluence/display/REL/Post-2.6+Feature+Branches.

Sakai Configuration

The sakai.properties file is a central configuration file that is typically stored in a /sakai subdirectory relative to the Tomcat home directory ($CATALINA_HOME). It is a non-XML text file containing a series of key/value pairs that is read using the load method of java.util.properties. Settings in sakai.properties govern everything from setting your institution's name to configuring your database. All settings in sakai.properties are read on startup; any changes you make subsequently will only take effect when you restart web application server.

The default default.sakai.properties file is located in the config module:

sakai-src/config/configuration/bundles/src/bundle/org/sakaiproject/config/bundle/default.sakai.properties

A sample sample.sakai.properties file that documents many of the standard properties can also be found in config:

sakai-src/config/configuration/bundles/src/bundle/org/sakaiproject/config/bundle/sample.sakai.properties

If you need to override the default settings you must create your own sakai.properties file either from scratch or from a known working copy adding new key/value settings in order to customize your installation. Since any component property can in principle be overridden by a sakai.properties setting, sample sakai.properties files will show only a small fraction of all the possible settings.

The default location for your local sakai.properties file is $CATALINA_HOME/sakai. This folder is not created by Maven during the build and deployment process, so you will have to create it manually or via a script. You can also store Sakai's configuration files outside of your web application server's file hierarchy. For example, in a development environment you may find yourself frequently reinstalling Tomcat and unless you create a build script to automate the Tomcat installation and configuration process avoiding having to recreate $CATALINA_HOME/sakai and sakai.properties each time has its advantages.

To locate your properties file outside of your web application server environment modify the Java startup command or the JAVA_OPTS environment variable and set a system property named sakai.home. Make sure your external location is readable and writable by your web application server.

-Dsakai.home=/path/to/desired/sakai/home/

For detailed documentation on the full variety of possible sakai.properties settings, see the sakai_properties.doc in sakai-src/reference/docs/architecture/sakai_properties.doc.

Sakai Email Configuration

Enabling Sakai to both send and receive email requires setting a number of properties in sakai.properties. For sending mail Sakai requires the address (name or IP) of an external SMTP server that will accept mail from Sakai:

smtp@org.sakaiproject.email.api.EmailService=some.smtp.org

To enable Sakai to receive mail you'll need to set the following properties:

# dns addresses used for incoming email
smtp.dns.1 = 255.255.255.1
smtp.dns.2 = 255.255.255.2

# SMTP port on which our SMTP server runs. Default is 25.
#Recommend running on 8025, and using a standard mailer on 25 to forward mail to Sakai.
smtp.port = 25

# flag to enable or disable our SMTP server for incoming email (true | false)
smtp.enabled = true

# email address used as the "from" address for any email sent by Worksite Setup tool or Site Info tool.  
# Recipients may not receive notifications if this address isn't valid.
#setup.request=address@somedomain

To disable the SMTP server for incoming email, set smtp.enabled=false in sakai.properties:

smtp.enabled=false

Sakai's SMTP server is Apache James. Utilizing the above configuration to run James on the standard SMTP port 25 requires admin privileges. Most admins won't permit Tomcat to run with the above permissions and would rather run a standard mailer like Postfix on port 25 and configure it to forward requests to Sakai. You may also already have a mailer service running on port 25 (Linux usually has it running by default) and so you will want to change the James port port in order to avoid a conflict. For example:

smtp.port=8025

Sakai Build and Deploy

Maven Master POM

Sakai makes use of Maven's Project Object Model to provide an XML representation of basic project information covering dependency management, build targets, external repositories, issue tracking, mailing lists, reporting plugins, developer bios, etc. A top-level master pom.xml file located in the /master project acts as a parent for other pom.xml files included in other Sakai project modules. If you are building Sakai for the first time you should build the master POM first before attempting to build and deploy Sakai as whole. Issue the Maven clean and install goals from the /master project folder to build and install the master POM:

cd master
mvn clean install
cd ..

Maven Build and Deploy

Once you have built the master POM, issue the following Maven goals from the sakai-src directory or from the folder containing the Sakai modules downloaded from our SVN code repository:

mvn clean install sakai:deploy -Dmaven.tomcat.home=/pathto/tomcathome

-Dmaven.tomcat.home specifies Tomcat's location and can be omitted if Tomcat home is specified in Maven's settings.xml file.
If using Websphere instead of Tomcat, you must also add the -Pwas parameter option to the above command. This configures the build process to generate an enterprise archive (EAR) file for Websphere. See Building the Sakai Source for Websphere for more information.

When performing your first build of Sakai, Maven will run for quite a few minutes issuing fairly verbose output. Maven will download any missing dependencies into your local repository, then attempt to compile the Sakai code and, if successful, will then deploy Sakai to Tomcat in the form of *.war files in the $CATALINA_HOME/webapps directory. If during this process Maven reports that the build failed read the accompanying error message carefully to troubleshoot the issue (see the [Troubleshooting] section).

You can also issue mvn clean install sakai:deploy from any sakai project module top-level folder in order to build and deploy portions of Sakai such as individual tools.

Maven Goal Options

There are a number of other ways to build and deploy Sakai using Maven:

Build and Deploy Sakai in Offline Mode

If your local repository contains all Sakai project dependencies, you can run Maven "offline" by adding the -o option:

mvn -o clean install sakai:deploy

Build and Deploy the Sakai "Framework"

You can build and deploy the Sakai framework by adding the -Pframework option:

mvn -Pframework clean install sakai:deploy

Build and Deploy Sakai "Mini"

You can build and deploy a minimal set of Sakai tools by adding the -Pmini option:

mvn -Pmini clean install sakai:deploy

Skip Unit Tests when Building and Deploying Sakai

There may be occasions when you want to build and deploy Sakai without executing the set of unit tests that accompany many of the Sakai modules. If so add -Dmaven.test.skip=true to the goals you issue:

mvn -Dmaven.test.skip=true clean install sakai:deploy

Starting/Stopping Sakai in Tomcat

At this stage your installation of Sakai has not yet been configured to use your preferred database (it will use its own HSQLDB by default) but you should now be able to bring it up as a working web application by simply starting Tomcat, and it can be helpful at this point to know if any problems exist before you try to connect it to another database. Tomcat will take a minute or so to start up, depending on the speed of your machine, and it's a good idea to watch the Tomcat log as it comes up to catch any errors (see [Troubleshooting]).

You can start Tomcat by running the appropriate start batch/shell script file from the root Tomcat directory:

Windows: start-sakai.bat
Unix/Mac: start-sakai.sh

Once Tomcat has loaded the Sakai application (again, this can take a minute or so) point your browser to

http://localhost:8080/portal

This will bring you to the Sakai gateway site from which you can create new accounts and log in to the system. If the gateway page fails to load, check the Tomcat logs (see the [Troubleshooting] section) for any errors and stack traces. If the gateway page does come up, log in with the default admin account (the username and password are both 'admin'). If you can log in without errors Sakai is alive and well.

Stopping Sakai involves shutting down Tomcat by running the appropriate stop batch/shell script file from the root Tomcat directory:

Windows: stop-sakai.bat
Linux/Unix/Mac: stop-sakai.sh

Sakai Logging

Once you have Sakai installed, configured and started, you can monitor Sakai by watching the logs. The log level for the standard Sakai source code and the demo is set to show info and warnings only. Watch for the WARN: messages. There are going to be some "normal" ones at startup, and some will likely slip by at runtime, but any warning is potentially something you might want to check out.

Logging levels can be specified in sakai.properties. This augments and overrides the levels set in the default config file. Example:

log.config.count=3
log.config.1 = ALL.org.sakaiproject.log.impl
log.config.2 = OFF.org.sakaiproject
log.config.3 = DEBUG.org.sakaiproject.db.impl

This uses the established (if awkward) method of having a name.count followed by name.1, name.2 etc. to form an array of strings for the value "name". In this case, the name is "log.config". The values are of the form LEVEL.logger, and the possible levels are: OFF TRACE DEBUG INFO WARN ERROR FATAL ALL.

Changing the Log Configuration

Sakai uses log4j for logging. See the official log4j documentation for more information about how to configure it if you have questions, but a few notes are collected here below.

To change the logging for Sakai in the source you can use sakai-src/kernel/log-configure/src/conf/log4j.properties, and the relevant property is:

log4j.logger.org.sakaiproject=INFO

To turn on debug logging for all of Sakai, change that value from INFO to DEBUG. In order to turn on debug logging for just a single component of Sakai, add a line such as in the following example, which will leave most of Sakai at INFO, but generate DEBUG level messages for the SQL service:

log4j.logger.org.sakaiproject=INFO
log4j.logger.org.sakaiproject.component.framework.sql.BasicSqlService=DEBUG

The logging controls are part of the LogConfigurationManager, implemented as a component in the util module. It can be disabled, if that's desired, with an entry in sakai.properties:

enabled@org.sakaiproject.log.api.LogConfigurationManager = false

For Mac and *nix systems, the most important log is found in Tomcat's logs/catalina.out. It can be instructive to watch this log as Tomcat is starting up, by using a startup command like the following:

bin/startup.sh; tail -f logs/catalina.out

Tomcat on Windows tends to be a little more puzzling about its logs, and it includes more of them, but its default behavior is to open catalina.out in a new window as soon as you start Tomcat. If you need more information about the logs in Windows, we'll refer you to the official Tomcat documentation.

The SMTP server logs from Sakai will be written to the $CATALINA_HOME/sakai/logs directory.

Database Installation

Supported Databases

Sakai has been tested against and supports the following production-grade databases:

Sakai requires transaction support. In the case of MySQL you must implement the InnoDB storage engine to ensure proper transaction handling.

UTF-8 Character Set

Irrespective of whether you utilize MySQL or Oracle be sure you have configured your database to use the UTF-8 character set. Failure to do so will result in range of issues when attempting to use Unicode characters in Sakai. Consult your Db documentation or a local DBA for instructions on how to set your database up properly.

If you are uncertain as to how your database is currently configured, you can check with a query. Here is a sample query for checking an Oracle instance:

SQL> select value from nls_database_parameters where parameter = 'NLS_CHARACTERSET';

VALUE
--------------------------------------------------------------------------------
AL32UTF8

For Mysql, the command to see what encoding your database is currently set to is "show create database sakai", assuming, of course, that your database is named "sakai". e.g.:

mysql> show create database sakai;
+----------+----------------------------------------------------------------+
| Database | Create Database |
+----------+----------------------------------------------------------------+
| sakai | CREATE DATABASE `sakai` /*!40100 DEFAULT CHARACTER SET utf8 */ |
+----------+----------------------------------------------------------------+
1 row in set (0.00 sec)

Converting a database from one character set to another is a non-trivial operation, particularly if it is a large production database. We recommend strongly that you verify this aspect of the database creation and configuration process before deploying Sakai.

Database Drivers

Choose the appropriate MySQL or Oracle JDBC driver (or connector) for your installation.

MySQL Connector/J Driver

For MySQL, download the *zip/*tar.gz archive, extract its contents and copy the mysql-connector-java-<version>-bin.jar to $CATALINA_HOME/common/lib.

For MySQL 4.1 users problems have been reported for both the MySQL Connector/J 3.1.10 and 3.1.11 drivers. Choose version 3.1.12 or higher.

Oracle OJDBC Driver

For Oracle download the ojdbc14.jar file and copy it to $CATALINA_HOME/common/lib.

Both Oracle 10g AND Oracle 9i users must use the 10g driver; the latest 10g "Release 2" (10.2.x) or higher is recommended.

Database Connection Settings

The sakai.properties configuration file defines database technology and connection information. Appropriate sample settings for HSQLDB, Oracle and MySQL are listed below.

By default, all Sakai distributions are configured to use an in-memory version of HSQLDB. HSQLDB is provided for testing/demo purposes only and should not be run in production.

Whatever database you choose to use, you will need to modify at a minimum the following connection settings:

url@javax.sql.BaseDataSource
username@javax.sql.BaseDataSource
password@javax.sql.BaseDataSource

Set the Database Username and Password

Start by setting your database username and password:

# DATABASE CONFIGURATION - make sure to modify details to match your particular setup

# The username and password. The defaults are for the out-of-the-box HSQLDB. Change to match your setup.
username@javax.sql.BaseDataSource=yourDbUserName
password@javax.sql.BaseDataSource=yourDbPassword

Configure Database Settings

HSQLDB Sample Configuration

HSQLDB is Sakai's default database. Remember to comment out its settings should you choose to run Sakai utilizing either MySQL or Oracle.

## HSQLDB settings - on by default
vendor@org.sakaiproject.db.api.SqlService=hsqldb
driverClassName@javax.sql.BaseDataSource=org.hsqldb.jdbcDriver
hibernate.dialect=org.hibernate.dialect.HSQLDialect
validationQuery@javax.sql.BaseDataSource=select 1 from INFORMATION_SCHEMA.SYSTEM_USERS
# two hsqldb storage options: first for in-memory (no persistence between runs), second for disk based
#url@javax.sql.BaseDataSource=jdbc:hsqldb:mem:sakai
url@javax.sql.BaseDataSource=jdbc:hsqldb:file:${sakai.home}db/sakai.db

MySQL Sample Configuration

Locate the MySQL configuration block, uncomment the settings and save your changes. Make sure you modify the data source, username and password settings to match your local environment. Do not forget to comment out the HSQLDB and Oracle settings.

# MySQL settings - make sure to alter as appropriate
vendor@org.sakaiproject.db.api.SqlService=mysql
driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQLInnoDBDialect
url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakai?useUnicode=true&characterEncoding=UTF-8
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

# To get accurate mysql query throughput statistics (for example for graphing) from the mysql command
# show status like 'Com_select'
# this alternate validation query should be used so as not to increment the query counter unnecessarily
# when validating the connection:
#validationQuery@javax.sql.BaseDataSource=show variables like 'version'

Oracle Sample Configuration

Locate the Oracle configuration block, uncomment the settings and save your changes. Make sure you modify the data source, username and password settings to match your local environment. Do not forget to comment out the HSQLDB and MySQL settings.

## Oracle settings - make sure to alter as appropriate
vendor@org.sakaiproject.db.api.SqlService=oracle
driverClassName@javax.sql.BaseDataSource=oracle.jdbc.driver.OracleDriver
hibernate.dialect=org.hibernate.dialect.Oracle9Dialect
url@javax.sql.BaseDataSource=jdbc:oracle:thin:@your.oracle.dns:1521:SID
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

Oracle users may experience performance issues with certain of the SQL settings that work for HSQL and MySQL. Oracle users can reduce Db load by uncommenting the following settings:

# For improved Oracle performance (from the University of Michigan)
validationQuery@javax.sql.BaseDataSource=
defaultTransactionIsolationString@javax.sql.BaseDataSource=
testOnBorrow@javax.sql.BaseDataSource=false

The auto.ddl Setting

On startup, Sakai will generate all database objects (tables, keys, constraints, etc.) automatically, obviating the need to run DDL scripts manually.

# establish auto.ddl - on by default
auto.ddl=true
#auto.ddl=false

Once the database schema is created you should set auto.ddl=false.

Database Migration

Overview

A database conversion is typically required between Sakai versions. Database conversion scripts - in distinct versions for MySQL and Oracle, respectively - are found in the reference/docs/conversion folder of the release or in our SVN repository:

In the same directory you'll also find conversion scripts for earlier Sakai versions. Migration from an earlier version will require the successive application of all intermediate scripts (see the following table). You cannot, for example, move from 2.2.1 to 2.4.0 by applying a single script. The were no database schema changes between 2.4.0 and 2.4.1, so you can migrate to the 2.5.0 schema from either version using the 2.4.0 scripts.

Upgrade Step	Conversion script prefix
1.5 to 2.0	sakai_1_5-2_0
2.0 to 2.1	sakai_2_0-2_1
2.1 to 2.1.1	sakai_2_1-2_1_1
2.1.1 to 2.1.2	sakai_2_1_1-2_1_2
2.1.2 to 2.2.0	sakai_2_1_2-2_2_0
2.2.0 to 2.2.1	sakai_2_2_0-2_2_1
2.2.1 to 2.3.2	sakai_2_2_1-2_3_1
2.3.0 to 2.3.2	sakai_2_3_0-2_3_1
2.3.1 to 2.3.2	no schema changes
2.3.2 to 2.4.1	sakai_2_3_1-2_4_0
2.4.0 to 2.4.1	no schema changes
2.4.1 to 2.5.0	sakai_2_4_0-2_5_0
2.5.0 to 2.5.1	sakai_2_5_0-2_5_1
2.5.0 to 2.5.2	sakai_2_5_0-2_5_2
2.5.1 to 2.5.2	no schema changes

The latter version represents a security release that replaced one or more intervening Sakai releases. In this case the provided conversion script contains the necessary information to migrate you through the no longer available, intervening Sakai versions.

As a general rule, be sure to read through the conversion scripts before applying them. The conversion scripts are generic in the sense that they do not take into account any special customizations you may have made - such as new roles, or the deployment of additional tools or if you are migrating from 2.4.x - and they may complicate your migration with unintended consequences if you execute them blindly.

There were no schema changes between Sakai 2.5.1 and 2.5.2. The Sakai 2.5.1 and 2.5.2 releases are both based on 2.5.0; Sakai 2.5.1 containing a major portfolio tool bug that was reverted in Sakai 2.5.2.

Other Conversion

2.5 also includes data and schema conversion outside the standard scripts for Assignments and Content Hosting to address data integrity for assignments and performance enhancements in both tools. Below is a quick summary and overview of the process for each tool.

Assignments

The assignment service has permitted the creation of duplicate submission objects (i.e. 2 or more submissions for the same student and assignment). While the UI should prevent this from happening, at various stages in the evolution of the Assignments code, bugs, race conditions or other failures have led to duplicate objects being created. This conversion seeks to reconcile those duplicates and add database constraints to prevent this is the future.

In summary, the conversion script is necessary to

1. Remove existing duplicate submission records, if any
2. Prevent future submission duplicates by applying unique constraint on the ASSIGNMENT_SUBMISSION table
3. Improve performance of the Assignment tool

The conversion script does the following to the existing ASSIGNMENT_SUBMISSION table in Sakai database:

1. read in all tuples as AssignmentSubmission object, parse out data such as submitter_id, submit_time, submitted, and graded, and stores those attributes as separate columns in the ASSIGNMENT_SUBMISSION table;
2. Runs though the table, combine and remove submission duplicates (tuples with same "context" and "submitter_id" combination);
3. apply the unique constraint of "context" + "submitter_id" to ASSIGNMENT_SUBMISSION table.

There is a readme file with detailed instructions on this process at https://source.sakaiproject.org/svn/assignment/tags/sakai_2-5-0. In addition, there is further information in the related JIRA SAK-11821.

This conversion was a part of the post-2.4 assignments branch so those migrating from a version already running this can disregard this step.

Content Hosting

Moving from 2.4 to 2.5 requires adding several columns to the database tables used by the Content Hosting Service (the service used by the Resources tool, Dropbox, filepicker and WebDAV). The conversion scripts contain DDL statements to accomplish those changes. You need to run these conversions scripts (or perform the equivalent operations manually) and then convert your existing Resources via one of the methods outlined below, before you will gain the performance improvements Sakai 2.5 offers.

The new columns added to the database tables support a switch from XML serialization to "binary-entity" serialization, and enable Resources to perform faster and use less memory. One of the key areas this impacts is improving the performance of quota calculations.

There are two methods for converting existing Resources, with the first being the recommended option, as it enables all performance improvements when completed:

1. Run the conversion utility, which can be run on a live system. (See readme for more details.)
   • Systems running oracle should read the email threads copied to the comments section below.
2. Let the code convert each Resource as it is accessed.
   • This is only recommended for implementations with small datasets, such as pilot deployments; otherwise you should use the above conversion utility.
   • While some performance benefits from the binary-entity serialization can be realized immediately using this method, others, such as the quota calculation improvements will not be available until all Resources have been accessed and converted.

Based on the state of the data in the Content Hosting Service tables, it will start up in one of two modes:

1. Binary only - If the code detects on start-up that all of the XML fields are null – as would be the case after running the conversion utility – it will run in binary mode. The means the system will only read and write using binary-entity serialization, and you will be able to fully realize all the performance enhancements that it offers.
2. Dual mode - If the code detects there is still data in the XML fields – as would be the case if the conversion utility has not be run – it will run in dual mode. This means the system will be capable of reading both XML-serialized and binary-entity-serialized resources, but will write using only binary, and will convert any XML data it encounters into binary data. This gives you some of the performance benefits of binary-entity serialization without running the conversion utility, but you will never get the quota-calculation improvements unless all Resources end up converted.

Need Further Help? For further information, please contact: Ian Boston for MySQL backends Jim Eng for Oracle backends

Discussion

The Discussion tool was retired and removed for Sakai 2.5. (Upgrade/Migration options...)

Troubleshooting Issues

Troubleshooting Issues

Getting Help

Below are a number of common issues encountered while building and starting up Sakai but you may also benefit from the expert advice and assistance available within the Sakai developer community. The quickest way to get your questions answered is to join the Sakai Development Work Group (otherwise known as sakai-dev) and send an email to the list.

To join the sakai-dev list go to http://collab.sakaiproject.org, create a new account, log in to Collab, select the My Workspace tab, and then use the Membership tool to join the group named DG: Development. You can then begin to send emails to (and receive them from) sakai-dev@collab.sakaiproject.org. To later unsubscribe, you can simply use the same Membership tool to unjoin the site.

Build Issues

JAR download failures

A first build of Maven on a fresh installation may warn of numerous jar download failures if you include the clean phase. This is a nuisance, but not otherwise a problem. Even when doing a clean maven tries to download all dependencies, including those Sakai jars that may not be built until the later build phase. Once they are built and placed into the repository, maven is perfectly happy for the next "clean build" cycle. The upshot is that you may see these errors for your first build, but you shouldn't see them for subsequent builds. It also means that you're better off not including the clean phase during your first build of a new version of the code.

If this does not account for the download failures you're seeing, then you may want to double-check your maven.remote.repo setting. See the Maven Configuration section, and follow it precisely.

Out of Memory errors

You may find that your machine runs out of memory while it is building Sakai. As it turns out, maven does not read JAVA_OPTS when it starts up, and so if your build output complains of "Out of Memory" errors you'll need to set an additional environment variable, namely, MAVEN_OPTS. The value in the sample Unix command below should be more than enough:

export MAVEN_OPTS="-Xmx384m -XX:PermSize=48m"

Uninformative failure messages

If you need more detailed output to track down a build error, maven can be run in debug mode by adding the -x argument, e.g. mvn -x.