Skip to end of metadata
Go to start of metadata
This page contains macros or features from a plugin which requires a valid license.

You will need to contact your administrator.

 

Sakai Collaboration and Learning Environment (CLE) 2.7.2

released: 10 Sept 2011

The Sakai Collaboration and Learning Environment (CLE) is a Java-based, service-oriented web application that provides a variety of capabilities supporting teaching and learning, portfolios, research, and ad-hoc project collaboration. The Sakai CLE is typically deployed using Apache Tomcat as its servlet container and scalability is achieved by running multiple instances of Tomcat in a clustered environment, each deploying a copy of the Sakai CLE. It integrates with a variety of external authentication services including CAS, Kerberos, LDAP, Shibboleth and WebAuth. A single database, usually MySQL or Oracle, provides a transactional store of information while file storage is typically delegated to NAS or SAN solutions. In most production settings, the Sakai CLE relies on a back-end student information system (SIS) to provide it with student and course information, which the Sakai CLE consults via provider APIs.

The Sakai Collaboration and Learning Environment (CLE) 2.7.2 maintenance release provides over 370 bug fixes that address key areas like accessibility, internationalization, performance and security.

Our thanks go out to the dedicated Sakai Community volunteers from around the world who have made this release possible.

Icons are used throughout the release notes to highlight important points in the installation, configuration, build and deployment process. Below is a list of the icons you will encounter:

(tick) Hints (info) Useful Information (warning) Caution (minus) Warning (thumbs up) Good practice (thumbs down) Bad practice

The documentation is presented here for ongoing comment, correction, and clarification, so please use the "Add Comment" link at the bottom of any of these pages if you note errors, require further details or have tips to share.

What's new

Release

Capability

Version

Notes

2.7.0

Conditional Release

2.7.0

 

2.7.0

IMS BasicLTI

1.1.3

Contrib tool promotion.

2.7.0

Profile2

1.3.8

User profile replacement.

2.7.0

Sitestats

2.1.4

Contrib tool promotion.

Language updates and additions

Release

Language

Country

locale

2.7.0

Catalan

Spain

ca_ES

2.7.0

English

United States

en_US

2.7.0

French

France

fr_FR

2.7.0

Japanese

Japan

ja_JP

2.7.0

Portuguese

Portugal

pt_PT

2.7.0

Russian

Russia

ru_RU

2.7.0

Spanish

Spain

es_ES

 

System requirements

Operating system (OS) choices

The Sakai CLE is OS neutral. It is typically run on any of the numerous Linux distributions such as CentOS, Debian GNU/Linux, Fedora, Gentoo Linux, Red Hat Enterprise Linux (RHEL), SuSe Linux, Ubuntu but is also run on Mac OS X server, Microsoft Windows and Sun Solaris. Operating systems other than Linux are not nearly as well tested, and all of the community QA servers are running Linux, so this is generally the recommendation.

Examples:

Cerritos College, Windows 2003.
Georgia Tech, RHEL.
Indiana University, RHEL.
Mount Holyoke College: Debian GNU/Linux.

Oxford University: Debian GNU/Linux.
Rutgers University: Sun Solaris.
University of California, Berkeley: Sun Solaris.
University of Cape Town: SuSe Linux.

University of Florida: RHEL.
Universidad de Murcia: CentOS.
University of Virginia: Fedora.
Virginia Tech: Ubuntu.

Java

Oracle's Sun Java SE 6, a.k.a Java 1.6, is the preferred version to use with the Sakai CLE. Certain files, such as *.jsp and *.jws, require compilation so downloading and attempting to use only the run time environment (JRE 6.0) will not suffice. Mac OS X 10.6 (Snow Leopard) includes the full version of Java SE 6 so Mac users do not need to install Java. 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 J2SE 5.0 (a.k.a Java 1.5) has completed the EOL process and is no longer supported. If are still running Java 1.5 please note that security vulnerabilities exist in JDK/JRE 5.0 updates 1.5.0_17 and earlier.

For Sakai 2.9 OpenJDK and JDK 7 are supported along with JDK 6. Previous releases would not work with OpenJDK.

Application server choices

The Sakai Community is overwhelmingly an Apache http/Apache Tomcat user community and the Sakai CLE is at home in such an environment. Some Several schools run their Tomcats with Windows IIS and nginx proxies without issue. Since Sakai CLE 2.7.0 a Websphere module was included in the release in order to facilitate deployment to a Websphere/Db2 production environment; however, support has waned and the Websphere option is currently considered deprecated. A few schools such as Hong Kong University of Science and Technology and the Universidad de Guadalajara report deploying Sakai on JBoss.

Sakai 2.8.0 and previous releases require Tomcat 5.5 out of the box but can be configured in custom builds to run under Tomcat 7. Tomcat 7 is the requirement for running Sakai 2.9.0+. There are some changes to the Tomcat configuration required to get Sakai to startup in the source or binary form under Tomcat 7. Please see this page for more information!

Database choices

Sakai CLE production installations typically run either Oracle 10g/11g or MySQL 5.0/5.1. Support for IBM Db2 was added for the Sakai CLE 2.7.0 release but for 2.8.0 DB2 conversion scripts were not updated or tested and are currently considered deprecated. A demo version of Sakai includes HSQLDB; it should never be deployed in production.

It should be noted that Sakai is not limited to these database choices and integration with other RDBMS systems is not difficult. In the past at least one installation used Microsoft SQL Server while requests for PostgreSQL integration are occasionally raised on the Sakai developers list. However, to date no one in the Sakai Community has stepped forward to support alternatives to either Oracle or MySQL, a prerequisite for adding additional database options to the release.

Australian National University, MySQL 5.1
Indiana University, Oracle 10g
Oxford University, MySQL 5.0

Stanford University, Oracle 10g
Texas State University, San Marcos, MySQL 5.1
University of Cape Town, MySQL 5.1

University of Florida, Oracle 11g
University of Virginia, MySQL 5.0
University of Michigan, Oracle 10g
Virginia Tech, Oracle 11g

Clustering, file storage and load balancing strategies

A typical Sakai CLE cluster is comprised of one or more application servers running one or more instances of Tomcat 5.5 operating either in standalone mode or behind the Apache HTTP 2.2 web server. Each Tomcat instance runs a full copy of the Sakai CLE. The cluster is backed by a single database providing a transactional store of information. Storing binary content outside the database is a configurable option in Sakai and highly recommended from a performance standpoint. Most Sakai schools with sizable user populations opt for network-attached storage (NAS) or storage area network (SAN) solutions. Load balancing is provided by Apache (using mod_jk, mod_proxy_balancer or mod_proxy_ajp) or dedicated hardware solutions such as F5 BIG-IP, NetScaler or Zeus.

Three examples should suffice:

University of Cape Town
User base: 27,000+
Cluster: six Dual Xeon 3.6 GHz 8G RAM, 64-bit SuSe Linux (4 x physical servers, 2 x VMWare servers).
App servers: Apache HTTP server 2.2, Tomcat 5.5, Sakai 2.7.1.
Database: MySQL 5.1, 2 x dual-core processors, 16G RAM.
File storage: SAN Disk shared via NFS.
Load balancing: Apache 2.2 with mod_jk.

University of Michigan
User base: 45,000+
Cluster: five Dell PowerEdge 1950 boxes, each with 16 GB RAM running 64-bit RHEL 5.x (a sixth PowerEdge 1950 is utilized outside the cluster as a search server).
App servers: Apache HTTP server 2.2, fronting a single Tomcat 5.5/Sakai 2.7.1 install. One Java 1.6 JVM is configured per server with a 6 GB heap.
Database: Oracle 10g running on a Sun Fire T5120 with 128 GB RAM and Solaris 10 as the OS.
File storage: allocated 6 TB of disk space and stored externally in a NetApp FAS3020 filer, NFS mount.
Load balancing: two NetScaler RS9800 Secure Application switches.

