Skip to end of metadata
Go to start of metadata

Sakai Source Distribution Installation Guide

1.0 Verify/Install Java 5.0

Sun Microsystem's Java 2 Platform Standard Edition 5.0 (J2SE 5.0), a.k.a Java 1.5, is required to build and run Sakai. Certain files, such as *.jsp and *.jws, require compilation so downloading and attempting to use only the runtime environment (JRE 5.0) will not suffice.  Mac OS X includes the full version of Java J2SE 5.0, pre-installed with the Java Development Kit (JDK) and the HotSpot virtual machine (VM), so Mac users should not need to install Java.  If you find Sun's version and naming conventions confusing, see Sun Java SE Naming and Versions for an outline of their practices.

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

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

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

$ java -version

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

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

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

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

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

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

1.1 Set Java environment variables

Java requires two environment variables be set for optimal operation. For UNIX operating systems one typically modifies a startup file like ~/.bash_login to set and export shell variables while Mac users typically set and export environment variables in .bash_profile. For Windows, go to Start -> Control Panel -> System -> Advanced -> Environment Variables and set JAVA_HOME via the GUI (samples below).

JAVA_HOME

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

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

(info) If your machine has already set the variable JRE_HOME or if you want to use a particular JRE if you have more than one JRE installed on your machine then you'll want to set the JRE_HOME variable as well. JRE_HOME is what Apache Tomcat uses when it starts up, but it defaults to use JAVA_HOME if JRE_HOME is not set. In most cases, setting JAVA_HOME should cover both cases sufficiently.

PATH

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

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

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

$ set

[excerpt]

JAVA_HOME=/Library/Java/Home
...
PATH=/Library/Java/Home/bin [etc]
....

1.2 Tune the JVM

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

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

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

JAVA_OPTS="-server -XX:+UseParallelGC -Xmx876m -XX:MaxPermSize=2160m -Djava.awt.headless=true"

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

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

1.3 Add an HTTP Proxy (if required)

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

2.0 Install Tomcat 5.5.26+

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.5.0 was tested using Apache Tomcat 5.5.23 although the latest stable release of Tomcat 5.5 should present no compatibility issues. You can learn more about Tomcat by visiting http://tomcat.apache.org/.

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

Download and Install Tomcat

Tomcat and Sakai 2.5 releases

Sakai

Tomcat (tested against)

Tomcat (also works with)

Tomcat (avoid)

2.5.0

5.5.23

5.5.25

5.5.26 (known incompatibilities)

2.5.2

5.5.26

5.5.27 ((warning) requires JAVA_OPTS modification)

2.5.3

5.5.26

5.5.27 ((warning) requires JAVA_OPTS modification)

2.5.4

5.5.26

5.5.27 ((warning) requires JAVA_OPTS modification)

Tomcat 5.5.27

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

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

Getting Tomcat

Tomcat can be downloaded as a binary install from

http://archive.apache.org/dist/tomcat/tomcat-5/

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

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

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

Tomcat 2.5.2+

ln -s apache-tomcat-5.5.26 tomcat

Tomcat 2.5.0

ln -s apache-tomcat-5.5.23 tomcat

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

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

2.1 Set Tomcat environment variables

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

CATALINA_HOME

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

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

PATH

Add the Tomcat /bin directory to your PATH variable:

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

2.2 Configure Tomcat

Sakai supports UTF-8 allowing for non-Roman characters, but this requires that Tomcat be configured to accept UTF-8 URLs since it ships with ISO-8859-1 as the default URL encoding. To change this setting, edit $CATALINA_HOME/conf/server.xml. Add the attribute URIEncoding="UTF-8" to the <connector> element. For example:
<Connector port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100" debug="0"
connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>

If you want to run Tomcat on different ports than the defaults, this would also be a good time to make those changes in the server.xml file. See Tomcat configuration documentation for more details.

