Sakai 1.5.0


Sakai Links

Tool Links

Run Sakai

Sakai CVS

Download Sakai
This zip file contains the root level project files for Sakai, and all the Sakai module folders. Unzip this into the folder you designate as your Sakai development folder (called $SAKAI_DEV in these instructions). Get the file here:
Setup Your Tools

Use a Java SDK version 1.4.2 or later:

Set the JAVA_HOME environment variable to point to the base directory of your Java installation. This will enable Tomcat, Maven, and Eclipse find the right Java installation automatically. This may already be setup for you by your Java SDK installation.

  • Windows example: JAVA_HOME="c:/dev/j2sdk1.4.2_04"
  • Mac example: JAVA_HOME=/Library/Java/Home

Use Maven 1.0 or later:

Maven installation is covered by their documentation in their Getting Started guide. Do "Download" and "Install", and read over the rest. After you install Maven, customize it by placing this file in your home directory. This file will identify an extra Maven repository for our use, and the location of your Tomcat installation for deployment.

maven.repo.remote =,
maven.tomcat.home = /usr/local/tomcat/

Edit the "maven.tomcat.home" value to show your tomcat root location; leave the first line as is. Please note, and include, the trailing slashes in these settings - the deploy will fail if they are missing

Windows Tomcat Home Setting
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", you need to identify it like this:
     maven.tomcat.home = c:/tomcat/
It is also possible to leave out the drive letter, if it is clear which drive this will be:
     maven.tomcat.home = /tomcat/
Your Home Directory

Maven's is stored in your home directory, however that's defined on your platform.

Most Unix machines have this as "~".

On later Windows machines, it's likely to be "c:\Documents and Settings\userid" (where "userid" is your Windows user id).

For older Windows (95, 98) machines, if your Windows system is configured for single-user mode, your home directory is probably the Windows system directory "c:/windows".


Use Tomcat version 5, 5.0.25 or later:

Sakai deploys a number of .war and .jar files into your Tomcat environment:

  • .war files go into your webapps folder. Tomcat will expand these at startup.
  • .jar files are deployed outside of the webapp framework to be shared by all the Sakai webapps. Most of these go into the Tomcat shared/lib folder. This is empty at Tomcat distribution; you can re-empty it when doing a clean deploy of Sakai.
  • some .jar files go in Tomcat's common/lib and server/lib folders. The hsqldb-*.jar file goes into common. Some Sakai dav jars go into common and server. If you are using a jdbc database, the driver .jar would likely go here as well. When clearing out an old Sakai installation, be careful not to delete all of tomcat's common/lib or server/lib (as is safe to do with shared/lib).

Depending on how you have your Tomcat configured, you will get log files in the Tomcat logs folder. Some logs will be written to the console window in which you launched Tomcat.

Special Tomcat Configuration

Sakai takes over the "root path" (i.e "/") of Tomcat. Tomcat ships with a webapp called "ROOT". You must remove or rename the "ROOT" webapp so that Sakai can have the root path.

The "sakai-dispatch" webapp acts a the root webapp. One of the context files you deployed using the "maven tomcat_context" step controls this. The webapp is deployed to /usr/local/sakai rather than tomcat's normal webapp area, so it doesn't get Tomcat confused.

The root path is used by Sakai for URL to the server. Dispatchers are installed there to forward requests where they need to go among the various Sakai webapps.

The root webapp is also used as the one webapp that has all the user sessions. These sessions are specially shared among the various Sakai webapps.


You can use Eclipse to develop Sakai. However, it is not necessary to download or use Eclipse in order to build or install Sakai. If you are doing development, any development environment can be used to edit the Sakai source code. Final Sakai builds and deploys are done with Maven commands, not from an IDE like Eclipse.

You can use Eclipse to develop Sakai:

Eclipse has a feature called Classpath Variables which lets you use variables in project files, share the project files, and have each user define these variables to point at the appropriate, and perhaps different, location on their development machines.

You can set these variables in Eclipse (2.11) under Windows / Preferences / Classpath Variables. In Eclipse 3.0 these variables can be accessed via project Properties / Java Build path / Libraries / Add Variables.