Indiana University
User base: 100,000+
Cluster: two HP DL740 servers, 8-way with 3.0 GHz CPUs, 64 GB RAM and an IBM ESS "Shark" SAN running nine virtual application servers.
App servers: each virtual server is allocated 2 CPUs and 3.6 GB RAM and runs Apache HTTP 2.2/Tomcat 5.5.
Database: the Oracle 10g database is also a virtual instance housed on a Dell 810, dual socket, Quad Core server. The database is allocated 8 CPU and 32 GB RAM.
File storage: allocated 7 TB of disk space and is stored externally utilizing two NetAppliance FAS920C filers, NFS mount.
Load balancing: two HP DL385 servers running Zeus ZXTM load balancers. The load balancers run under Red Hat Enterprise Linux (RHEL) within VMware virtual machines and the architecture allows for more horizontal scaling if required.

See also:

External Authentication choices

The Sakai CLE can integrate with a variety of external authentication services including CAS, Kerberos, LDAP, Shibboleth and WebAuth.

Examples:

Australian National University: LDAP.
Indiana University: CAS.
Georgia Tech: CAS.
Oxford University: WebAuth.
Pepperdine University: CAS.

Stanford University: Kerberos.
Stockholm University: Shibboleth.
University of California, Davis: CAS.
University of Delaware: LDAP.

University of Hawaii: LDAP.
University of Michigan: Kerberos.
University of Florida: Shibboleth.
Yale University, CAS.

Integrating with student information systems

Sakai Community institutions have integrated their Sakai CLE installations with Banner, Datatel and Peoplesoft as well as a variety of home-grown student information systems (SIS).

The Sakai CLE has two basic approaches to integrating data from external systems. Most sites use a combination of these approaches. The first approach is to use the internal Sakai "provider" APIs. These APIs are places for Sakai to "consult" while Sakai is running. There are APIs for User Identity, User Directory, Course Listing and User Roles.

User Identity API: allows Sakai to call local code to validate users when they log into the system. This commonly uses Kerberos, Active Directory or LDAP to validate the user's credentials.

User Directory API: allows user information such as name and e-Mail address to be retrieved from an external system such as LDAP or X.509. The User Directory API has provisions to allow the local site to make decisions when to display student information in order to meet FERPA requirements. Each institution has different interpretation of FERPA so the precise FERPA decisions are delegated to the User Directory API.

Course Listing API: consulted when the instructor is creating a course site - this API returns the list of externally stored rosters for which the current user is the instructor. The user can select from one or more of these external rosters to associate with the course they are creating.

User Role API: is consulted when users log in to determine which external rosters they user is a member of and what their role is within those rosters. The Sakai internal configuration is updated if there are any changes to an individual's roster status.

The above API's are "pull" APIs--they are consulted when the user logs in or tries to take some action. The Course List API described above does not auto-populate courses.

If there is a desire to "push" information into the Sakai CLE, there are two approaches - Quartz and web services.

Sakai utilizes an internal batch system called Quartz that provides a cron-like capability within Sakai. Quartz is used by creating a Java class that does the necessary work and then having Quartz schedule the regular execution of that Java code.

A more common approach to pushing configuration information into Sakai is through web services. Any of Sakai's APIs can be accessed by web services. Web service access points have been developed for many of the common Sakai APIs used for configuration. These SOAP web services can be called from PHP, Python, Perl, Java, .NET or any other language. The Sakai CLE web service data structures are kept simple to insure the widest possible interoperability with as many languages as possible. Administrators often build scripts to pull data from their SIS system and populate the Sakai CLE with that data. These scripts may be automated using cron or manually executed by the administrator at the proper time during a semester.

This combination of pull/push configuration capabilities allows for a very wide range of integration possibilities for the Sakai CLE.

 

Downloading

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.

Demo archive

The Sakai Demo is a pre-built version of Sakai with Apache Tomcat and a simple configuration, perfect for a quick and easy demo of Sakai. The demo is NOT intended for large scale implementations. It is suitable only for evaluating the software and running small pilot implementations on a single server.

Binary archive

The Sakai Binary is a pre-built version of Sakai without Apache Tomcat, jar dependencies, or extra configuration files. Download the Binary release if you want to just drop the Sakai bundle into a pre-existing Tomcat environment.

Source archive

The Sakai Source includes Sakai portal, tool and service source code. Start from Source if you plan to make any code-level changes to your Sakai system.

Source checkout

Sakai source code can also be checked out anonymously from our SVN repository. The latest development work is located in /trunk; stable releases can be found in /tags while maintenance, experimental and other work are located in /branches.

For example, to checkout a stable Sakai 2.7.2 release tag issue the following Subversion terminal command:

svn co https://source.sakaiproject.org/svn/sakai/tags/sakai-2.7.2/ sakai-2.7.2

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 Subversion terminal command:

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

Indie projects

A number of Sakai CLE projects (known collectively as "indie" projects) are currently not included in either the source archive or source check out. Instead, these projects are downloaded, installed in your local .m2 repository and then deployed to Tomcat as *.zip overlays during the Maven build process. If you need to apply any local customizations to these projects you must check out the code separately.

Indie project teams manage their own release cycles independently of the general Sakai CLE release cycle, permitting more frequent "off-cycle" maintenance releases for key projects such as the Kernel or Test and Quizzes.

Each Indie project site includes a variety of reports regarding the release, including Javadocs.

CLE Release

Project Site

Tag

Maint branch

Notes

2.7.2

kernel

1.1.14

1.2.x

 

2.7.2

basiclti

1.1.9

1.3.x

 

2.7.2

common

1.0.10

1.1.x

 

2.7.2

edu-services

1.0.13

1.1.x

 

2.7.2

emailtemplateservice

0.4.8

0.4.x

 

2.7.2

entitybroker

1.3.20

1.3.x

 

2.7.2

jobscheduler

2.7.9

2.7.x

 

2.7.2

jsf

2.7.12

2.7.x

 

2.7.2

msgcntr

2.7.7

2.7.x

 

2.7.2

polls

1.3.16

1.3.x

 

2.7.2

profile

2.7.7

2.7.x

 

2.7.2

profile2

1.3.18

1.3.x

 

2.7.2

purepoms

2.7.12

2.7.x

 

2.7.2

sakai-mock

2.7.7

2.7.x

 

2.7.2

samigo

2.7.5

2.7.x

 

2.7.2

search

1.2.11

1.2.x

 

2.7.2

sitestats

2.1.11

2.1.x

 


 

Installing

Unknown macro: {composition-setup}

cloak.toggle.type = text
cloak.toggle.open = [+]
cloak.toggle.close = [-]

Unknown macro: {toggle-cloak}
Demo install

Unknown macro: {cloak}
Unable to render {include} The included page could not be found.
Unknown macro: {cloak}

Unknown macro: {toggle-cloak}
Bin install

Unknown macro: {cloak}

1.0 Get the binary archive

(warning) Binary limitations. Post-release patches are not always packaged as jars, so a binary install forces a relatively static implementation that cannot be as readily patched later.

The binary distribution of Sakai provides a shortcut for those that already have Tomcat in place and configured as needed (including the database setup and 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., for the Sakai application will be deposited in the correct locations.

The latest Sakai binary archive is available at http://source.sakaiproject.org/release/.

2.0 Verify/Install Java 1.6

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

2.1 Set Java environment variables

Several environment variables and related properties must be set for Java. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set JAVA_HOME via the GUI.

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

(info) 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

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

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

(tick) 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

(minus) 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 - Getting issue details... STATUS ). 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 - Getting issue details... STATUS ). Finally, specify an HTTP user agent other than "Java/xxxxx" in order to resolve Google and other RSS feeds (see SAK-10159 - Getting issue details... STATUS , SAK-13353 - Getting issue details... STATUS and SAK-18044 - Getting issue details... STATUS ).

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

(warning) Tomcat 5.5: we recommend Tomcat 5.5.33 in order to avoid certain Tomcat security vulnerabilities present in earlier releases.

(minus) Tomcat 6.0 / 7.0: Sakai 2.7 has not been tested in Tomcat 6.0 or 7.0 and will not run in either version of Tomcat without configuration changes. Adopters are advised to stay with the Tomcat 5.5. series.

(warning) JAVA_OPTS: running Sakai 2.x in Tomcat 5.5.27+ requires JAVA_OPTS modifications (see below).

(info) Sakai installations should always be accompanied by a fresh install of Tomcat. It provides a clean environment that simplifies troubleshooting if problems are encountered during the startup phase.

The Apache Tomcat servlet container provides an ideal environment for running Sakai as a web application. Tomcat implements both the Java Servlet and JavaServer Pages (JSP) specifications and can be run in standalone mode or in conjunction with a web application server such as the Apache HTTP server or JBoss. Sakai 2.7 works with the Tomcat 5.5 series.

