Installation Guide

1. Overview

1.1. Choose an Install Type

Sakai 2.2.1 downloads are available for three different installation methods:


This archive includes the Tomcat container and pre-built webapps, so that the only prerequisite for getting started is Java (v. 1.4.2 or higher). While not intended for large-scale implementations, it is suitable for evaluating the software and small-scale pilot implementations on single servers.


This archive is a kind of Tomcat overlay. If you have a working Tomcat appropriately configured, the binary installation provides a quick way to drop the Sakai application bundle into place without requiring a maven build. This may be a good choice if you know you don't need to make any code-level changes.


This archive includes only the source code to build Sakai, and therefore calls for separate, preparatory installations of Tomcat and the Maven build tool, along with (most likely) a preferred database. The installation and configuration of these components comprises the bulk of this installation guide.

1.2. Demo Installation

A demo installation is brief and straightforward. The most technically challenging aspect of a demo install is making sure that your Java environment is squared away in advance. The steps are as follows:

  1. Verify Java Installation and Environment Variables (see the first two sections of Set up Environment).

  2. Download and unpack the Demo archive


    demo archive


    demo archive

  3. Start Tomcat with the following commands from the root Tomcat directory:




Once Tomcat is started up, you can 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 syste. For more orienting tips on how to begin using Sakai, skip ahead to Getting Started with the Software.

To stop the demo:




Special notes about the Demo installation

Data storage:

The data for a demo installation is stored in a HypersonicSQL database (HSQLDB) which is stored in memory and then written out to files when Tomcat is shut down. These files are located at sakai-demo/sakai/db/sakai.db.*.

Email not configured:

The Sakai demo is configured to neither send nor receive email.

1.3. Binary Installation

The Binary installation of Sakai provides a shortcut for those that already have Tomcat in place and configured as needed (see Set up Environment for details on Tomcat configuration), and it does so by providing a pre-built Sakai that can simply be dropped into place. All you need to do is unpack the binary archive at the root Tomcat directory, and the appropriate wars, jars, etc., will be deposited in the correct locations.

If you wish to configure a binary installation you'll need to manually create a sakai directory in $CATALINA_HOME to hold your file, as described in Post-Installation Configuration.

1.4. Source Installation

The Demo and Binary installs described above provide quick ways to get up and running, but assume that no code-level changes are called for. The remainder of this installation guide devotes itself to the more rigorous and customizable Source installation, although some of its details (e.g. the post-installation configuration) may also be pertinent for more sophisticated uses of the demo and binary installs. The full set of steps for a Source installation may be organized into the following phases:

  1. Set up Environment, including Java, Tomcat, and Maven.

  2. Build and Deploy Sakai by running Maven.

  3. Perform appropriate Post-installation Configuration of the application.

  4. If you want to configure Sakai for either MySQL or Oracle, perform the requisite Database Configuration.

1.5. Migrating from a Previous Release

2.2.1 adds only bug fixes to 2.2.0, and so a transition between the two should be straightforward. If you have been running 2.2.0 already, you should be able to deploy 2.2.1 with confidence: it will not break your skins, providers, or other 2.2 code.

If you are moving from an earlier 2.1 or 2.0 codebase, however, 2.2 involves some significant changes: in tools, DB schema, and APIs. Migrating to 2.2 from a previous release therefore requires close attention to detail. Be sure to go over the release notes carefully, and a few key hurdles are identified below:

The 2.2 framework refactoring means that many package names have changed, and these differences will mainly be encountered in settings which reference beans. It's best to not try to use a from a previous release, and instead start with the sample in reference/docs/

DB conversion scripts:

Every release has DB conversion scripts, and 2.2.1 is no exception. Be sure, however, to read these scripts over carefully before executing them on your production data. They do not take into account any special customizations you may have done, and you may need to alter them for your situation. See the Database Configuration section for more details.

Provisional tools:

A few contrib tools that schools may have already put into production are now provisional with 2.2 releases. The DB conversion scripts in particular assume that these new provisional tools are not represented in your schema, and attempt to introduce them. If you have already deployed Message Center, Post 'Em, Search, or Summary Calendar on a production system, you'll want to be sure to avoid running the portions of the conversion scripts that pertain to them. Again, see the Database Configuration section for more details.


Among the changes that 2.2 introduces is a separation of external user identifiers from Sakai's internal user ids. Any custom UserDirectoryProvider will need some alteration to account for this, along with changes to its import statements and declarations that stem from API changes. See the release notes for more details.