Sakai uses two variables on our Eclipse projects:

Variable Description Sample
MAVEN_REPO points at the local maven repository ~/.maven/repository
TOMCAT_HOME points at the root of the tomcat install
(used to get at xercesImpl.jar)

There are some other eclipse variables that are used for source for our support packages. These are used just when browsing code, not for compile. If you have downloaded the source for the support packages we are using, you can set these. Some of the Eclipse projects have these source locations registered, by these variables:

Variable Description Sample
SPRING_HOME the spring framework 1.0.1 source
(make sure there's a /src folder within)
JSF_HOME the JavaServer Faces 1.1 source
(note that downloading the JSF 1.1 source requires a special license agreement)
VELOCITY_HOME the Velocity 1.3.1 source
(make sure there's a /src folder within)
(make sure there's a /src folder within)
HIBERNATE_HOME the Hibernate software (version 2.1.6)
(make sure there's a /src folder within)

Each Sakai module can be made into an Eclipse project. The special Eclipse files .classpath and .project are checked in to the CVS and distributed in the source .zip file. Once you have the source on your machine and have the Eclipse classpath variables set up, you can add each Sakai module as a Java Project in Eclipse.

Name the module "sakai-" followed by the Sakai module name. For example, the "chef-tools" module in Sakai should be called "sakai-chef-tools" in Eclipse. When adding the project, make it a Java type, and point it at the appropriate Sakai module directory. Eclipse will find its files and should be happy.

Sakai can be developed and compiled in Eclipse, but do the final compilation and build / deploy using Maven. The Eclipse projects are setup to share the same binary directories as used by Maven.

Get Clean

If you need to upgrade from Sakai 1.0.0, please follow the specific instructions for upgrading from Sakai 1.0.0 to 1.5.0. If you have installed previous versions of Sakai or CHEF, you will need to clean up your Tomcat before starting with the 1.5.0 release. It is recommended that your install a fresh new Tomcat. Clean up by clearing out your tomcat webapps, logs, shared/lib, and work folders. Continue cleaning by removing your local maven repository's sakaiproject folder. Also remove any CHEF based webapps from your tomcat; CHEF and Sakai are not compatible in the same Tomcat.

Once you have either checked out the source, or downloaded and unzipped the source, you can from $SAKAI_DEV use the "clean_env" goal of maven:

maven clean_env

to delete the following files and folders:

Sakai Webapps rm -rf TOMCAT/webapps/sakai-*
Sakai .wars rm -rf TOMCAT/webapps/sakai-*.war
Tomcat Logs rm -rf TOMCAT/logs/*
Tomcat Shared Lib rm -rf TOMCAT/shared/lib/*
Tomcat Common Lib rm -rf TOMCAT/common/lib/hsqldb-*.jar
rm -rf TOMCAT/common/lib/sakai*.jar
Tomcat Server Lib rm -rf TOMCAT/server/lib/sakai*.jar
Tomcat Work rm -rf TOMCAT/work/*
Maven Repo. rm -rf ~/.maven/repository/sakaiproject

Warning: use "clean_env" carefully, as it will delete files and folders. Check that your tomcat webapps are "clean" after using this maven goal, as it may not remove all the old webapps.

Build Sakai

From the $SAKAI_DEV, issue this command:


This will run the default "clean_full" goal, download all dependent packages, build all Sakai source, install built source in your local Maven repository, and deploy the newly built Sakai to your Tomcat.

At least once, especially if you are working from CVS, issue these commands to fully setup your server for Sakai:

maven reg
maven conf_db
maven tomcat_context            (for Unix/OSX)
maven tomcat_context_windows    (for Windows)

This sets up the database configuration. If you are on windows, be sure to use "tomcat_context_windows" for the last command.

Other things you can do:

Sakai Maven Goals
clean and fully build all of the Sakai -modules and deploy to Tomcat
maven clean 
clean all prior build targets in the development folder
maven full 
re-build without cleaning and re-deploy
maven clean_env 
clear out the maven repository and tomcat from prior Sakai (see above)
maven conf_db
copy the database configuration files from source to /usr/local/sakai. Note: This configures Sakai with the default HSQLDB configuration. To use MySQL or Oracle, see the section "Using a database".
maven tomcat_context
copy the tomcat context XML files from source to the tomcat/conf/Catalina/localhost folder. Use this if you are using tomcat 5.0.27, as it does not properly distribute these files from the .war files.
maven tomcat_context_windows
the version of the tomcat_context goal that should be used if you are deploying on a Windows operating system.
maven reg
copy the registration files from source to /usr/local/sakai/reg. If you are working from CVS instead of the QuickStart, you need to do this before running.
maven javadoc
Create javadocs from the Sakai source. Creates a javadoc folder and a .zip file of the javadocs.
Configure Your Server

Sakai looks in files on the server to get configured. As shipped, Sakai finds these in:


The contents of this folder can be populated by copying the files and folders from the Sakai reference module's "usr_local_sakai" folder to your machine's /usr/local/sakai/ folder, something like this:

cp -r $SAKAI_DEV/reference/src/usr_local_sakai/* /usr/local/sakai/
(where $SAKAI_DEV is your Sakai development folder)

Make sure that the /usr/local/sakai folder has permissions to allow you (during development) and tomcat (at runtime) to read, create and write files.

Verify after the copy that you end up with the files and folders as listed below.

It is not necessary to edit the local server configuration files in order to run Sakai on your localhost only. However, to run a publicly accessible Sakai instance you will need to modify (at least) the file To change the selection of configuration of components, you will need to modify the components.xml files.

/usr/local/sakai files
Files File Names Notes
Custom Server Configuration (optional)

These files contain the top-level convenient Sakai configuration values. This is where to configure the server host name and port, DNS servers for mail handling, and many other server properties.

Settings in these files override settings that can be made in various places in the components.xml files. Setting them here allows you to use unmodified distribution components.xml files.

You can have one or both of these files, and distribute the settings between them.

Static Data Files
These you won't have to modify.
Starter Database Files db/

These files store and configure the default HSQLDB database. These files are not used if you configure an external MySQL or Oracle database. If you are running with the default HSQLDB database as a pilot or in production, you will want to regularly backup this directory. The maven goal conf_db copies these files from the source into /usr/local/sakai/db

Custom Service Components Configuration legacy-component/components.xml

These files control the choices and configurations of the service components used by Sakai. The default configuration selects and configures a set of components backed by tables on a SQL database.

The maven goal conf_db refreshes these files from the files in the source tree. Any changes you have made in /usr/local/sakai would be overwritten.

This is only one step in setting up for a database configuration. See the notes below.

Tool Registrations reg/(toolname).xml

These files register individual Sakai tools, and well as sets of tools for different types of Sakai sites.

Dispatcher Webapp


The Sakai dispatcher webapp is deployed here instead of in Tomcat's webapp area. This webapp is configured to act as the root path for Tomcat. The "ROOT" webapp of Tomcat must be deleted or renamed for this to work.

This will be created and updated whenever you run the maven command from the $SAKAI_DEV or $SAKAI_DEV/deploy folder.

Run Sakai

Start up Sakai by starting Tomcat. Watch your Tomcat output and monitor the logs! If things are not working, the logs will tell you what's going on.

Once started, you can access Sakai using this URL (modify this if you are using a different host name or port)


The out-of-box administrator's account and password are admin / admin.

Sakai CVS

In addition to the file to access the Sakai source code, you can access the latest and prior versions of the code using the Sakai CVS server.

Anonymous access to our CVS is supported by SSH key. We have a public key for the "anoncvs" user installed on our server; you can download the "private" matching key, install it on your development machine, and gain full read access to the Sakai source modules.

Get the private key from here sakai_anoncvs_dsa, and install it in the appropriate place on your computer, likely it's ~/.ssh. Don't change the file name when you install it.

Then add these lines to your ssh config file, located in the same place:


Make sure that the IdentityFile line points at your downloaded key.

Your environment variable "CVS_RSH" must be set as follows:


You can check out the sakai code module like this:

cvs -q -z9 -d :ext:sakai_anon_cvs:/cvs co sakai

This version has been tagged "sakai_1-5-0".

There are other root level modules in the cvs, but only the sakai module is required to build Sakai.

Sakai CVS on the web

You can also access the web interface to Sakai CVS.

Sakai Database Configuration

The default configuration of Sakai uses the HSQLDB database persisted in /usr/local/sakai/db/. At startup, these are read to re-populate the information in memory. This is a convenient solution for development, but not suitable for production.

For a Sakai server in production, you should use an external database, such as Oracle or MySQL 4.1+. This release supports both. Note that Sakai requires MySQL 4.1 or better, and does not support MySQL 4.0 at this time. Support for other databases may be available in later releases.

1. Drivers

You need to have appropriate JDBC drivers for your database installed in your Tomcat's /common/lib. For Oracle and MySQL, drivers are available here:

2. Prepare the Database

There are scripts in the Sakai reference module

  • $SAKAI_DEV/reference/src/sql/legacy/oracle/*.sql
  • $SAKAI_DEV/reference/src/sql/legacy/mysql/*.sql

The file all.sql lists the scripts you need to run - the path may not be correct for actually running this as a script.

Run these against the user you setup for Sakai's use on your database.

For example, here is a transcript of creating a MySQL user, database, and tables for Sakai:

Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.

C:\> cd C:\sakai\reference\src\sql\legacy\mysql
C:\sakai\reference\sql\legacy\mysql\> mysql -u root -p
Enter password: ******
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 51 to server version: 4.1.5-gamma-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> create database sakai default character set utf8;
Query OK, 1 row affected (0.00 sec)

mysql> grant all on sakai.* to sakaiuser@'localhost' identified by 'sakaipassword';
Query OK, 0 rows affected (0.00 sec)

mysql> grant all on sakai.* to sakaiuser@'' identified by 'sakaipassword';
Query OK, 0 rows affected (0.00 sec)

mysql> quit

The file all.sql contains the Sakai table definitions:

C:\sakai\reference\src\sql\legacy\mysql\> mysql --user=sakaiuser --password=sakaipassword sakai < all.sql
Field Type Null Key Default Extra
CHANNEL_ID varchar(99) PRI
CREATEDON datetime 0000-00-00 00:00:00


3. Configure Sakai's Database Connection Information

The /usr/local/sakai/ (or file needs to have the proper database connection information.

An example, for MySQL:


An example, for Oracle:


Set the appropriate driver, connection string, user and password. The maxConnections is the pool size for the connection pool. The maxSlowConnections defines a second pool used for "slow" operations, such as streaming download.
4. Configure Sakai's Service Components

To use the database, you need a set of service component implementations that use the database. Sakai ships with a set, and configurations for selecting them in the components_db.xml files. The easiest way to enable these is to run the maven command

  • maven conf_db

from your $SAKAI_DEV folder. This moves the database configuration files from the source tree into your /usr/local/sakai/*. Any changes you have made to the components.xml files in /usr/local/sakai/* will be overwritten.

5. Database Tips

Sakai has clustering capability. Multiple Sakai application servers can be run, all using the same back end database. Be sure to set the setting in to a unique value for each server in your cluster.

You may want to set the default character set of your MySQL server to be UTF-8.

You may want to set the MySQL timezone to GMT, although this is not strictly necessary.

Large file uploads cause large database queries. You may need to increase the maximum query size your database allows. In MySQL this can be accomplished by increasing the max_allowed_packet property in the the configuration file my.cnf:


Sakai uses a database connection pool to access the database. It's size can be configured (see above). If you have too small a pool, Sakai will slow down somewhat, as various components that need to access the database wait in line for a connection.

If you need to make back end database corrections to the data, by modifying the tables directly, not through Sakai, the Sakai servers in the cluster need to be informed of this. The admin site has a memory tool, and a command to Reset All Caches. This reset command is shared among all application servers in the cluster. When you make a change to the database, reset the caches so that Sakai can become aware of the change.

Prior versions of CHEF and Sakai used the database engine's record locking to implement our exclusive object locking policy. This tended to eat up database connections and, if overloaded, lead to massive gridlock and unresponsive Sakai servers. This version of Sakai uses a locking table in the database to accomplish exclusive locking, and no longer has this scaling problem.