Sakai 2.6 配置英文原版

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.

Sakai 2.6 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.

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

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

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

Release Installation Notes

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

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

1.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 JAVA_HOME

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

Unix:

export JAVA\_HOME=/usr/java/java-current

Mac:

export JAVA\_HOME=/Library/Java/Home

Windows:

JAVA\_HOME=C:\j2sdk1.5.0_18

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.

Add $JAVA_HOME/bin to PATH

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

Unix:

export PATH=$PATH:$JAVA_HOME/bin/

Mac:

export PATH=$PATH:$JAVA_HOME/bin/

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

;C:\jdk1.5.0_18\bin

Set JAVA_OPTS

The default Java virtual machine (JVM) settings are insufficient for an application of Sakai's size. As a result several JVM parameters must be increased for Sakai to run, while others may need to be adjusted for optimal performance. At a minimum add the following property settings to your JAVA_OPTS environment variable. We recommend that you define these settings in Tomcat's /bin directory in a file named setenv.sh (Unix/Mac) or setenv.bat (Windows). See the Tomcat section below for more details.

Unix/Mac:

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

Windows:

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

Add 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.6 works with the Tomcat 5.5 series. We recommend Tomcat 5.5.26+ in order to avoid certain Tomcat security vulnerabilities present in earlier releases. Note however, that using Tomcat 5.5.27 requires the addition of a JAVA_OPTS parameter (see below). Sakai 2.6 is not compatible with Tomcat 6.0+.

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.

Sakai 2.6 out-of-the box (OOTB) will not run inside Tomcat 6.0+.

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

Good: C:\opt\tomcat\, C:\sakaistuff\installs\tomcat\

Bad: C:\program files\tomcat\, C:\opt\apache tomcat 5.5.26\

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 5.5.27 and strict quote escaping

Tomcat 5.5.27 enforces strict quote escaping which causes run-time errors in certain Sakai tools that use the JavaServer Faces (JSF) UI rendering 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 setting:

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

Tomcat JDK 1.4 Compatibility Package

Do not download and install the JDK 1.4 Compatibility Package. Sakai 2.6 will not run should you install it.

2.1 Set Tomcat environment variables

By convention, the base Tomcat directory (e.g. /usr/local/apache-tomcat-5.5.26) 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.

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 string to the end of the Path system variable

;C:\tomcat\bin

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

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.

2.3 Tomcat memory managment

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

After this you need to set the default startup options

C:\tomcat\bin> tomcat5 //US//Tomcat5 ++JvmOptions "-Xmx768m;-Xms768m;-XX:PermSize=128m;-XX:MaxPermSize=256m;-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, 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
-Dorg.apache.jasper.compiler.Parser.STRICT_QUOTE_ESCAPING=false

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.

  If you are using java6 (jvm.dll) you might get the unhelpful error in the System log "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.

In addition, when using java6 you need the option of -Dsun.lang.ClassLoader.allowArraySyntax=true. Please see SAK-15874  for more details.

Note: You can add additional options to this as well if you like. For instance -Dsakai.security=C:\tomcat\security

For setting up remote debugging, please see this page (Remote Debugging) 

3.0 Install Maven 2.0.6+

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.
Maven 2.0.6 is the minimum version that works with Sakai 2.6 although most Sakai developers run Maven 2.0.8 or 2.0.9 while a few use Maven 2.1.0. 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.0.8. 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

Maven version: 2.0.8
Java version: 1.5.0_18
OS name: "mac os x" version: "10.4.11" arch: "i386" Family: "unix"

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

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/apache-maven-2.0.8

Windows:

set MAVEN_HOME=C:\apache-maven-2.0.8

PATH

Add the Maven /bin directory to your PATH variable:

Unix/Mac:

export PATH=$PATH:$MAVEN_HOME/bin

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

;C:\apache-maven-2.0.8\bin

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

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

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

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.

4.0 Install Subversion 1.5+

The Sakai Community uses Subversion (SVN) as its source control management (SCM) system. We recommend SVN version 1.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.tigris.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.5.6 (r36142)
   compiled Mar 12 2009, 14:30:13