Tomcat can be downloaded as a binary install from http://archive.apache.org/dist/tomcat/tomcat-5/

Choose the core distribution. Windows users have the option of downloading either a Windows Service Installer .exe or a binary *.zip archive. We recommend the *.zip archive over the installer because configuration and log viewing are easier. You can later convert the .zip install into a service install by running /bin/service.bat (see below for more details).

Unpack the Tomcat archive into your installation directory of choice, e.g. /opt/. Unix/Mac users should create a symbolic link (e.g., ln -s apache-tomcat-5.5.33) while Windows users should simply rename the base Tomcat directory to /tomcat to simplify the path.

Tomcat pathnames

Windows users should ensure that the Tomcat path includes no spaces as this causes errors with JavaServer Faces (JSF) tools in Sakai.

(thumbs up) Good: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\
(thumbs down) Bad: C:\program files\tomcat\, C:\opt\apache tomcat 5.5.33\

Tomcat permissions

Unix/Mac users should make sure that they have write permissions to the Tomcat servlet container files and directories before proceeding or startup permission errors may occur.

Tomcat JDK 1.4 Compatibility Package

(minus) Do not download and install the JDK 1.4 Compatibility Package. Sakai 2.7 will not run should you install it.

3.1 Set Tomcat environment variables

By convention, the base Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.31) is referred to as $CATALINA_HOME. As a convenience, you should create a $CATALINA_HOME environment variable. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set your Tomcat environment variables via the GUI.

Set the CATALINA_HOME environment variable to point to the base directory of your Tomcat installation and add the Tomcat /bin directory to your PATH variable:

Variable

Unix/Mac

Windows

CATALINA_HOME

export CATALINA_HOME=/opt/tomcat

CATALINA_HOME=C:\tomcat

PATH

export PATH=$PATH:$CATALINA_HOME/bin

;C:\tomcat\bin

(warning) Windows: append string to the end of the Path system variable.

3.2 Configure Tomcat

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

(warning) Neglecting this adjustment will force users 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.

3.3 Tomcat memory management

You can better manage Tomcat memory usage by creating a setenv.sh/.bat 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 -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: create a file called setenv.bat and add the following line:

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'

3.4 Set up Tomcat as a Windows service

You can convert the .zip install into a service install by running service.bat from the /bin directory:
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".

After this you need to set the default startup options:

C:\tomcat\bin> tomcat5 //US//Tomcat5 ++JvmOptions "-Xms512m;-Xmx1024m;-XX:PermSize=128m;-XX:MaxPermSize=256m;-Dfile.encoding=UTF-8; -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false"

If you choose to do this in the GUI follow these steps: 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, you'll need to change the Java Virtual Machine path from ..\bin\client\jvm.dll to ..\bin\server\jvm.dll.

(minus) Java 1.6 users will you need add the system property -Dsun.lang.ClassLoader.allowArraySyntax=true. This option is not required for Java 1.5. Please see the Java section above or SAK-15874 for more details.

Be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI, e.g.:

-Xms512m
-Xmx1024m
-XX:PermSize=128m
-XX:MaxPermSize=256m
-Dfile.encoding=UTF-8
-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
-Dsun.lang.ClassLoader.allowArraySyntax=true
-Dhttp.agent=Sakai

(warning) Samoo has reported that display issues after editing text documents with accented characters using the resources tool. The issue was resolved by adding -Dfile.encoding=UTF-8 as a Java option (open command window -> type "tomcat5w" -> "Java" ->"Java Options:").

You can add additional system properties if needed, e.g., -Dsakai.security=C:\tomcat\security.

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.

(warning) Java 1.6 users may encounter the unhelpful system log error "The Apache Tomcat service terminated with service-specific error 0 (0x0)". This can be fixed by copying the file msvcr71.dll from the /bin directory into the server or client directory with the jvm.dll file.

To set up remote debugging, please see (Remote Debugging).

4.0 Unpack the Sakai binary distribution

The Sakai binary archive is available at http://source.sakaiproject.org/release/. The URL redirects to the most current release. If looking for an earlier release append the version number to the URL (e.g., http://source.sakaiproject.org/release/2.6.2).

Download the archive into $CATALINA_HOME and then unpack the archive. Then start up Tomcat by running the Tomcat start up script in $CATALINA_HOME/bin. Unix/Mac users should make sure that they have write permissions to the Tomcat servlet container files and directories before proceeding or start up permission errors may occur.

(warning) If you wish to configure a binary installation you'll need to manually create a /sakai folder in $CATALINA_HOME to hold your sakai.properties file.

4.1 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

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

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/

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

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

5.0 Start/Stop Tomcat

Start/stop Tomcat from the terminal by running the appropriate startup/shutdown script located in $CATALINA_HOME/bin:

Unix/Mac

sh startup.sh
sh shutdown.sh

Windows

startup.bat
shutdown.bat

6.0 Explore Sakai

You should at this point have a working Sakai installation. Now it's time to get started with adding users, creating work sites, and otherwise playing around with the tools. We won't try to present a full user's guide here, but we can offer some pointers to get you oriented and on your way, and link you to more exhaustive sources of information elsewhere.

The Gateway Page

Once Tomcat has started successfully, you should be able to direct your browser to its gateway page at http://localhost:8080/portal (or replace 'localhost' with the name of the server where it's installed). From the gateway page you can create new accounts or browse for public site content. You could start by creating a new account, but that can also be done as an admin, and since the admin functions are needed to allow this account the right permissions, it's just as well to start by logging in as the admin user. Sakai's out-of-the-box admin account is simply named 'admin' (with password also 'admin'), so use those credentials to log in.

My Workspace

Every user on the system - including the admin - has a private site called My Workspace. It's the landing point upon logging in, and it's the first site tab visible at the upper left. Running vertically along the left-hand side of the screen are links to the various different tool pages within a given site, and the admin's My Workspace has a different set of such options here than most (each different type of account can be configured to have a different set of tools in its My Workspace by altering a template - see below).

Other Sites

Each new (accessible) site becomes visible as a tab along the top, to the right of My Workspace. For most users, they initially only have access to one site - their My Workspace. The admin user is a little different, in that it has access to two. The second admin site (which you can enter by clicking on its tab) is entitled Administration Workspace which, strangely enough, looks exactly the same as the admin My Workspace. It is.

Why the redundancy? Because you'll likely want to make these admin tools available to a particular user who doesn't have access to the admin's My Workspace (no one has access to other people's My Workspace on the system). To allow anyone access to the admin tools, you need only add them to the list of users of the Administration Workspace, and then promote them in the site to the "admin" role.

Admin Tools

Creating Users

The first thing you may want to do is to change the admin password to something secure, and to start creating a few sample users on your system. You can do both of those tasks through the Users tool on the left. To change the admin user's password, simply click on the 'admin' username in the list of users, and edit the fields on the subsequent page. To create users, click on the New User action link at the top of the tool page.

Creating Sites

If you're itching to create your first worksite, you may be tempted to dive directly into the Sites tool. That would probably be a mistake. The Sites tool is a powerful way to construct an entire site from the ground up, with fine-grained control over its every page, tool, and configuration detail. But this flexible power comes with a price, making for an intimidating interface and epic-scale workflow. The Sites tool is therefore best used as a way to tweak an existing site after the fact, once the standard pieces have been more expediently assembled.

The best way to start creating sites, therefore, is to use the Worksite Setup tool. Click on the New link at the top of the tool page, and then, for simplicity's sake, choose the Project site type, which will allow you to avoid issues of academic term, etc., that are provoked by a "course" site - issues which are probably unnecessary if you just want to start playing with the tools. Either type of site will serve, however: both types of sites have all the tools available to them.

Step through the remaining site creation pages, making your preferred selections. Be sure to click the Create Site button at the end of the process. After doing so, you should see the site title visible as a new tab along the top of the screen.

Adding Users to Sites

Since you set this site up as an admin, the admin is technically the owner of this site, and its only member at first. If you want to add other sample users to this site in different roles, you can do so through the Site Info tool of the site itself.

Click on the tab of your new site (which should now be visible) to enter it, and then click on the Site Info link along the left hand side. Site Info has a number of site maintainer functions available as action links across the top, and Add Participants is the one that will allow you to connect other users to the site. These users will of course need to have been previously created.

