1.0 Get the Sakai 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 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.

Starting with Sakai 10, Kernel code is included when being checked out.

10 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-10.4/ sakai-10.4

Release Infomation

The latest stable release may be newer than the version listed above. Please see http://source.sakaiproject.org/release/ or the tags at https://source.sakaiproject.org/svn/sakai/tags/ and use the newest version for best results.

10.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-10.x/ sakai-10.x

2.0 Verify/Install Java 1.7

Oracle's Sun Java SE 7, a.k.a Java 1.7, is the preferred version to use with the Sakai CLE, because it has been tested the most thoroughly. Sakai 10 should have binary compatibility with Java 6. Certain files, such as *.jsp and *.jws, require compilation so downloading and attempting to use only the run time environment (JRE 7.0) will not suffice. Mac OS X 10.7 and above does not include a Java installation by default. If you find Sun's version and naming conventions confusing, see Sun Java SE Naming and Versions for an outline of their practices.

Oracle's Sun Java SE 6 (a.k.a Java 1.6) has completed the EOL process and is no longer supported. If are still running Java 1.6 please note that security vulnerabilities exist in JDK/JRE 6.0.

Java 7

As of June 19, 2013, an issue has been reported with respect to Java 7 compatibility. The problem is in the Comparators and the workaround is to use the JVM property

-Djava.util.Arrays.useLegacyMergeSort=true

This issue has been fixed for jdk7u60+.

For details see - http://sakai-project-mail-list-archives.1343168.n2.nabble.com/Building-Sakai-Java-7-and-Sakai-comparators-tt7589944.html and

SAK-38978 - Content Hosting comparators are incompatible with java 7 CLOSED

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, basic version and build information will be displayed:

java version "1.7.0_03" Java(TM) SE Runtime Environment (build 1.7.0_03-b05) Java HotSpot(TM) 64-Bit Server VM (build 1.7.0_03-b05, mixed mode)

If Java is not installed or you are running the wrong version you can download the Java SE 7.0 JDK release from Oracle's Sun archive:

http://www.oracle.com/technetwork/java/javase/archive-139210.html

Install the JDK, typically in the /opt directory, i.e. /opt/java. Install the JRE in a different directory (usually the default directory, especially if running Windows) or you may experience run-time issues.

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.

Variable	Unix	Mac	Windows

Variable	Unix	Mac	Windows
JAVA_HOME	`export JAVA_HOME=/usr/java/java-current`	`export JAVA_HOME=/Library/Java/Home`	`JAVA_HOME=C:\jdk1.6.0_24`
PATH	`export PATH=$PATH:$JAVA_HOME/bin/`	`export PATH=$PATH:$JAVA_HOME/bin/`	`;C:\jdk1.6.0_24\bin`

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

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.

Variable	Unix/Mac	Windows

Variable	Unix/Mac	Windows
SUBVERSION_HOME	export SUBVERSION_HOME=/opt/subversion	set SUBVERSION_HOME=C:\subversion
PATH	export PATH=$PATH:$SUBVERSION_HOME/bin	;C:\subversion\bin

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

4.0 Install Maven 3.0 or later

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.

It is recommended to use Maven 3.2.5 through 3.3.9.

You can download Maven at

http://maven.apache.org/download.html

Extract the distribution archive into your installation directory of choice, e.g. /usr/local/apache-maven-3.2.2. 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 3.2.5 (45f7c06d68e745d05611f7fd14efb6594181933e; 2014-06-17T09:51:42-04:00) Maven home: /usr/local/apache-maven-3.2.5 Java version: 1.8.0_111, vendor: Oracle Corporation Java home: /usr/lib/jvm/java-8-openjdk-amd64/jre Default locale: en_US, platform encoding: UTF-8 OS name: "linux", version: "3.13.0-30-generic", arch: "amd64", family: "unix"

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