If you plan to run Tomcat as a standalone web server as opposed to running it in conjunction with the Apache HTTP server then you will want to make a further minor change that may spare some confusion later. The ROOT webapp is the one served up when a request is made to Tomcat's root URL. If you want users to be re-directed automatically to the Sakai application, you must insert an index.html file into /webapps/ROOT that prompts this re-direction. The index.html file should look something like the following:

<html>
<head>
<title>Redirecting to /portal</title>
<meta http-equiv="Refresh" content="0:URL=/portal">
</head>
<body bgcolor="#ffffff" onLoad="javascript:window.location='/portal';">
<div style="margin:18px;width:288px;background-color:#cccc99;padding:18px;border:thin solid #666600;text-align:justify">
<p style="margin-top:0px">
You are being redirected to the Sakai portal.  If you are not automatically redirected, use the link below to continue:<br/>
<a href="/portal">Take me to the Sakai portal</a>
</p>
</body>
</html>

If you don't make this change you (and your users) will need to append /portal to the URL entered to access Sakai each time. If you intend to connect Tomcat with Apache HTTP server you can configure redirections from within Apache, an option that lies outside the scope of this document.

2.3 Tomcat memory settings

You can better manage Tomcat memory usage by creating a SETENV file defining JAVA_OPTS environment variable settings in the tomcat/bin directory.

Mac/Unix: create a file called setenv.sh and add the following line:

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

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

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

2.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, e.g.
C:\tomcat\bin> service.bat install

You can add a service name as a second argument to the above script (the default name is "Tomcat5"). You can uninstall the service by replacing "install" with "remove".

To open the configuration window, issue the following command:

C:\tomcat\bin> tomcat5w //ES//Tomcat5

Replace "Tomcat5" with whatever service name you chose for the install. You'll want to set the service to startup automatically ("Startup Type" under the General tab).

(info) Windows users that have installed Tomcat as a service can set most Java options through the Tomcat service manager GUI, but not all of them are as straightforward as inclusion in a single environment variable. To achieve the equivalent of the "-server" option, for example, you'll need to change the Java Virtual Machine path from ..\bin\client\jvm.dll to ..\bin\server\jvm.dll. Then be sure to put the remaining JAVA_OPTS on separate lines in the Java Options field of the GUI. e.g.:

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

Finally, clear out the Initial Memory Pool and Maximum Memory Pool values, as those might conflict with the options you're putting in the Java Options field. Then click Apply, restart the service, and double-check the service manager to verify that the values have changed.

3.0 Install Maven 2.0.6+

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

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

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

Download and Install Maven

(tick) For Sakai 2.5 we have upgraded our build process from Maven 1.0 to Maven 2.0.6+.

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

To confirm that you can start Maven, run the command mvn --version. This should start maven and cause it to report its version. At this point your environment is prepared to build and deploy the Sakai source code.

mvn --version

3.1 Set Maven Environment Variables

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

MAVEN_HOME

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

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

PATH

Add the Maven /bin directory to your PATH variable:

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

MAVEN_OPTS

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

export MAVEN_OPTS='-Xms256m -Xmx512m -XX:PermSize=64m -XX:MaxPermSize=128m'

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

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

Optionally, you can specify the Tomcat home to be an environment variable:

Users who utilize a network proxy need to add the following to their file:

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

4.0 Install the Sakai source distribution

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

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

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

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

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

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

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

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

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

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

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

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

2-5-x Maintenance Branch

The latest bug fixes for a particular release can be found in our maintenance branches. Please note that certain maintenance branch fixes require database schema changes; see the Sakai Confluence Wiki 2-5-x branch summary for more information.

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

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

Post-Release 2.5 Branches

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

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 can be read using the load method of java.util.properties. Settings in sakai.properties govern everything from setting your institution name to configuring your database. All settings in sakai.properties are only read on startup; thus any changes you make will only take effect when you restart Tomcat.

The default sakai.properties file is located in the Components API project module:

sakai-src/component/component-api/component/src/config/org/sakaiproject/config/sakai.properties

A sample sakai.properties file which documents many of the standard properties can be found in the Reference module:

sakai-src/reference/docs/sakai.properties