As long as we're here in Site Info, it's worth pointing out that the Edit Tools link at the top will allow you to remove and add tools from the site.

Experimenting with Tools

You may have noticed an extra tool appear in your site - one which you didn't explicitly choose - labeled Help. This tool provides online documentation of the various bundle tools, and other facets of the system. This should be your companion as you learn more about the software's functionality.

This Help tool is also reached in a context-sensitive way by clicking on the question mark icons at the upper right of any particular tool frame. Clicking on those question marks will open up the precise content of the tool you happen to be in at the time.

At some later point, when you become comfortable with the standard tools, you may wish to see other, more experimental tools that are available for Sakai. The Sakai distribution includes provisional tools that are still maturing, but can already serve needs in innovative ways that the standard ones do not. These extra tools require additional steps to enable, so that system users will not stumble across them inadvertently if that's not desired, but you are encouraged to evaluate them for your own deployment.

Where to Learn More

About the Project

The sakaiproject.org site offers the best background and orientation to the project and its goals, but chances are you've already seen it. For more particular information on the progress and roadmaps of certain tools or other initiatives, see the relevant Confluence spaces.

Community Participation

The Sakai Community provide email forums on a variety of topics. The lists are open, however, they do reject all non-member email, so you need to join a list before you can post to it, though you can still access its archives.

The four main Sakai community lists are:

Announcements (announcements@apereo.org) - items of community-wide interest in Apereo, including Sakai (receive newsletters; learn about conferences and deadlines; follow general progress on upcoming releases; participate in calls for community input). A low-volume, read-only list, which everyone should join.

Building Sakai (sakai-dev@collab.sakaiproject.org) - designing, developing, testing, and documenting Sakai (learn about the technical details of building tools or integrating services; find guidelines for design and development of tools and services; locate technical specifications; learn about plans for future releases). For designers, programmers, developers, and quality assurance.

Pedagogy (pedagogy@collab.sakaiproject.org) - teaching and learning, collaboration, and other uses of Sakai (learn about best practices; share experiences; connect with user communities with similar interests, K-12, Higher-Ed, Portfolios). For teachers, staff, students, researchers, instructional designers, instructional technologists and end-user support staff.

Deploying Sakai (production@collab.sakaiproject.org) - implementing, installing, configuring, and supporting Sakai (find release documentation; learn about performance tuning; browse suggested hardware and software configurations; share examples of training, tutorial and support materials). For sysadmins, DBAs, and technical support staff.

There are also a variety of smaller, topic-specific working groups that use email lists, which you may also find of interest as you get more involved with the community.

To join a Sakai mailing list point your browser to:

http://collab.sakaiproject.org/mailman/listinfo/

and join the lists that interest you. You will be asked to fill out a short form (username, password) and you can select whether or not to receive each list post individually (default) or batched in a daily digest. Once you have submitted your request you will be sent a confirmation email with a short set of instructions for confirming your subscription request.

About Technical Matters

Reference materials for various technical issues are best found in Sakai's subversion repository (where these installation documents are also stored) or in the project's Confluence wiki. The docs in subversion can be found in the reference module, e.g. https://source.sakaiproject.org/svn/reference. See in particular the docs/architecture folder contained there, which contains a wide-ranging collection of technical white papers.

The Confluence wiki is a more informal source of information, but also valuable and broader in scope. New developers in particular should visit the Programmer's Cafe. You are encouraged to create an account there and participate.

But often the most incisive information comes from direct interaction with your peers. As mentioned above, the Collab Server is the place to go for this. For technical questions the best (and most active) such group is DG: Development, also commonly referred to by its alias, "sakai-dev."

Unknown macro: {cloak}

Unknown macro: {toggle-cloak}
Source install

Unknown macro: {cloak}

1.0 Get the Sakai CLE source code

There are two ways to acquire Sakai source code. You can choose to download a packaged *.zip or *tar.gz file from Sakai's release page or check out the code directly from our code repository using Subversion's (SVN) source control management system.
Packaged releases are available at http://source.sakaiproject.org/release/.
Sakai source code can also be checked out anonymously from our SVN repository. The latest development work is located in /trunk; stable releases can be found in /tags while maintenance and other work is performed in /branches.

Starting with Sakai 2.6, Sakai common services (e.g., authz, content, event, site, tool, user, etc.) have been repackaged and refactored as the Sakai Kernel (K1). In most cases, you will never have to check out the kernel manually as Sakai kernel dependencies are managed by Maven.

2.7 release archive

You can download an archive of Sakai source code:

2.7 release tag

To checkout a stable release tag issue the following svn command from the terminal:

svn co https://source.sakaiproject.org/svn/sakai/tags/sakai-2.7.1/ sakai-2.7.1

2-7-x maintenance branch

The latest bug fixes for a particular release can be found in our maintenance branches. Please note that certain maintenance branch fixes require database schema changes. You can check out the maintenance branch by issuing the following command from the terminal:

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

2.0 Verify/Install Java 1.6

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

2.1 Set Java environment variables

Several environment variables and related properties must be set for Java. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set JAVA_HOME via the GUI.

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

(info) 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

JAVA_HOME

export JAVA_HOME=/usr/java/java-current

export JAVA_HOME=/Library/Java/Home

JAVA_HOME=C:\jdk1.6.0_02

PATH

export PATH=$PATH:$JAVA_HOME/bin/

export PATH=$PATH:$JAVA_HOME/bin/

;C:\jdk1.6.0_02\bin

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

(tick) 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

(minus) 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 - Getting issue details... STATUS ). 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 - Getting issue details... STATUS ). Finally, specify an HTTP user agent other than "Java/xxxxx" in order to resolve Google and other RSS feeds (see SAK-10159 - Getting issue details... STATUS , SAK-13353 - Getting issue details... STATUS and SAK-18044 - Getting issue details... STATUS ).

-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

Specify an HTTP Proxy (optional)

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

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

3.0 Install Subversion 1.6+

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

http://subversion.apache.org/

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

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

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

3.1 Set Subversion environment variables

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

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

(warning) Windows: append the string to the end of the Path system variable

4.0 Install Maven 2.2.1

The Apache Maven project management framework provides Sakai with "a set of build standards, artifact repository model and a software engine that manages and describes projects" (Better Builds, p. 22). As part of the installation process you will use Maven as a build tool in order to compile, test and deploy Sakai to a servlet container such as Apache Tomcat.

(warning) Maven 2.2.1 is required for performing Sakai 2.7 builds.
(minus) Maven 3.0 is currently NOT compatible with Sakai 2.7.

You can download Maven at

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

Extract the distribution archive into your installation directory of choice, e.g. /opt/maven/apache-maven-2.2.1. Confirm that you have installed the correct version of Maven and can start it by issuing mvn --version from the terminal. At this point your environment is prepared to build and deploy the Sakai source code.

mvn --version
Apache Maven 2.2.1 (r801777; 2009-08-06 15:16:01-0400)
Java version: 1.6.0_20
Java home: /System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Home
Default locale: en_US, platform encoding: MacRoman
OS name: "mac os x" version: "10.6.3" arch: "x86_64" Family: "mac"

4.1 Set Maven environment variables

A number of environment variables must be set for optimal Maven performance. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set your Maven environment variables via the GUI.

Set the MAVEN_HOME environment variable to point to the base directory of your Maven installation and add the Maven /bin directory to your PATH variable:

Variable

Unix/Mac

Windows

MAVEN_HOME

export MAVEN_HOME=/opt/maven/apache-maven-2.2.1

set MAVEN_HOME=C:\apache-maven-2.2.1

PATH

export PATH=$PATH:$MAVEN_HOME/bin

;C:\apache-maven-2.2.1\bin

(warning) Windows: append string to the end of the Path system variable

MAVEN_OPTS

Maven does not read JAVA_OPTS on start up, resulting occasionally in "Out of Memory" errors when building Sakai. To assure sufficient memory allocation during builds, you should add a MAVEN_OPTS environment variable as defined below. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set JAVA_HOME via the GUI.

export MAVEN_OPTS='-Xms512m -Xmx1024m -XX:PermSize=64m -XX:MaxPermSize=128m'

4.2 Create a local Maven repository

Create a local Maven repository (.m2) in your home directory:

Unix/Mac

cd $HOME
mkdir -p .m2/repository

Windows

mkdir %HOMEDRIVE%%HOMEPATH%\.M2\repository

(info) In Windows the default location of your home directory is C:\Documents and Settings\yourusername. Windows also establishes it through environment variables by combining your "home drive" location and your "home path" location, i.e. %HOMEDRIVE%%HOMEPATH%. (The %-sign is how Windows brackets environment variables).

4.3 Create a Maven settings.xml file

Create a new XML file in your .m2 directory called settings.xml. Add the following lines, specifying the actual location of your Tomcat home directory (in this example /opt/tomcat).

(minus) Do not include trailing / or \ slashes in the directory paths.
(warning) 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

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>/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>
<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 a <proxies> section to settings.xml:
<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>

(info) If you do not use a username or password for your proxy exclude the <username> and <password> elements. You only need the nonProxyHosts option if you have a local maven repo that does not require the proxy to be accessed. Maven 2.0 does not support Microsoft's NTLN authentification scheme. If you connect to a proxy like ISA you will need to use a tool such as http://ntlmaps.sourceforge.net/ to proxy your traffic.

5.0 Install Tomcat 5.5.33

(warning) Tomcat 5.5: we recommend Tomcat 5.5.33 in order to avoid certain Tomcat security vulnerabilities present in earlier releases.

(minus) Tomcat 6.0 / 7.0: Sakai 2.7 has not been tested in Tomcat 6.0 or 7.0 and will not run in either version of Tomcat without configuration changes. Adopters are advised to stay with the Tomcat 5.5. series.

(warning) JAVA_OPTS: running Sakai 2.x in Tomcat 5.5.27+ requires JAVA_OPTS modifications (see below).

(info) Sakai installations should always be accompanied by a fresh install of Tomcat. It provides a clean environment that simplifies troubleshooting if problems are encountered during the startup phase.

The Apache Tomcat servlet container provides an ideal environment for running Sakai as a web application. Tomcat implements both the Java Servlet and JavaServer Pages (JSP) specifications and can be run in standalone mode or in conjunction with a web application server such as the Apache HTTP server or JBoss. Sakai 2.7 works with the Tomcat 5.5 series.

Tomcat can be downloaded as a binary install from http://archive.apache.org/dist/tomcat/tomcat-5/

Choose the core distribution. Windows users have the option of downloading either a Windows Service Installer .exe or a binary *.zip archive. We recommend the *.zip archive over the installer because configuration and log viewing are easier. You can later convert the .zip install into a service install by running /bin/service.bat (see below for more details).

Unpack the Tomcat archive into your installation directory of choice, e.g. /opt/. Unix/Mac users should create a symbolic link (e.g., ln -s apache-tomcat-5.5.33) while Windows users should simply rename the base Tomcat directory to /tomcat to simplify the path.

Tomcat pathnames

Windows users should ensure that the Tomcat path includes no spaces as this causes errors with JavaServer Faces (JSF) tools in Sakai.

(thumbs up) Good: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\
(thumbs down) Bad: C:\program files\tomcat\, C:\opt\apache tomcat 5.5.33\

Tomcat permissions

Unix/Mac users should make sure that they have write permissions to the Tomcat servlet container files and directories before proceeding or startup permission errors may occur.

Tomcat JDK 1.4 Compatibility Package

(minus) Do not download and install the JDK 1.4 Compatibility Package. Sakai 2.7 will not run should you install it.

5.1 Set Tomcat environment variables

By convention, the base Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.31) is referred to as $CATALINA_HOME. As a convenience, you should create a $CATALINA_HOME environment variable. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set your Tomcat environment variables via the GUI.

Set the CATALINA_HOME environment variable to point to the base directory of your Tomcat installation and add the Tomcat /bin directory to your PATH variable:

Variable

Unix/Mac

Windows

CATALINA_HOME

export CATALINA_HOME=/opt/tomcat

CATALINA_HOME=C:\tomcat

PATH

export PATH=$PATH:$CATALINA_HOME/bin

;C:\tomcat\bin

(warning) Windows: append string to the end of the Path system variable.

5.2 Configure Tomcat

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

(warning) Neglecting this adjustment will force users 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.

5.3 Tomcat memory management

You can better manage Tomcat memory usage by creating a setenv.sh/.bat 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 -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: create a file called setenv.bat and add the following line:

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'

5.4 Set up Tomcat as a Windows service

You can convert the .zip install into a service install by running service.bat from the /bin directory:
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".

After this you need to set the default startup options:

C:\tomcat\bin> tomcat5 //US//Tomcat5 ++JvmOptions "-Xms512m;-Xmx1024m;-XX:PermSize=128m;-XX:MaxPermSize=256m;-Dfile.encoding=UTF-8; -Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false"

If you choose to do this in the GUI follow these steps: 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, you'll need to change the Java Virtual Machine path from ..\bin\client\jvm.dll to ..\bin\server\jvm.dll.

(minus) Java 1.6 users will you need add the system property -Dsun.lang.ClassLoader.allowArraySyntax=true. This option is not required for Java 1.5. Please see the Java section above or SAK-15874 for more details.

Be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI, e.g.:

-Xms512m
-Xmx1024m
-XX:PermSize=128m
-XX:MaxPermSize=256m
-Dfile.encoding=UTF-8
-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false
-Dsun.lang.ClassLoader.allowArraySyntax=true
-Dhttp.agent=Sakai

(warning) Samoo has reported that display issues after editing text documents with accented characters using the resources tool. The issue was resolved by adding -Dfile.encoding=UTF-8 as a Java option (open command window -> type "tomcat5w" -> "Java" ->"Java Options:").

You can add additional system properties if needed, e.g., -Dsakai.security=C:\tomcat\security.

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.

(warning) Java 1.6 users may encounter the unhelpful system log error "The Apache Tomcat service terminated with service-specific error 0 (0x0)". This can be fixed by copying the file msvcr71.dll from the /bin directory into the server or client directory with the jvm.dll file.

To set up remote debugging, please see (Remote Debugging).

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

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

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.

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

7.0 Build, deploy and start up Sakai in Tomcat

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

7.1 Start/Stop Tomcat

Start/stop Tomcat from the terminal by running the appropriate startup/shutdown script located in $CATALINA_HOME/bin:

Unix/Mac

sh startup.sh
sh shutdown.sh

Windows

startup.bat
shutdown.bat

8.0 Explore Sakai

You should at this point have a working Sakai installation. Now it's time to get started with adding users, creating work sites, and otherwise playing around with the tools. We won't try to present a full user's guide here, but we can offer some pointers to get you oriented and on your way, and link you to more exhaustive sources of information elsewhere.

The Gateway Page

Once Tomcat has started successfully, you should be able to direct your browser to its gateway page at http://localhost:8080/portal (or replace 'localhost' with the name of the server where it's installed). From the gateway page you can create new accounts or browse for public site content. You could start by creating a new account, but that can also be done as an admin, and since the admin functions are needed to allow this account the right permissions, it's just as well to start by logging in as the admin user. Sakai's out-of-the-box admin account is simply named 'admin' (with password also 'admin'), so use those credentials to log in.

My Workspace

Every user on the system - including the admin - has a private site called My Workspace. It's the landing point upon logging in, and it's the first site tab visible at the upper left. Running vertically along the left-hand side of the screen are links to the various different tool pages within a given site, and the admin's My Workspace has a different set of such options here than most (each different type of account can be configured to have a different set of tools in its My Workspace by altering a template - see below).

Other Sites

Each new (accessible) site becomes visible as a tab along the top, to the right of My Workspace. For most users, they initially only have access to one site - their My Workspace. The admin user is a little different, in that it has access to two. The second admin site (which you can enter by clicking on its tab) is entitled Administration Workspace which, strangely enough, looks exactly the same as the admin My Workspace. It is.

Why the redundancy? Because you'll likely want to make these admin tools available to a particular user who doesn't have access to the admin's My Workspace (no one has access to other people's My Workspace on the system). To allow anyone access to the admin tools, you need only add them to the list of users of the Administration Workspace, and then promote them in the site to the "admin" role.

Admin Tools

Creating Users