Variable	Unix/Mac	Windows
MAVEN_HOME	`export MAVEN_HOME=/usr/local/apache-maven-3.2.2`	`set MAVEN_HOME=C:\apache-maven-3.2.2`
PATH	`export PATH=$PATH:$MAVEN_HOME/bin`	`;C:\apache-maven-3.2.2\bin`

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 MAVEN_OPTS via the GUI.

Because of some sorting done in various unit tests and the current issue with Java 7, you should add this useLegacyMergeSort to MAVEN_OPTS so all tests will pass.

EVALSYS-1389 - Evaluations Unit Tests don't compile with Sakai 10 RESOLVED

export MAVEN_OPTS='-Xms512m -Xmx1024m -Djava.util.Arrays.useLegacyMergeSort=true'

5.0 Install Tomcat 7

Apache Tomcat - http://tomcat.apache.org/
Note: Always do a fresh install of Tomcat (please note that Tomcat has a bug. Please use Tomcat 7.0.65 or Tomcat 7.0.68, when released. Addendum 30January2017 - appears to work with 7.0.75 as of this writing. Is known not to work with 7.0.72 through 7.0.74
SAK-31912 - FacesContext already released in JSF tools with Tomcat 7.0.72+ RESOLVED )
Note: Windows users should ensure that there are no spaces in the complete tomcat path as this causes errors with JSF tools in Sakai
GOOD: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\
BAD: C:\program files\tomcat\, C:\opt\apache tomcat 7.0.1\

Download Tomcat 7 if you're using Sakai 10- http://tomcat.apache.org/download-70.cgi
Download Tomcat 8 if you're using Sakai 11 - https://tomcat.apache.org/download-80.cgi
(The directions below are mostly the same for 7 or 8, but the setenv.sh is a little different)
- Windows users should get the zip file instead of installing a service
  It makes viewing the tomcat logs easier and it is easier to configure
  If you're running the tag of Sakai 2.9.1 or earlier you need to be running Tomcat 7.0.21 or earlier. If you go any higher Webdav and Sitestats will have errors and not work. A better solution is to upgrade to the latest version of Sakai and Tomcat.
  SAK-28531 - Sitestats does not load with Tomcat 7.0.35 CLOSED
  SAK-23156 - IncompatibleClassChangeError from WebDAV LOCK operations giving 500 response code CLOSED
Extract to /opt (symlink the apache-tomcat-7.0.x directory to tomcat after extracting)
- Example (assuming you have saved the file as /opt/apache-tomcat-7.0.x.tar.gz)
- Windows users should just rename the directory since they cannot symlink
Modify conf/server.xml for international character support
1. Add URIEncoding="UTF-8" to the Connector element
  - <Connector port="8080" URIEncoding="UTF-8" ...