To override the defaults you can create your own sakai.properties file either from scratch or from a known working copy. New key/value settings can be added to the sakai.properties. Since any component property can in principle be overridden here, any sample sakai.properties will show only a small fraction of all the possible settings.

(warning) If you checkout a copy of sakai.properties from our SVN repository make sure it corresponds to the version of Sakai you are using (e.g. Sakai 2.5.x):

$ svn co http://source.sakaiproject.org/svn/reference/branches/sakai_2-5-x/docs/sakai.properties
If you create your own sakai.properties file the standard place to locate it is $CATALINA_HOME/sakai. This directory is not created by Maven during the build and deployment process, so you will have to create it manually.

(info) You may find it preferable to store Sakai's configuration files outside of the Tomcat file hierarchy. In a development environment, for example, you may find yourself frequently reinstalling Tomcat and unless you create a build script to automate the Tomcat installation and configuration process you will likely want to avoid having to recreate the $CATALINA_HOME/sakai folder and its property file contents each time.

To locate your properties file outside of Tomcat 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 Tomcat.

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

4.2 Database default configuration

By default all Sakai distributions (demo, binary, source) are configured to use an in-memory version of HSQLDB on start up. HSQLDB is adequate for testing or local development but does not offer the same reliability and scalability as a more robust relational database. 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.

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

4.3 Build and deploy Sakai

Sakai makes use of Maven's Project Object Model to provide an XML representation of basic project information covering dependency management, build targets, external repositories, issue tracking, mailing lists, reporting plugins, developer bios, etc. A top-level master pom.xml file located in the /master project acts as a parent for other pom.xml files included in other Sakai project modules. If you are building Sakai for the first time you should build the master POM first before attempting to build and deploy Sakai as whole. Issue the Maven clean and install goals from the /master project folder to build and install the master POM:
cd master
mvn clean install
cd ..
Once you have built the master POM, issue the following Maven goals from the sakai-src directory or from the folder containing the Sakai modules downloaded from our SVN code repository:
$ mvn clean install sakai:deploy -Dmaven.tomcat.home=/pathto/tomcathome

(info) -Dmaven.tomcat.home specifies Tomcat's location and can be omitted if Tomcat home is specified in Maven's settings.xml file.

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

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

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

Build and Deploy Sakai in Offline Mode

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

mvn -o clean install sakai:deploy

Build and Deploy the Sakai "Framework"

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

mvn -Pframework clean install sakai:deploy

Build and Deploy Sakai "Mini"

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

mvn -Pmini clean install sakai:deploy

Skip Unit Tests when Building and Deploying Sakai

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

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

4.4 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

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