The first thing you may want to do is to change the admin password to something secure, and to start creating a few sample users on your system. You can do both of those tasks through the Users tool on the left. To change the admin user's password, simply click on the 'admin' username in the list of users, and edit the fields on the subsequent page. To create users, click on the New User action link at the top of the tool page.

Creating Sites

If you're itching to create your first worksite, you may be tempted to dive directly into the Sites tool. That would probably be a mistake. The Sites tool is a powerful way to construct an entire site from the ground up, with fine-grained control over its every page, tool, and configuration detail. But this flexible power comes with a price, making for an intimidating interface and epic-scale workflow. The Sites tool is therefore best used as a way to tweak an existing site after the fact, once the standard pieces have been more expediently assembled.

The best way to start creating sites, therefore, is to use the Worksite Setup tool. Click on the New link at the top of the tool page, and then, for simplicity's sake, choose the Project site type, which will allow you to avoid issues of academic term, etc., that are provoked by a "course" site - issues which are probably unnecessary if you just want to start playing with the tools. Either type of site will serve, however: both types of sites have all the tools available to them.

Step through the remaining site creation pages, making your preferred selections. Be sure to click the Create Site button at the end of the process. After doing so, you should see the site title visible as a new tab along the top of the screen.

Adding Users to Sites

Since you set this site up as an admin, the admin is technically the owner of this site, and its only member at first. If you want to add other sample users to this site in different roles, you can do so through the Site Info tool of the site itself.

Click on the tab of your new site (which should now be visible) to enter it, and then click on the Site Info link along the left hand side. Site Info has a number of site maintainer functions available as action links across the top, and Add Participants is the one that will allow you to connect other users to the site. These users will of course need to have been previously created.

As long as we're here in Site Info, it's worth pointing out that the Edit Tools link at the top will allow you to remove and add tools from the site.

Experimenting with Tools

You may have noticed an extra tool appear in your site - one which you didn't explicitly choose - labeled Help. This tool provides online documentation of the various bundle tools, and other facets of the system. This should be your companion as you learn more about the software's functionality.

This Help tool is also reached in a context-sensitive way by clicking on the question mark icons at the upper right of any particular tool frame. Clicking on those question marks will open up the precise content of the tool you happen to be in at the time.

At some later point, when you become comfortable with the standard tools, you may wish to see other, more experimental tools that are available for Sakai. The Sakai distribution includes provisional tools that are still maturing, but can already serve needs in innovative ways that the standard ones do not. These extra tools require additional steps to enable, so that system users will not stumble across them inadvertently if that's not desired, but you are encouraged to evaluate them for your own deployment.

Where to Learn More

About the Project

The sakaiproject.org site offers the best background and orientation to the project and its goals, but chances are you've already seen it. For more particular information on the progress and roadmaps of certain tools or other initiatives, see the relevant Confluence spaces.

Community Participation

The Sakai Community provide email forums on a variety of topics. The lists are open, however, they do reject all non-member email, so you need to join a list before you can post to it, though you can still access its archives.

The four main Sakai community lists are:

Announcements (announcements@apereo.org) - items of community-wide interest in Apereo, including Sakai (receive newsletters; learn about conferences and deadlines; follow general progress on upcoming releases; participate in calls for community input). A low-volume, read-only list, which everyone should join.

Building Sakai (sakai-dev@collab.sakaiproject.org) - designing, developing, testing, and documenting Sakai (learn about the technical details of building tools or integrating services; find guidelines for design and development of tools and services; locate technical specifications; learn about plans for future releases). For designers, programmers, developers, and quality assurance.

Pedagogy (pedagogy@collab.sakaiproject.org) - teaching and learning, collaboration, and other uses of Sakai (learn about best practices; share experiences; connect with user communities with similar interests, K-12, Higher-Ed, Portfolios). For teachers, staff, students, researchers, instructional designers, instructional technologists and end-user support staff.

Deploying Sakai (production@collab.sakaiproject.org) - implementing, installing, configuring, and supporting Sakai (find release documentation; learn about performance tuning; browse suggested hardware and software configurations; share examples of training, tutorial and support materials). For sysadmins, DBAs, and technical support staff.

There are also a variety of smaller, topic-specific working groups that use email lists, which you may also find of interest as you get more involved with the community.

To join a Sakai mailing list point your browser to:

http://collab.sakaiproject.org/mailman/listinfo/

and join the lists that interest you. You will be asked to fill out a short form (username, password) and you can select whether or not to receive each list post individually (default) or batched in a daily digest. Once you have submitted your request you will be sent a confirmation email with a short set of instructions for confirming your subscription request.

About Technical Matters

Reference materials for various technical issues are best found in Sakai's subversion repository (where these installation documents are also stored) or in the project's Confluence wiki. The docs in subversion can be found in the reference module, e.g. https://source.sakaiproject.org/svn/reference. See in particular the docs/architecture folder contained there, which contains a wide-ranging collection of technical white papers.

The Confluence wiki is a more informal source of information, but also valuable and broader in scope. New developers in particular should visit the Programmer's Cafe. You are encouraged to create an account there and participate.

But often the most incisive information comes from direct interaction with your peers. As mentioned above, the Collab Server is the place to go for this. For technical questions the best (and most active) such group is DG: Development, also commonly referred to by its alias, "sakai-dev."

Unknown macro: {cloak}

 

Upgrading

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

 

Configuring

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

 

New properties, permissions

Release

Tool/Service

Property

Default

Ticket

Change

2.7.1

Archive

archive.toolproperties.excludefilter

password|secret

SAK-18965 - Getting issue details... STATUS

Filter properties when performing a site export in order to exclude properties with the string 'secret' or 'password' in the resulting site.xml file.

2.7.1

Help

help.hide

sakai.profile

SAK-18627 - Getting issue details... STATUS

Hide the help collection for the legacy Profile tool.

2.7.1

Portal

portal.error.showdetail

true

SAK-18585 - Getting issue details... STATUS

Certain institutions consider Sakai error messages overly verbose, revealing technical information that is not relevant to the user (e.g., stack traces, SQL error messages, etc.). You can limit such disclosures by setting portal.error.showdetail to false.

2.7.0

BasicLTI

basiclti.consumer_instance_guid

 

 

Site-wide identifier, e.g., ctools.umich.edu

2.7.0

BasicLTI

basiclti.consumer_instance_name

 

 

Site-wide name, e.g., CTOOLs At University of Michigan

2.7.0

BasicLTI

basiclti.consumer_instance_url

 

 

Site-wide URL, e.g., http://ctools.umich.edu

2.7.0

BasicLTI

basiclti.consumer_instance_key.[hostname]

 

 

LMS-wide key, e.g., basiclti.consumer_instance_key.imsglobal.org=lmsng.school.edu

2.7.0

BasicLTI

basiclti.consumer_instance_secret.[hostname]

 

 

LMS-wide secret, e.g., basiclti.consumer_instance_secret.imsglobal.org=secret.

2.7.0

BasicLTI

sakai.testlti.launch

 

 

Suppress portlet form field with supplied launch end-point URL.

2.7.0

BasicLTI

sakai.testlti.key

 

 

Suppress portlet form field with supplied key.

2.7.0

BasicLTI

sakai.testlti.secret

 

 

Suppress portlet form field with supplied secret.

2.7.0

BasicLTI

basiclti.provider.enabled

false

 

Enable BasicLTI producer.

2.7.0

BasicLTI

webservices.allow=.+

 

 

Set the values for the IP address and/or domain addresses from which requests will be accepted.

2.7.0

BasicLTI

basiclti.provider.allowedtools

 

 

List of Sakai tools that can serve as providers (partial list), e.g., sakai.announcements:sakai.assignment.grades:sakai.forums:sakai.gradebook.tool:sakai.resources:sakai.schedule:sakai.samigo:sakai.rwiki

2.7.0

BasicLTI

basiclti.provider.[hostname].secret

 

 

Provide a secret for a given "key", e.g., basiclti.provider.lmsng.school.edu.secret=secret.

2.7.0

BasicLTI

basiclti.provider.highly.trusted.consumers

 

 

Permit clean pass through of site/user credentials for a list of trusted consumers, e.g., basiclti.provider.highly.trusted.consumers=lmsng.school.edu:another.school.edu.

2.7.0

DbContentService

content.filesizeColumnReady

false

KNL-427 - Getting issue details... STATUS , SAK-18455 - Getting issue details... STATUS