Set environment variable: CATALINA_HOME=/opt/tomcat
Add $CATALINA_HOME/bin to PATH
Setup the SETENV file in the tomcat/bin directory with JAVA_OPTS (from Install Java 1.7+)
Populate Database With Demo Data
Instead of starting with an empty database you can add the flag -Dsakai.demo=true in addition to the others shown here. During your first Tomcat launch it will populate your database with test data (students, courses, etc). Once the data has been created remove this flag for subsequent Tomcat launches. Be advised that this flag will not trigger on a database with data already in it so you must make this choice during the initial setup. It should also be noted that without this flag one will not be able to create any course sites in Sakai unless Academic Term, Subject, Course, and Section data is manually added to the "cm_" tables in the database.
1. Mac/Linux: Create a file called setenv.sh with the following (alternately, you can put this into your .bashrc file so they're automatically executed):
  Tomcat 7 Mac/Linux
  Tomcat 8 Mac/Linux
2. Windows(PC): Create a file called setenv.bat with the following:
  Tomcat 7 Windows
  Tomcat 8 Windows
[OPTIONAL] Delete the default webapps from the webapps dir
rm -rf webapps/*

Configure tomcat 7/8 to use the old tomcat 5.5 classloader dirs, this is not needed for the master branch of Sakai and Sakai 11.

Edit conf/catalina.properties
1. Add the following to the line that begins with "common.loader=..."
  - Tomcat 7
    ,${catalina.base}/common/classes/,${catalina.base}/common/lib/*.jar
  - Tomcat 8
    ,"${catalina.base}/common/classes/","${catalina.base}/common/lib/*.jar"
2. Add the following to the line that begins with "server.loader=..."
  ${catalina.base}/server/classes/,${catalina.base}/server/lib/*.jar
3. Add the following to the line that begins with "shared.loader=..."
  ${catalina.base}/shared/classes/,${catalina.base}/shared/lib/*.jar
Create the directories
mkdir -p shared/classes shared/lib common/classes common/lib server/classes server/lib

Improve startup speed

You can improve startup speed under both Tomcat 7 and Tomcat 8 significantly.

Tomcat 7

Edit the file conf/catalina.properties and add the property to the bottom

org.apache.catalina.startup.ContextConfig.jarsToSkip=*.jar

Tomcat 8

Edit the file conf/context.xml and add this JarScanFilter block to the context

<Context>

<JarScanner>

<JarScanFilter defaultPluggabilityScan="false" />

</JarScanner>

</Context>

6.0 Configure Sakai

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. You may want to create a local.properties file in the same directory as sakai.properties. Properties listed in local.properties override sakai.properties.

For a source installation 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

The bin package does not include a sakai.properties file. This is a deliberate exclusion; it eliminates the possibility of overwriting a local sakai.properties file if a bin package is opened over an existing Sakai installation.

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. We recommend that you review the default.sakai.properties file included in the source installation or in the appropriate maintenance branch.

Version	default

Version	default
11	default.sakai.properties
10	default.sakai.properties
2.9	default.sakai.properties

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/

6.1 Default database support (HSQLDB)

By default Sakai 2.9 distributions (demo, binary, source) are configured to use an in-memory version of HSQLDB on start up. HSQLDB is deprecated for Sakai 10 and later.

Many developers and the vast majority of Sakai installations choose to run either MySQL or Oracle in their local and production environments and the default and sample sakai.properties include configuration settings for both databases. Click the "Configure" tab above for instructions on setting up Sakai to use MySQL or Oracle. For MySQL download https://mariadb.com/kb/en/mariadb/about-mariadb-connector-j/ and copy into the lib directory.

You will not need to create Sakai database objects (tables, indices, etc) when setting up your database. Sakai generates its own database schema automatically during the Tomcat setup process via the autoDDL setting in sakai.properties.

6.2 Configure database

Create a Sakai database with a default character set of UTF-8. Create a user account to which you will assign all permissions.

Use any database name and username you wish and then update your sakai.properties file (or even better, create a local.properties file, which has precedence).

In the example below the database is named "sakaidatabase" and the user account is "sakaiuser".

Excerpt from sakai.properties

username@javax.sql.BaseDataSource=sakaiuser
password@javax.sql.BaseDataSource=sakaipassword

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

mysql -u root -p Enter password: Welcome to the MySQL monitor. Commands end with ; or \g. Your MySQL connection id is 272 Server version: 5.1.46 MySQL Community Server (GPL) Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. This software comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to modify and redistribute it under the GPL v2 license Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. mysql> create database sakaidatabase default character set utf8; Query OK, 1 row affected (0.00 sec) mysql> grant all on sakaidatabase.* to sakaiuser@'localhost' identified by 'sakaipassword'; Query OK, 0 rows affected (0.00 sec mysql> grant all on sakaidatabase.* to sakaiuser@'127.0.0.1' identified by 'sakaipassword'; Query OK, 0 rows affected (0.00 sec) mysql> flush privileges; Query OK, 0 rows affected (0.00 sec) mysql> quit

7.0 Build, deploy and start up Sakai in Tomcat

Install the Sakai master project

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 Sakai pom.xml files. If you are building Sakai for the first time you should install the master project first by issuing the clean and install goals from the /master project folder.

Sakai 10 install guide (source)