Sakai Binary Distribution Installation Guide
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/.
1.0 Verify/Install Java 5.0Sun Microsystem's Java 2 Platform Standard Edition 5.0 (J2SE 5.0), a.k.a Java 1.5, remains the recommended JVM 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.
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. Sun recommends that you install JDK/JRE 5.0 Update 18+ (the final update is JDK/JRE 5.0 Update 22).
Sakai 2.6 can be run using Java Platform, Standard Edition 6 (Java SE 6), a.k.a Java 1.6, although to-date there is little production experience that warrants recommending 2.6 users to upgrade their JVM. Should you choose to run Sakai in a Java 6 JVM you must (at a minimum) add the following environment setting to your JAVA_OPTS:
To confirm that Java is both installed on your system and is the correct version for Sakai, run
java -version from the command line:
If Java is installed, basic version and build information will be displayed:
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:
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 variablesSeveral environment variables and related properties must be set for Java. For UNIX operating systems one typically modifies a startup file like
~/.bash_loginto 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 Variablesand set
JAVA_HOMEvia the GUI.
Set the JAVA_HOME environment variable to point to the base directory of your Java installation and add Java's
/bin directory to the PATH environment variable.
If the variable JRE_HOME is already set or if you want to use a particular JRE if you have more than one JRE installed on your machine then you'll want to set the JRE_HOME variable as well. JRE_HOME is what Apache Tomcat uses when it starts up, but it defaults to use JAVA_HOME if JRE_HOME is not set. In most cases, setting JAVA_HOME should cover both cases sufficiently.
Windows: append the string to the end of the
Path system variable
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.
Java 6 users must also add the following setting to their JAVA_OPTS:
Specify a Language and Locale (optional)
You can define the default language/locale when starting Sakai by setting the system properties
-Duser.region. For information on supported languages see the release notes or visit the i18N Work Group space.
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
Tomcat 5.5.27+ enforces strict quote escaping a change in *.jsp handling that have yet to be addressed in certain tools such as portfolios. The workaround requires adding this system property. See SAK-15736 - NPE when trying to preview portfolios when running in tomcat 5.5.27 and websphere Closed .
2.0 Install Tomcat 5.5.33Sakai 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+.
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.33 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+.
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.
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.33\
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:
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 variablesBy convention, the base Tomcat directory (e.g.
/usr/local/apache-tomcat-5.5.33) is referred to as
$CATALINA_HOME. As a convenience, you should create a
$CATALINA_HOMEenvironment 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 Variablesand set your Tomcat environment variables via the GUI.
CATALINA_HOME environment variable to point to the base directory of your Tomcat installation and add the Tomcat
/bin directory to your
Windows: append string to the end of the
Path system variable.
2.2 Configure TomcatIf 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.xmlfile. 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
ROOTwebapp 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
/webapps/ROOTthat prompts this re-direction. The
index.htmlfile should look something like the following:
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 managementYou can better manage Tomcat memory usage by creating a setenv.sh/.bat file defining
JAVA_OPTSenvironment variable settings in the
Mac/Unix: create a file called setenv.sh and add the following line:
Windows: create a file called setenv.bat and add the following line:
2.4 Set up Tomcat as a Windows serviceYou can convert the .zip install into a service install by running
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:
If you choose to do this in the GUI follow these steps: Open the configuration window, issue the following command:
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
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.:
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.,
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.
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
To set up remote debugging, please see (Remote Debugging).
3.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.
If you wish to configure a binary installation you'll need to manually create a
/sakai folder in $CATALINA_HOME to hold your
3.1 Configure Sakai
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
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
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.
3.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.
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
4.0 Start/Stop Tomcat
Start/stop Tomcat from the terminal by running the appropriate startup/shutdown script located in
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.
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).
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.
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.
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.
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 (email@example.com) - 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 (firstname.lastname@example.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 (email@example.com) - 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 (firstname.lastname@example.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:
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."