Default value changed from true to eliminate performance issue affecting Sakai on start up. Of particular relevance if upgrading from Sakai 2.3 or earlier.

2.7.0

Content

content.html.forcedownload

true

SAK-18540 - Getting issue details... STATUS

Force browser to download rather than render inline any file served from content hosting with a content-type of text/html.

2.7.0

Profile2

profile2.picture.max

2

 

Upload limit for profile pictures in MB.

2.7.0

Profile2

profile2.convert

false

 

Convert images from old profile to new (true/false).

2.7.0

Profile2

profile2.integration.twitter.enabled

true

 

Allow users to post status updates to Twitter.

2.7.0

Profile2

profile2.integration.twitter.source

Profile2

 

Source listed for Twitter status updates.

2.7.0

Profile2

profile2.picture.change.enabled

true

 

Allow users to change their profile picture.

2.7.0

Profile2

profile2.picture.type

upload

 

Can users upload an image or just link to an existing one (upload/url).

2.7.0

Profile2

profile2.privacy.change.enabled

true

 

Allow users to change their privacy settings.

2.7.0

Profile2

profile2.privacy.default.profileImage

0

 

0=everyone, 1=only connections.

2.7.0

Profile2

profile2.privacy.default.basicInfo

0

 

0=everyone, 1=only connections, 2=only me.

2.7.0

Profile2

profile2.privacy.default.contactInfo

0

 

0=everyone, 1=only connections, 2=only me.

2.7.0

Profile2

profile2.privacy.default.academicInfo

0

 

0=everyone, 1=only connections, 2=only me.

2.7.0

Profile2

profile2.privacy.default.personalInfo

0

 

0=everyone, 1=only connections, 2=only me.

2.7.0

Profile2

profile2.privacy.default.birthYear

true

 

 

2.7.0

Profile2

profile2.privacy.default.search

0

 

0=everyone, 1=only connections.

2.7.0

Profile2

profile2.privacy.default.myFriends

0

 

0=everyone, 1=only connections, 2=only me.

2.7.0

Profile2

profile2.privacy.default.myStatus

0

 

0=everyone, 1=only connections.

2.7.0

Profile2

profile.manager.integration.bean

see note

SAK-17573 - Getting issue details... STATUS

Instruct ProfileManager to get it's data from Profile2. Default=org.sakaiproject.profile2.legacy.ProfileManager. If not set tools such as the Roster will use the LegacyProfileManager to provide data.

2.7.0

Profile2

profile2.invisible.users

postmaster

 

Comma separated list of userIds (not eids) that will never show in searches or friends lists.

2.7.0

Sites

site.templates

 

SAK-16419 - Getting issue details... STATUS

In 2.6.0 a feature was implemented to allow existing sites to serve as site templates. This was handled by adding the property site.templates and specifying a comma-delimited list of existing sites chosen to serve as templates. For 2.7.0 this property has been eliminated. Instead, the Sites tool must now be used to add the property template with a value equal to true for sites chosen to serve as site templates. Additionally, sites previously designated as site templates must be re-flagged using the Sites tool. In a future release there is a plan to add a checkbox indicating that a site is serving as a template.

9.0 New/changed permissions

Release

Tool/Service

Permission

Notes

2.7.0

Portfolios

osp.matrix.scaffolding.delete.any

replaces osp.matrix.scaffolding.delete

2.7.0

Portfolios

osp.matrix.scaffolding.delete.own

new

2.7.0

Portfolios

osp.matrix.scaffolding.export.any

replaces osp.matrix.scaffolding.export

2.7.0

Portfolios

osp.matrix.scaffolding.export.own

new

2.7.0

Portfolios

osp.matrix.scaffolding.publish.any

replaces osp.matrix.scaffolding.publish

2.7.0

Portfolios

osp.matrix.scaffolding.publish.own

new

2.7.0

Portfolios

osp.matrix.scaffolding.revise.any

replaces osp.matrix.scaffolding.edit

2.7.0

Portfolios

osp.matrix.scaffolding.revise.own

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.accessAll

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.accessUserList

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.manageStatus

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.use

replaces osp.matrix.scaffolding.use

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.viewAllGroups

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.viewEvalOther

new

2.7.0

Portfolios

osp.matrix.scaffoldingSpecific.viewFeedbackOther

new

2.7.0

Portfolios

osp.portfolio.evaluation.use

replaces osp.matrix.evaluate

2.7.0

Portfolios

osp.presentation.review

replaces osp.matrix.review

2.7.0

Sitestats

sitestats.admin.view

new

2.7.0

Sitestats

sitestats.view

new

 

Database support

The Sakai CLE supports the following production-grade databases:

Database

Driver

Notes

MySQL 5.1.x

MySQL Connector/J 5.1.13+

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

MySQL 5.0.x

MySQL Connector/J 5.0.4+

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

Oracle 11g

OJDBC

(warning) 2.7 was not tested using Oracle 11g; however, both Virgina Tech and the University of Florida are using Oracle 11g with their Sakai deployments.
(warning) Oracle recommends using the latest 11g driver if you are using Java 6 with either 10g or 11g; with Java 6 in combination with the 11g driver, it's recommended that you use kernel-1.2.1+ (2.8), kernel-1.1.11+ (2.7) or kernel-1.0.x (r87324+) in order to include the fix for KNL-637.

Oracle 10g / 9i

OJDBC

(warning) Both Oracle 10g AND 9i users must use the 10g driver; the latest 10g "Release 2" (10.2.x) or higher is recommended.
(warning) Oracle recommends using the latest 11g driver if you are using Java 6 with either 10g or 11g; with Java 6 in combination with the 11g driver, it's recommended that you use kernel-1.2.1+ (2.8), kernel-1.1.11+ (2.7) or kernel-1.0.x (r87324+) in order to include the fix for KNL-637.

DB2

 

Deprecated

Choose the appropriate MySQL or Oracle JDBC driver (or connector) for your installation. 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 Oracle download the ojdbc14.jar file and copy it to $CATALINA_HOME/common/lib.

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

In actuality, Sakai is not limited to these database choices and integration with other RDBMS systems is not difficult. In the past at least one installation used Microsoft SQL Server while requests for PostgreSQL integration are occasionally raised on the Sakai developers list. However, to date no one in the Sakai Community has stepped forward to support alternatives to either Oracle or MySQL, a prerequisite for adding additional database options to the release.

(minus) 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 database 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.

1.0 Configure the database

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 in sakai.properties:

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

2.0 Set the database username and password

Set 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

3.0 Set the database connection

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=
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

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.Oracle9iDialect
hibernate.dialect=org.hibernate.dialect.Oracle10gDialect
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

(warning) Oracle users may experience performance issues with certain of the SQL settings that work for 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

4.0 Set auto.ddl=true

(info) On startup, Sakai will generate all database objects (tables, keys, constraints, etc.) automatically, obviating the need to run DDL scripts manually per the sakai.properties setting auto.ddl.
# establish auto.ddl - on by default
auto.ddl=true
#auto.ddl=false

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

5.0 Install MySQL 5.1 / 5.0

Configuring the Sakai CLE to use MySQL is an excellent option both for local development and production purposes.

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