Copyright (C) 2000-2008 CollabNet.
Subversion is open source software, see http://subversion.tigris.org/
This product includes software developed by CollabNet (http://www.Collab.Net/).
. . . .

4.1 Set Subversion environment variables

SUBVERSION_HOME

Set the SUBVERSION_HOME environment variable to point to the base directory of your SVN installation.

Unix/Mac:

export SUBVERSION_HOME=/opt/subversion

Windows:

set SUBVERSION_HOME=C:\subversion

PATH

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

Unix/Mac:

export PATH=$PATH:$SUBVERSION_HOME/bin

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

;C:\subversion\bin

5.0 Get the Sakai source distribution

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/

Once, you have downloaded the code, choose a location to unpack the archive. When unpacked you will see a directory named sakai-src.

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.

Sakai  

Trunk	https://source.sakaiproject.org/svn/sakai/trunk/
Tags	https://source.sakaiproject.org/svn/sakai/tags/
Branches	https://source.sakaiproject.org/svn/sakai/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 2.6 kernel dependencies are managed by Maven.

Kernel (K1)  

Trunk	https://source.sakaiproject.org/svn/kernel/trunk
Tags	https://source.sakaiproject.org/svn/kernel/tags
Branches	https://source.sakaiproject.org/svn/kernel/branches

2.6 release tags

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.6.0/ sakai-2.6.0

2-6-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-6-x branch summary for more information. 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-6-x/ sakai_2-6-x

5.1 Sakai contributed projects (contrib)

Additional capabilities provided by Sakai Community members are available as "contrib" projects. These projects range from prototype efforts to mature tool and service releases such as the Universidade Fernando Pessoa's SiteStats tool or Etudes' Melete Lesson Builder tool.

The contrib repo is located at

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

Before installing a "contrib" tool check its release notes to confirm that it's Sakai common services dependencies have been updated to bind to the new kernel. Contrib tool information can also be found in Sakai's Confluence wiki.

Adding a 2.6-compatible contrib tool to your build is usually a straightforward process. For example, to add SiteStats to you Sakai build checkout the latest release tag into your sakai-2.6.0 base folder:

cd sakai-2.6.0
svn co https://source.sakaiproject.org/contrib/ufp/sitestats/tags/sitestats_2-0-rc1/ sitestats

Edit SiteStats' base pom file sitestats/pom.xml updating the <parent> pom's <version> value to the appropriate Sakai version:

<!-- Parent: Sakai master pom -->
<parent>
  <artifactId>master</artifactId>
  <groupId>org.sakaiproject</groupId>
  <!-- EDIT ME: Sakai Version -->
  <version>2.6.0</version>-->                     <!-- For 2.6.0 release -->   
  <!-- <version>2.6.1-SNAPSHOT</version> -->      <!-- For 2.6.x branch -->
  <!-- <version>2.7.0-SNAPSHOT</version> -->      <!-- For TRUNK -->  
</parent>

Then install SiteStats artifacts in your local Maven repository followed by deployment to your servlet container (e.g. Tomcat):

cd sitestats
mvn clean install sakai:deploy

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

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

A sample sample.sakai.properties file that documents many of the standard properties can also be found in config:

sakai-src/config/configuration/bundles/src/bundle/org/sakaiproject/config/bundle/sample.sakai.properties

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. Since any component property can in principle be overridden by a sakai.properties setting, sample sakai.properties files will show only a small fraction of all the possible settings.

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/

5.3 Default database support (HSQLDB)

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.

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.4 Build and deploy Sakai with Maven

Maven Master POM

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

Clean, Install and Deploy Sakai

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

-Dmaven.tomcat.home specifies Tomcat's location and can be omitted if Tomcat home is specified in Maven's settings.xml file.
If using Websphere instead of Tomcat, you must also add the -Pwas parameter option to the above command. This configures the build process to generate an enterprise archive (EAR) file for Websphere. See Building the Sakai Source for Websphere for more information.

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.

Maven Goal Options

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

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

5.5 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