User information has yet to be fully consolidated. Attempts are underway to gather and present this information in a more uniform way but in the interim a tourist's guide of the landmarks may be in order.

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 Confluence space named Management/Project Coordination. That coordinating page will also link you out to Confluence spaces for particular tools, and documentation about them.

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@collab.sakaiproject.org) - items of community-wide interest in Sakai (receive newsletter every two weeks; learn about conferences and deadlines; follow general progress on upcoming releases; partipipate 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.

Using Sakai (sakai-user@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 vareity 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."

  • No labels

11 Comments

  1. Should Oracle connection section be amended to conform to the the following log entry in catalina.out? Best.

    WARN: The Oracle9Dialect dialect has been deprecated; use either Oracle9iDialect or Oracle10gDialect instead (2008-02-08 09:01:01,642 main_org.hibernate.dialect.Oracle9Dialect)

  2. Is there any goal for undeploy ?like mvn sakai:undeploy or so ?

  3. http://bugs.sakaiproject.org/jira/browse/SAK-9250 seems to indicate mysql driver 5.1.5 is recommended for mysql5, not 5.0.4. Are both ok?

  4. Hi ,

    With apologies for this rather "negative" message, I would like to report my experiences. I will also make some modest, suggestions. I have been working with open-source projects since the early days of GNU software. This one is turning out to be quite gnarly and frustrating. After spending a huge amount of time wading through the docs, the videos and struggling through many, many iterations with the build, I am writing this.

    My environment is as follows.
    (WindowsXP Professional, JDK 1.5.0.14, apache-tomcat 5.5.23, Maven 2.0.9, Subversion 1.4.6, MySQL 5.0.x).

    1) checkout-source
    (svn co https://source.sakaiproject.org/svn/sakai/branches/sakai_2-5-x/ )
    No errors.
    2) Environmental variables are as follows
    MAVEN_HOME environmental variable set to c:\maven
    PATH has %MAVEN_HOME%\bin within it.
    CATALINA_HOME=c:\apache-tomcat-5.5.23
    JDK_HOME=c:\Program Files\Java\jdk1.5.0_14
    3) I performed a "mvn clean install"
    Two maven repositories got created and populated.
    C:\Documents and Settings\ranki\.m2 (approx 60+ directories populated with libraries, jars ...)
    C:\Documents and Settings\ranki\.maven (6 odd directories ...)
    Is there a "maven target" to verify the repository's status for e.g something like
    (mvn check-repository). After populating the repository, some kind of hash check would be usefull. On obtaining a success, one could save a lot of time using the "mvn -o " option. i.e offline build).

    I have done this step many-many-many times (mvn clean install). No luck to date. I get errors during the download/install of jar files. The documentation is not clear on what can be ignored and when. These errors continue even after many many attempts.

    I also experimented by bypassing the "test" step, hoping to save some time and to ignore some extremely stringent tests. (-Dmaven.test.skip=true). I tried the mini version. (mvn -Pmini clean install ), again with no luck.

    In short, I read every document that seemed relevant, experimented with every thing, that I could lay my hands on and have had no luck.

    Can, I build the "Simplest Tool", Tasklist that you detail in the docs against a released binary build ?. It would be very helpfull and I could temporarily get out of build hell. (sad)

    /rk

    Is this designed to be this hard ?. (smile)

    1. Under the last section of this document titled Uninformative failure messages, should read mvn -X  (that's capital X not lowercase) for enabling debug output, at least in maven 2.0.9.
    2. I agree with the previous comment.  Build failures should not exist for long periods of time in a release branch (e.g. 2-5-x) and especially not in release candidates (e.g. 2-5-0_RC_04b).  I am currently looking at a build failure in the sam/samigo-audio package, complaining that a passphrase needs to be entered (see output below).
    3. Troubleshooting documentation is sorely lacking.  Barring this build error actually being fixed, there should at least be some documentation describing how to work around it.  I simply disabled the samigo-audio package entirely, by commenting it out from sam/pom.xml.
    [debug] Executing: /bin/sh -c "cd /Users/adi/svn/sakai/sakai_2-5-0_RC_04b/sam/samigo-audio && /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home/bin/jarsigner -verify /Users/adi/svn/sakai/sakai_2-5-0_RC_04b/sam/samigo-audio/m2-target/sakai-samigo-audio-2.5.0.jar"
    [info] jar is unsigned. (signatures missing or not parsable)
    [INFO] jarsigner: you must enter key password
    [WARNING] Enter Passphrase for keystore:
    [INFO] ------------------------------------------------------------------------
    [ERROR] BUILD ERROR
    [INFO] ------------------------------------------------------------------------
    [INFO] Result of /bin/sh -c "cd /Users/adi/svn/sakai/sakai_2-5-0_RC_04b/sam/samigo-audio && /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Home/bin/jarsigner /Users/adi/svn/sakai/sakai_2-5-0_RC_04b/sam/samigo-audio/m2-target/sakai-samigo-audio-2.5.0.jar false" execution is: '1'.
    


  5. my maven is work in the Step"Verify Maven ", but after the step "Sakai Installation", when I use "mvn --version", there is an error: "Exception in thread "main" java.lang.NoClassDefFoundError: '-Xms256m"
    I checked 'classpath' and 'path' again and again, and can't find anything wrong.
    I can't understand why this happen.

    1. What does your MAVEN_OPTS look like?

  6. A couple typos in what's above:

    • under the MAVEN_OPTS section, the sample command uses a space instead of an underscore
    • the link to 'Download a sample settings.xml file' seems to be broken. Is the attachment missing?
    1. Bad link removed on sample settings.xml. I only see an underscore in the MAVEN_OPTS section. Can you send me a copy of what you found.

  7. Unknown User (sswinsb2@une.edu.au)

    Something should be mentioned about the MySQL configuration parameter 'max_allowed_packet'.

    If you are storing your content in the database and don't change the 'max_allowed_packet' parameter from its default of 1Mb, you won't be able to upload anything larger than 1Mb. This can be set in the my.cnf file. You can view your current setting by executing 'show variables;' from the MySQL console and looking for the parameter max_allowed_packet. It's default is 1048576, which is in bytes.

  8. Estoy instalando sakai-src-2.5.4 en windows al ejecutar mvn clean install sakai:deploy y me genera el siguiente error, que puedo hacer??

    Tests in error:

    Tests run: 23, Failures: 0, Errors: 1, Skipped: 0

    -------------------------------------------------------
    T E S T S
    -------------------------------------------------------
    Running org.sakaiproject.search.indexer.impl.test.DbJournalManagerTest
    00:10:42,609 main INFO TDataSource:85 - Using Derby DB
    00:10:46,625 main INFO DbJournalManagerTest:80 - ================================== org.sakaiproje
    ct.search.indexer.impl.test.DbJournalManagerTest.testGetNextSavePoint
    00:10:47,000 main INFO DbJournalManagerTest:99 - ==PASSED========================== org.sakaiproje
    ct.search.indexer.impl.test.DbJournalManagerTest.testGetNextSavePoint
    00:10:47,015 main INFO TDataSource:85 - Using Derby DB
    00:10:47,343 main INFO DbJournalManagerTest:108 - ================================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testPrepareSave
    00:10:47,406 main INFO DbJournalManagerTest:121 - ==PASSED========================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testPrepareSave
    00:10:47,406 main INFO TDataSource:85 - Using Derby DB
    00:10:47,687 main INFO DbJournalManagerTest:130 - ================================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testCommitSave
    00:10:47,765 main INFO DbJournalManagerTest:148 - ==PASSED========================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testCommitSave
    00:10:47,781 main INFO TDataSource:85 - Using Derby DB
    00:10:48,015 main INFO DbJournalManagerTest:157 - ================================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testRollbackSave
    00:10:48,343 main INFO DbJournalManagerTest:172 - ==PASSED========================== org.sakaiproj
    ect.search.indexer.impl.test.DbJournalManagerTest.testRollbackSave
    Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.938 sec
    testGetNextSavePoint(org.sakaiproject.search.indexer.impl.test.DbJournalManagerTest) Time elapsed:
    4.437 sec
    testPrepareSave(org.sakaiproject.search.indexer.impl.test.DbJournalManagerTest) Time elapsed: 0.391
    sec
    testCommitSave(org.sakaiproject.search.indexer.impl.test.DbJournalManagerTest) Time elapsed: 0.375
    sec
    testRollbackSave(org.sakaiproject.search.indexer.impl.test.DbJournalManagerTest) Time elapsed: 0.56
    2 sec

    Results :

    Tests in error:

    Tests run: 27, Failures: 0, Errors: 1, Skipped: 0

    INFO ------------------------------------------------------------------------
    ERROR BUILD FAILURE
    INFO ------------------------------------------------------------------------
    INFO There are test failures.

    Please refer to C:\sakai\search\search-impl\impl\m2-target\surefire-reports for the individual test
    results.
    INFO ------------------------------------------------------------------------
    INFO For more information, run Maven with the -e switch
    INFO ------------------------------------------------------------------------
    INFO Total time: 25 minutes 21 seconds
    INFO Finished at: Wed May 20 00:10:48 GYT 2009
    INFO Final Memory: 129M/258M
    INFO ------------------------------------------------------------------------