(warning) Users upgrading from MySQL 5.0 to MySQL 5.1 on a Mac have reported name comparison problems on startup (for more info see http://collab.sakaiproject.org/pipermail/sakai-dev/2010-June/008066.html. This issue is solved by specifying the following property in a local my.cnf configuration file:

lower_case_table_names=1

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

(info) Case sensitivity. In most varieties of UNIX, MySQL is case sensitive since the underlying operating system determines the case sensitivity of database and table names. This is not the case for MySQL running in Windows which is case insensitive. Previous MySQL conversion scripts contained a mixture of upper case and lower case statements which occasionally caused problems for upgraders; for 2.8 we opted for lower case for the syntax while leaving the table and field names upper case. Testing on MySQL 5.1 did not reveal any issues with this choice.

Before installing MySQL, confirm whether or not it is already installed on your system by checking the version from the command line:

mysql --version
mysql  Ver 14.14 Distrib 5.1.52, for apple-darwin10.3.0 (i386) using readline 5.1

If MySQL is not installed download MySQL 5.1/5.5 binaries or source from http://dev.mysql.com/downloads/. Linux users should install MySQL using a package or binaries if possible. Choose the standard configuration. Windows users should consider installing MySQL as a service. Remember to include MySQL's /bin directory in your PATH statement.

MySQL 5.5: http://dev.mysql.com/downloads/mysql/5.5.html

MySQL 5.1: http://dev.mysql.com/downloads/mysql/5.1.html

Assign a password for the root account:

mysql -u root -pmysqlpassword
5.1 Set MySQL environment variables
MYSQL_HOME

Set the MYSQL_HOME environment variable to point to the base directory of your MySQL installation. In the example below, the path points to a symbolic link file rather than the actual MySQL installation directory. You can create a symbolic link ("sym link") in Unix using the ln -s command (e.g., ln -s mysql-5.1.46-osx10.6-x86_64 mysql).

Unix/Mac:

export MYSQL_HOME=/usr/local/mysql

Windows:

set MYSQL_HOME=C:\mysql
PATH

Add MySQL's /bin directory to your PATH variable.

Unix/Mac:

export PATH=$PATH:$CATALINA_HOME/bin:$JAVA_HOME/bin:$M2_HOME/bin:$MYSQL_HOME/bin:$PHP_HOME/bin:$SUBVERSION_HOME/bin:$USR_LOCAL/bin

Windows:

;C:\mysql\bin
5.2 Create a my.cnf/my.ini configuration file
You can configure MySQL to read a wide variety of startup options from a file named my.cnf. Settings are scoped and can be overridden by file location:

Scope

Location

Override

global

/etc/my.cnf

 

server-specific

binary install: /usr/local/mysql/data/my.cnf; source install: /usr/local/var/my.cnf

global

user

~/my.cnf

global, server-specific

Below is a minimalist MySQL 5.1 configuration file for a development laptop /etc/my.cnf:

[mysqld]
default-storage-engine=InnoDB
lower_case_table_names=1

(warning) Restart MySQL in order for the new settings to take effect.

5.3 Create a "sakai" database and user account
Unable to render {include} The included page could not be found.

 

Deprecations, removals

Release

Capability

Status

Notes

2.7.0

Blogger

stealthed

Deprecated and scheduled for removal as of 2.8.0 release.

2.7.0

Mailtool

retired

Removed as of 2.7.0 release.

2.7.0

Presentation

retired

Removed as of 2.7.0 release.

2.7.0

Reports

stealthed

Deprecated and scheduled for removal as of 2.8.0 release.

2.7.0

Sample

retired

Removed as of 2.7.0 release.

2.7.0

Warehouse

OSP dependency

Deprecated and scheduled for removal by portfolio team as of 2.8.0 release.

 

Known issues

Release

Tool/Service

Ticket

Fixed

Issue

2.7.1

Assignments

SAK-18606 - Getting issue details... STATUS

 

A fix for this issue introduced a mismatch between the instructor and student view - the instructor sees text as rich text while the student sees it as plain text with escaped markup.

2.7.1

profile-1.3.11

PRFL-425 - Getting issue details... STATUS

profile-1.3.12

ProfileImageServiceImpl includes a recursive method call that can result in a StackOverflowError error. Normal operation of the tool is largely unaffected but errors can result if users view images via in the roster. This bug has been addressed in the profile-1.3.12 release.

2.7.1

Site Info

SAK-18878 - Getting issue details... STATUS

2.7.x

SiteTextEditUtil calls {{processFormattedText}] incorrectly, resulting in plain text being treated as processed text which, under certain conditions, will result in a runtime exception.

2.7.0

Blogger

SAK-18625 - Getting issue details... STATUS

 

Blogger is deprecated and stealthed in 2.7. If you need to adjust its permissions use the Admin realms tool.

2.7.0

Blogger, Chat, Portfolios, Samigo

SAK-17578 - Getting issue details... STATUS , SAM-639 - Getting issue details... STATUS

 

Although Java SE 6 is the recommended JVM for Sakai 2.7.0, a number of tools fail to compile. The workaround is to add -Dsun.lang.ClassLoader.allowArraySyntax=true to JAVA_OPTS.

2.7.0

Calendar

SAK-3824 - Getting issue details... STATUS

 

Calendar templates make assumptions about date formats which do not always match localized formats.

2.7.0

Dropbox

SAK-18443 - Getting issue details... STATUS

 

Silent failure on drop box email notification setting.

2.7.0

Drop box, Resources, WebDAV

SAK-17980 - Getting issue details... STATUS

 

Inconsistent handling of UTF-8 special characters have been reported for these tools.

2.7.0

FckEditor

SAK-18556 - Getting issue details... STATUS

 

FCKEditor only allows _blank for target attributes on links.

2.7.0

kernel-1.1.8

KNL-460 - Getting issue details... STATUS

 

The kernel generates unnecessary warning messages in the logs during start up.

2.7.0

Maven

SAK-18655 - Getting issue details... STATUS

 

It has been reported that running mvn -Ppack-demo install fails for Windows Vista.

2.7.0

msgcntr-2.7.0

MSGCNTR-315 - Getting issue details... STATUS

 

Attempts to read a locked topic message previously unread by the user will generate a run time error.

2.7.0

msgcntr-2.7.0

SAK-18510 - Getting issue details... STATUS

 

MySQL indexes are not auto generated (auto.ddl=true) due to Hibernate 3.2.7ga bug.

2.7.0

Portal static files

SAK-14938 - Getting issue details... STATUS

2.7.1

Static HTML files (locations for which may be configured in sakai.properties) do not respond to dynamic language preferences.

2.7.0

profile2-1.3.8

SAK-18510 - Getting issue details... STATUS

 

MySQL indexes are not auto generated (auto.ddl=true) due to Hibernate 3.2.7ga bug.

2.7.0

Roster

SAK-15719 - Getting issue details... STATUS

 

There exists currently a permission asymmetry between roster.viewallmembers and site.upd. A user lacking site.upd may still be granted roster.viewallmembers permission. In such cases, certain form fields such as the group filter drop down are not rendered for the user.

2.7.0

Portfolios

SAK-18568 - Getting issue details... STATUS

2.7.1

Popup tools with spaces or apostrophes do not work in Internet Explorer when using the xsl-portal.

2.7.0

Portfolios

SAK-18011 - Getting issue details... STATUS

2.7.1

Page titles do not support special characters.

2.7.0

Profile

SAK-18563 - Getting issue details... STATUS

2.7.1

The Profile tool does not work for the given user when /> is inputted for number of tabs in the customize tabs option when portal.use.dhtml.more=true is set in sakai.properties.

2.7.0

Samigo

SAK-11261 - Getting issue details... STATUS

 

Date and time format not localized.

2.7.0

Site Info

SAK-18634 - Getting issue details... STATUS

2.7.1

IMS-CC package import results in a run time error.

2.7.0

sitestats-2.1.4

SAK-18510 - Getting issue details... STATUS

 

MySQL indexes are not auto generated (auto.ddl=true) due to Hibernate 3.2.7ga bug.

2.7.0

Worksite Setup

SAK-18613 - Getting issue details... STATUS

2.7.1

If you hook your new course site up to more than one Course Management entity (e.g., to the course offering and to all its sections), then site-manage leaves the "Site Title" required field blank.

2.7.0

Kernel

SAK-19707 - Getting issue details... STATUS

Requires manual database script

The Sakai 2.7 Release includes a new feature that supports dynamic localization
of page and tool titles. To accomodate "custom titles" that should not be translated, a new "sitePage.customTitle" property has been introduced to the definition of pages.

In order to avoid losing any custom page/tool title changes made in previous releases, the following zip file should be unpacked and the enclosed perl script must be run.

   https://jira.sakaiproject.org/secure/attachment/24199/custom-title-patch.zip

This script will generate SQL that sets the custom page title flag for specified tools that have locale-specific custom tool title names. This script will only need to be run once. Future page/tool title customizations will persist.

 

Security policy

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

Older Releases

The Sakai CLE 2.6 series is now unsupported. The release of Sakai CLE 2.8.0 in April 2011 marked the end of official community support for the Sakai 2.6 series. Organizations running Sakai CLE 2.6 (or earlier versions) are strongly encouraged to upgrade to the latest versions of Sakai CLE 2.7 or 2.8 in order to take advantage of continued maintenance support.

License

The Sakai CLE 2.7 series is licensed under the Educational Community License version 2.0.

  • No labels