/
Sakai Admin Guide - Full

Sakai Admin Guide - Full

Sakai 2.x Administrator's Guide

This is a single-page version of the Sakai 2.x Administrator's guide, which is intended to be more useful for printing and exporting the document in PDF format. To export in PDF format, click the PDF icon () that appears in the top right side of each Confluence page.

You can also view the guide in sections.

Introduction

This document covers the basics involved in moving from limited exploration of Sakai to something that can be used reliably by a larger group of users. The document will take as a given a working Sakai installation that uses the out of the box defaults.

This document assumes you have already been able to successfully install Sakai. It is also recommended that you take a moment to familiarize yourself with using the application before exploring the topics in this guide.

If you get stuck during the installation or configuration process, please start by searching this site and/or an archive of the sakai-dev list (such as gmane). If all else fails, join the Sakai developer list (sakai-dev) or the Sakai production list (production) and ask for help. For more information, see the "Joining the Community" section of this document.

The sakai.properties file

As mentioned in other areas, the sakai.properties file is a central configuration file that is typically stored in a sakai subdirectory relative to the tomcat home directory ([here are details on changing the default location]). All settings in the sakai.properties file are only read on startup, thus any changes you make will only take effect when you restart tomcat.

The sakai.properties file 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.

The first type of simple property (used to set booleans, simple strings, integers, etc.) is set simply by separating a key from a value with an equal sign, along the lines of:

sampleboolean=true
samplestring=set to a string value with one or more spaces, ending in a new line

Sakai makes use of hierarchical lists of property values, which require that you specify a "count" variable indicating the total number of values. The values themselves are defined by appending a number after each instance of the key. Here's an example:

sampleproperty.count=3
sampleproperty.1=peas
sampleproperty.2=porridge
sampleproperty.3=hot

Configuring the sakai.properties file

An option set in the sakai.properties file is only meaningful if one or more sections of the Sakai code base read and make use of the option and its configured value. There are at present over 250 configuration options used by portions of the Sakai 2.4 code base.

To assist users in setting the most important of the options, an example sakai.properties file is included with the Sakai source, in the directory reference/docs relative to the root of the source directory. The demo and binary distributions are distributed with a basic sakai.properties file as well, which should be stored in the sakai directory relative to the tomcat install included with the distribution.

Starting with this file, it is most critical to review and edit the following settings:

These and other configuration settings are mentioned throughout the remainder of this document. For a full glossary of available configuration options, consult the Sakai Properties Reference.

The Configuration Viewer tool

There is an optional tool available to provide a detailed guide to the sakai.properties file. For more information, visit the Config Viewer Tool home page.

This tool includes a complete list of known sakai properties, which you can download independently of the tool and open using Excel or any spreadsheet program that can open tab-delimited text files. The latest version of the sakai properties data can be found here:

https://source.sakaiproject.org/contrib//config-viewer/trunk/properties/src/org/sakaiproject/configviewer/configViewer.txt

Branding and Identity

sakai.properties settings

There are a number of configuration options found in the sakai.properties file that control branding and identity. These settings are responsible not only for changing the cosmetic wording that end users see in the web interface, but also for customizing information found in logs and email messages.

Setting

Description

ui.institution

The name of the organization associated with this Sakai installation (such as "My University").

ui.service

The local brand for Sakai within the institution. Among other things, this text is displayed at the root of the bread crumb bar that appears within Sakai.

serverId

A unique identifier for the particular server Sakai is running on. This is used to distinguish nodes in a clustered environment from one another.

serverUrl

The full service URL for this installation of Sakai

serverName

The server name for this installation of Sakai (this should match the value for serverUrl).

skin.repo

The location in which skins for this site are housed. This can be set to a relative or absolute URL. The default is /library/skin, which includes the default skins bundled with Sakai.

skin.default

The default skin to use for all sites. This should be the name of a skin directory that exists in the skin home directory.

Skinning

To further change the look of a Sakai installation, it is possible to "reskin" the installation using a series of style sheets and/or updated graphics, which are typically stored in TOMCAT_HOME/webapps/library/skin. For more information about skinning your Sakai installation, visit the "Reskinning Sakai" section of the Sakaipedia. A guide is also available.

Binary Content and Filesystem Settings

Binary content (files) uploaded into Sakai can either be stored in the database itself, or on the filesystem. By default, binary content is stored in the database.

Storing binary content on the filesystem

To use the filesystem to store binary content, add properties like the following to your sakai.properties file:

bodyPath@org.sakaiproject.content.api.ContentHostingService=/content/sakai
# Only uncomment the bodyVolumes property if you have multiple content volumes
# (sub directories/ mount points relative to the location specified above)
bodyVolumes@org.sakaiproject.content.api.ContentHostingService=vol1,vol2,vol3
# uncomment the next line if you wish to set a site quota of 1Gb
# siteQuota@org.sakaiproject.content.api.ContentHostingService=1048576

Note that Sakai only balances content between active volumes. Sakai doesn't check the availabilty of disk space on each volume. So, for example, if you have a single volume containing 100Mb of filesystem content and add four additional volumes, when another 400Mb of files are added, the distribution is likely to be something like 180Mb on the first volume and 80Mb on each of the new volumes.

Body volumes should not include spaces

Warning: If you are using filesystem storage, you should be very careful not to include spaces before or after the commas in your bodyVolumes@org.sakaiproject.content.api.ContentHostingService. This will cause your volume to be created with spaces in their names, which can cause problems. For more information, see:

http://bugs.sakaiproject.org/jira/browse/SAK-9752

Setting at least one body volume

Note: If you are using filesystem storage, you should set at least one volume by adding a bodyVolumes@org.sakaiproject.content.api.ContentHostingService option (see above). This will give you room to expand and relocate your filesystem content as your Sakai installation grows. If you do not set this option, binary content will be stored in the root of the directory specified in bodyPath@org.sakaiproject.content.api.ContentHostingService.

Storing binary content in the database

To use the database to store binary content, comment out the directives mentioned above in your sakai.properties file. Any content already located on the filesystem will remain on the filesystem.

Migrating from database storage to filesystem storage

If you have previously stored your binary content in the database and would like to move that content to the filesystem, add the following directive to your sakai.properties file and restart:

convertToFile@org.sakaiproject.content.api.ContentHostingService=true

There is currently no conversion route to move from storing content on the filesystem to storing content in the database.

Antivirus Scanning

The Rsmart group has developed a wrapper for content hosting that uses ClamAV to scan incoming binary content before it is stored. Source code can be found at:

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

Database Configuration and Tuning

By default, all distributions of Sakai are configured to use an in-memory version of HSQL db, which is adequate for very basic testing, 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 use either MySQL or Oracle in production. The reference sakai.properties files include example configurations for Oracle and MySQL. Rather than copying and pasting this code, you should comment out the database configurations you aren't using, and then uncomment and modify the settings appropriate for your database.

Here is a sample configuration block for Oracle:


# Oracle settings - make sure to alter as appropriate
vendor@org.sakaiproject.db.api.SqlService=oracle
driverClassName@javax.sql.BaseDataSource=oracle.jdbc.driver.OracleDriver
hibernate.dialect=org.hibernate.dialect.Oracle9Dialect
url@javax.sql.BaseDataSource=jdbc:oracle:thin:@your.oracle.dns:1521:SID
validationQuery@javax.sql.BaseDataSource=select 1 from DUAL
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED


Here is a sample configuration block for MySQL:


# MySQL settings - make sure to alter as appropriate
vendor@org.sakaiproject.db.api.SqlService=mysql
driverClassName@javax.sql.BaseDataSource=com.mysql.jdbc.Driver
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
url@javax.sql.BaseDataSource=jdbc:mysql://127.0.0.1:3306/sakai?useUnicode=true&characterEncoding=UTF-8
validationQuery@javax.sql.BaseDataSource=show variables like 'version'
defaultTransactionIsolationString@javax.sql.BaseDataSource=TRANSACTION_READ_COMMITTED

It's possible that for older versions of Mysql, you may have a different dialect like MySQLInnoDBDialect, but this was tested successfully on MySQL versions 5.5.x. 

When using this block or uncommenting an existing block, you will need to modify the connection settings specified by the setting url@javax.sql.BaseDataSource at the very least. In addition, you'll need to set the username and password options whichever database you choose, as in:


username@javax.sql.BaseDataSource=sakai
password@javax.sql.BaseDataSource=********


Configuring for Performance

Larger institutions have found the database to be the bottleneck when it comes to Sakai performance. Setting additional database configuration settings may be worth considering (see below for tips for Oracle and MySQL).

Oracle

Oracle may have performance problems with some of the SQL settings that work for HSQL and MySQL. Sakai installations using Oracle should strongly consider the following settings in sakai.properties to avoid these problems:

# For improved Oracle performance (from the University of Michigan)
validationQuery@javax.sql.BaseDataSource=
defaultTransactionIsolationString@javax.sql.BaseDataSource=
testOnBorrow@javax.sql.BaseDataSource=false

These settings will reduce the DB load by not forcing these settings with each use or transaction.

Oracle and Tests & Quizzes  

If you're running Oracle and using the Tests&Quizzes tool you should check the datatype of the MEDIA column in the SAM_MEDIA_T table. Hibernate tries to choose the right data type for a field, but has a habit of choosing the wrong one for Oracle. The correct types for each database are:

HSQL: varbinary
MySQL: longblob
Oracle: blob

If you need to change this type for your database, this will also involve finding the primary key constraint, dropping it and then recreating it. Contact your local DBA for further information on making this change. Below is some sample Oracle SQLplus output to better illustrate (SYS_C0064435 is the example constraint; replace it with yours):

SQL> alter table SAM_MEDIA_T modify MEDIA BLOB;

Table altered.

SQL> select constraint_name from user_constraints where table_name='SAM_MEDIA_T'
and CONSTRAINT_TYPE='P';

CONSTRAINT_NAME
------------------------------
SYS_C0064435

SQL> alter table sam_media_t drop constraint SYS_C0064435;

Table altered.

SQL> alter table SAM_MEDIA_T add constraint SYS_C0064435 primary key (MEDIAID);

Table altered.

SQL> desc SAM_MEDIA_T;

[table with BLOB type]

SQL> select constraint_name from user_constraints where table_name='SAM_MEDIA_T'
and CONSTRAINT_TYPE='P';

CONSTRAINT_NAME
------------------------------
SYS_C0064435

SQL> commit;

Commit complete.

MySQL

Case Sensitivity

By default, table names in MySQL are case insensitive on Windows, and case sensitive on UNIX systems. Portions of Sakai that attempt to access tables directly may specify table names in all uppercase or lowercase, which may cause problems if the name specified in the query does not correspond exactly to the name of the table. The solution to this problem (other than waiting for code to be cleaned up) is to configure MySQL to think of table names as being case insensitive. This can be accomplished by editing /etc/my.cnf and adding the following:


lower_case_table_names=1


Note If you already are running at standard unix mode 0, you have to convert all of your database and table names to lowercase first as per the notice in the guide before you can switch to one. These statements worked for me to convert all of the tables in one database. Insert your database name that you want to convert here. You could probably do all tables in all databases by just getting rid of the where clause. You also need to rename databases (with the RENAME DATABASE) command if the contain upper case characters.


select concat('rename table ', table_schema, '.', table_name, ' to ' , table_schema,'.', lower(table_name) , ';')  from information_schema.tables where table_schema = 'databasetoconvert' INTO OUTFILE '/tmp/dbconversion.txt';
 
source /tmp/dbconversion.txt


Query Caching

MySQL performance can be considerably improved by caching queries. You can do this by editing your sakai.properties file and altering the connection string as below, all on one line.

url@javax.sql.BaseDataSource=jdbc:mysql://localhost:3306/sakai?useUnicode=true&characterEncoding=UTF-8
&useServerPrepStmts=false&cachePrepStmts=true&prepStmtCacheSize=4096&prepStmtCacheSqlLimit=4096

The parameter that enables use of the query cache is 'useServerPrepStmts=false', while the others (cachePrepStmts=true, prepStmtCacheSize=4096, and prepStmtCacheSqlLimit=4096) enable caching of prepared statements on the server side. Based on production experience at UniSA, a query cache size of 128M is recommended. The query cache size is typically configured on UNIX systems by editing /etc/my.cnf to like this:

[mysqld]
query_cache_size = 128M

You will need to restart your instance of mysql after making the change.

There are some other settable properties for the query cache, but there doesn't seem to be a need to change the defaults. To learn more, you can visit:

MySQL 5

Icon

The above configuration properties work for MySQL 4.1 only. The connection parameters that allow MySQL caching on MySQL 4 cause problems with bit types on MySQL 5. Until the issue is resolved MySQL 5 cannot be recommended for Sakai production, since the use of a non-caching string results in markedly poorer performance.

SAKAI_PRESENCE as an in-memory table

Running SAKAI_PRESENCE as an in-memory table can have a significant positive effect on performance for MySQL. The SQL necessary to convert is just:

DROP TABLE SAKAI_PRESENCE;

CREATE TABLE `SAKAI_PRESENCE` (
`SESSION_ID` varchar(36) default NULL,
`LOCATION_ID` varchar(255) default NULL,
KEY `SAKAI_PRESENCE_SESSION_INDEX` (`SESSION_ID`),
KEY `SAKAI_PRESENCE_LOCATION_INDEX` (`LOCATION_ID`)
) ENGINE=MEMORY DEFAULT CHARSET=utf8;

But be sure to run this at a quiet time as otherwise you'd be sure to generate some odd results for users.

Disk I/O issues on Linux (Suse Linux Enterprise Server 9/Red Hat Enterprise Linux 4)

A Linux database server may see big disk-hanging delays (especially if the DB and the web server are on the same machine) under load. This appears to be a side effect of the default SLES9 I/O scheduler, CFQ. The Deadline scheduler, which has a maximum latency for serving requests, is therefore a better choice for database operations - although pages may still render slowly under load, performance will degrade more gracefully, avoiding hangs, and will provide some feedback to users.

To switch to the Deadline scheduler, the boot parameter elevator=deadline must be passed to the kernel that's being used. You can do so by editing the /etc/grub.conf file and adding the parameter to the kernel that's being used:

title Red Hat Enterprise Linux AS (2.4.21-32.0.1.ELhugemem)
root (hd0,0)
kernel /vmlinuz-2.4.21-32.0.1.ELhugemem ro root=/dev/sda2 elevator=deadline reboot=warm
initrd /initrd-2.4.21-32.0.1.ELhugemem.img

You will need to reboot the system to activate the new scheduler.

For more information about these Database issues, refer to the following:

Email Configuration

Out of the box, Sakai uses incoming mail to receive content that will be viewed using the Mail Archive tool, and to receive delivery failure notifications for outgoing messages. Outgoing mail is used for notification purposes, bug reporting, and to deliver content received by the Mail Archive tool.

You need to change a handful of settings within and outside of sakai to get mail working. Most of the changes are in sakai.properties, and will require you to stop Sakai, remove the sakai-mailarchive-james directory under webapps (but leave sakai-mailarchive-james.war), and then start Sakai again.

Outgoing Mail

For outgoing mail, you'll also need to set smtp.dns.1 and smtp.dns.2 to your DNS servers, and to set smtp@org.sakaiproject.email.api.EmailService to a host that handles SMTP in your environment. James can also handle outgoing mail for Sakai, but that this should only be used for small scale installations, as James will not provide the same level of robustness as a dedicated mail server. In particular, James will not handle delivery failures nicely, which makes it unsuited for a real deployment.

You'll probably also want to set setup.request so that informational messages either appear to come from a meaningful address (such as helpdesk@your.institution) or to clearly not come from a usable address (such as noreply@your.sakai.hostname).

You can make all the changes at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Outgoing Mail Using a Notification

The simplest way to test outgoing mail is to add a guest user to a site and enable notification:

  1. Log in to Sakai as an administrator (or at least a site maintainer)
  2. Navigate to a worksite
  3. Open the "Site Info" tool
  4. Click the "Add Participants" Link
  5. Enter a valid email address that you have the ability to check under the "Guest(s) Email Address" heading (the lower text area), then click "Continue"
  6. Select a site role (usually "access" or "maintain"), then click "Continue"
  7. Tick the "Send Now" radio button and hit "Continue"
  8. Click "Finish"

A mail message should have been sent to the email address you entered for the guest account.

Incoming Mail

To receive mail, you need to set smtp.enabled to true. You'll also need to set serverName to the service name of your installation (as in sakai.your.institution), so that James knows what messages it should field. You should also set serverId to the real hostname of the individual machine (or at least the unique part of it).

If you don't already have a mail transport agent (ala sendmail or postfix) and can bind to port 25, you should change smtp.port to 25. If you already have a mail agent, you'll need to find some way to move the appropriate mail from port 25 to 8025 (where james lives). You can use a NAT rule, or can configure sendmail or postfix to do the forwarding for you:

Sendmail Integration Instructions: http://bugs.sakaiproject.org/confluence/display/ENC/Sendmail+integration

Postfix Integration Instructions: http://article.gmane.org/gmane.comp.cms.sakai.devel/6139/

Postfix Integration Instructions Alternate: Postfix Email Configuration

Exim Integration Instructions: Exim Configuration

The following is a sample section of sakai.properties including all of the above changes:

# enable James
smtp.enabled=true
 
# configuring the port on which James listens.  In this example, another component (NAT rules, Sendmail) forward from 25 to 8025
smtp.port=8025
 
# James will only accept messages for this hostname
serverName=service.my.edu
 
# You'll get more meaningful feedback if you have the node name configured
serverID=node.my.edu

You can make these changes all at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Incoming (and outgoing) Mail Using James

Once you get all that done and start Sakai, you should be able to test the your configuration as follows:

  1. make sure James is listening on the right port
    1. telnet {the value you used for serverName} 8025 [or 25 if you've set it to that]
    2. you should see a status message from the server indicating the server name and the MTA. The server name should match what you put in for serverId (plus a domain), and should be followed by something like
      (James SMTP Server 2.1.3) ready {date and time}
  2. Set up a site for testing the mail archive tool
    1. Create a new site that includes the mailarchive tool.
    2. Open the mailarchive tool in the new site. You should see the value of serverName as configured in sakai.properties.
    3. Change the options for the mailarchive tool to accept mail from anyone (this makes it easier to test things).
    4. Enroll a user in the test site with an email address you can monitor. Once this is done, you should get a copy of your test messages.
  3. Test James from the command line using telnet
    1. Connect to James using the port you set up above and a command like the following:
      telnet {your hostname, or localhost} 8025
    2. Now type:
      EHLO {your service name, ala sakai.your.institution)
    3. You should see a response like:
      250 {serverID.domain} Hello {serverName} (localhost [127.0.0.1])
    4. Now type:
      MAIL FROM:<{your.email@your.institution}>
      and hit enter.
    5. You should see a receipt like:
      250 Sender <{your.email@your.institution}> OK
    6. Now type:
      RCPT TO:<{the email address you entered for the mailarchive tool in your site}>
      and hit enter.
    7. You should see a receipt like:
      250 Recipient <{email address for the mailarchive tool in your site} OK
    8. Now type:
      DATA
      and hit enter.
    9. Now type:
      Subject: test...
      (or something like that) and hit enter twice.
    10. Now type the body of your message as in:
      This is a message I am using to test James.
      When you're done entering the body of the message, hit enter twice.
    11. Now hit enter, enter a single period, then hit enter.
    12. You should see a receipt like:
      250 Message received
    13. Now type:
      QUIT
      and hit enter.
    14. Check the mailarchive tool to see if your message made it in.
    15. If that doesn't work, go back and check your settings. The log files logs/catalina.out and sakai/logs/james-DATE may help figure out what's wrong.
  4. If you have a separate mail transport agent (i.e. sendmail or postfix), try the same steps as above, but with the port for the MTA (25) instead of James.
  5. Check to see that you've received a copy of the messages. If you haven't, check the logs and look for details in the returned message that will eventually be sent to the MAIL FROM: address you entered.

Delivery Failure Notifications

If you wish to receive delivery failure notifications, abuse notifications, etc. for mail sent from your Sakai installation, you should make sure that postmaster@{your service name} is a working email address. It is also advisable to set meaningful email addresses for the postmaster and admin users included with Sakai. If you are using James as a standalone mail server or forwarding all mail for your service host name to James, you may wish to configure an instance of the Email Archive tool to receive, display, and forward all mail for postmaster. By default, the alias "postmaster" is reserved (to prevent site maintainers from assuming that address). In order to set up an instance of the Email Archive tool to handle the postmaster address, you will need to manually remove the entry for the postmaster address from the sakai_alias table. You should then immediately add an instance of the Email Archive tool to a site of your choice (either the Admin Workspace or a dedicated site). Messages received for postmaster by James will then be viewable in the instance of the Email Archive tool you've set up. You should configure that instance of the Email Archive tool to accept messages from anyone.

Email Archive Tool Alias Naming Limitation

As noted above, Sakai includes a postmaster account for use by James. As a consequence, the alias "postmaster" is reserved and should never be used as an Email Archive Tool alias. Doing so will result in Sakai throwing a runtime error.

Configuring Sakai from within the Web Application

Once Sakai is up and running and you are familiar with the basic operation of the software, there are few common administrative tasks that you may wish to perform.

Change the Default Administrator's Password
By default, the application ships with an administrative user named "admin" whose password is also "admin". Once you get Sakai up and running, one of the most important configuration tasks is to change the default admin password. To do this:

  1. log in to Sakai using the username "admin", password "admin".
  2. Navigate to the "Administration Workspace" site, then open the "Users" tool.
  3. Click the "admin" user's name in the list of users
  4. Enter a new password, then click "Update Details"

Adding Administrative Users

If you wish to delegate administrative permissions to a range of users and wish a clearer audit trail for admin changes, you may want to set up additional administrator accounts. To add a new administrative user:

  1. Log in as an existing administrator
  2. Under the "Administration Workspace" site, open the "Users" tool.
  3. Click the "New User" link.
  4. Enter the new user's information and set their type to admin (mostly a nicety to help remember who the admins are)
  5. Click "Save Details"
  6. Open the "Worksite Setup" tool. Check the box next to the "Administration Workspace" site, then click "Edit".
  7. Click "Add Participants" then enter the username you created earlier in the "Username(s)" text area (the upper of the two). Click "Continue".
  8. Tick the radio button for the "admin" role, then click "Continue".
  9. Select your notification options if desired, then click "Continue".
  10. Click "Finish" to add the user to the Administration Workspace as an admin.

If you wish to give a user superadmin privileges without adding them to the Administrative Workspace site:

  1. Create a new user following the first 5 steps above.
  2. Under the "Administration Workspace" site, open the "Realms" tool.
  3. Enter "/site/!admin" in the search field and hit the "Search" link.
  4. Click the "/site/!admin" link that appears in the list of results.
  5. Click the "Grant Ability" link at the top of the screen that appears.
  6. Enter the id of the user created above in the "User Id:" text box, select the "admin" role, then click "Done".

Manually Adding a Tool to a Sakai Site.

By default, a number of provisional tools are included with Sakai, but can only be added to a site manually. This process is detailed in the SakaiPedia entry "Manually Adding a Tool to a Sakai Site".

Displaying dynamic HTML within the gateway and other sites.

By default, the gateway site displayed before users logged in displays a two-column layout containing the latest message of the day and the content of the location specified by server.info.url in your sakai.properties file. The default location for server.info.url points to a static HTML file bundled with a standar Sakai installation. Administrators are likely to prefer a message that can be updated without requiring a restart. Here's an approach to making the server info displayed in the gateway dynamic:

  1. Open the "Administration Workspace"
  2. Open the "Resources" tool
  3. Click on the "public" directory.
  4. Use the triangle to the right of the Add button to select the "Create HTML Page" option.
  5. Enter your content, then click "Continue.
  6. Select a name and copyright options for your page, then click "Finish".
  7. Once the page is saved, copy and paste the URL for your page into memory (the URL will typically be something like http://hostname/public/Your File Name.
  8. Edit your sakai.properties file and set server.info.url to the URL specified above (the protocol and port are optional).
  9. Restart Sakai

A similar approach can be used to prepare public content for use in any site or template. As above, create public content from the "Administration Workspace" site. Once you've saved your content, simply add an additional "Web Content" tool to the site in question. Here's an example in which we add a custom page to the default template for new "My Workspace" sites (useful for training materials, etc.):

  1. Follow the steps to create a dynamic page as in the previous examples.
  2. Open the "Sites" tool
  3. Open the "My Workspace" template (!user)
  4. Click the "Pages" button
  5. Click the "New Page" link
  6. Enter a name for your new page (this will appear in the list of pages in the navigation bar).
  7. Click the "Tools" button
  8. Click the "New Tool" link
  9. Select the radio button next to the "Web Content" tool
  10. Scroll down and enter the URL you copied above into the "source" field.
  11. Click "Done" to save your changes.

Template sites only show up in the "Sites" tool. For individual sites, you can simply add the dynamic content as follows:

  1. Follow the steps to create a dynamic page as in the previous examples.
  2. Open the site
  3. Open the "Site Info" tool
  4. Click the "Edit Tools" link
  5. Select the "Web Content" tool, then click "Continue"
  6. Enter the URL you copied above into the "URL" field, then click "Continue", then "Finish"

Permissions

The permission to view, edit, delete, and otherwise manage the data associated with Sakai tools is managed using realms, which are most commonly associated with a site. Each realm has one or more roles to which a user can be assigned. Permissions are managed using the Realms tool in the administrative workspace.

Examples of roles would be instructor, student, teaching assistant, grader, site maintainer, site accessor. A role is typically given a single word name like "instructor", "student", "ta", "grader", "maintain", "access". Each role specifies explicitly all of its permissions, and one set of permissions does not imply another (for example, "add" for a given tool does not imply "edit" or even "read" for the same tool).

The default permissions for a realm are inherited from the most appropriate realm template for a given site at the time the site is created. A site with a type of "project" would inherit from the realm !site.template.project realm if it exists, or from the !site.template realm if !site.template.project realm does not exist.

JVM Tuning

JVM tuning is an ever-evolving process that changes with each version of Java. Even for development instances, you'll need to read through and apply the basic JVM tuning suggestions below.

Basic JVM Tuning

The default JVM settings are not adequate to run Sakai. At a minimum, you need to increase the overall heap size and the maximum size allowed for the permanent generation. This can be done as follows.

Mac/Linux: Create the file TOMCAT_HOME/bin/setenv.sh containing a line like the following:

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

Windows(PC): Create the file TOMCAT_HOME/bin/setenv.bat containing a line like the following:

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

Advanced JVM Tuning

For more information, please see:

Load Balancing and Scaling

Introduction

Although Sakai can be run on a single server which houses all database and filesystem content, many sites will want to consider growing their installation beyond the confines of a single server. This section of the admin guide will outline the basic approach to scaling up your sakai installation. When deciding which approach is best for you, you should consider the information below. Whatever solution you choose should be tested for performance and tuned as needed. For more information on tuning, see the Sakai Admin Guide - JVM Tuning and Sakai Admin Guide - Database Configuration and Tuning sections of the admin guide.

Standalone Server

The simplest option is to run all components of Sakai on a single server. As indicated by the asterisks in the diagram, Apache and filesystem storage are optional components, as Sakai can run with Apache (using Tomcat to handle requests directly) and can be made to store binary content in the database.

This configuration entails installing a database server locally or using the default Hypersonic SQL implementation bundled with Sakai. This option offers the least benefits in terms of scalability and redundancy.

However, this configuration is highly portable, and can be set up on a reasonably powerful laptop. Thus it is ideally suited for a standalone development environment, which allows a developer to write and test tools and modules for Sakai without even a network connection. This is also a good option when demonstrating Sakai in environments without reliable networking.

Thin client configuration

A "thin" client is simply a server which only runs the application component of Sakai, and which does not house any database or filesystem content. This solution allows institutions with existing database and distributed storage resources to take advantage of their existing infrastructure. It may be acceptable to run a limited demonstration or pilot with this configuration, but a load balanced solution is recommended for anything beyond that (see below).

Load balanced thin client

A load balanced collection of thin clients is one of the scalable options for Sakai. It offers load balancing to distribute large volumes of traffic. It also offers redundancy, which allows for the more seamless management of hardware failures and preventative maintenance. In this configuration, each application server is pictured as only running tomcat, which is the minimum required to run Sakai.

Thicker client

A "thicker" client is simply an application server that runs one or more tomcat instances behind an apache instance. Adding Apache allows you to take advantage of the configurability and maturity of Apache, and also to set up clients that contain more than one instance of tomcat. A key reason to consider this information is the hard limit of memory usage on 32-bit hardware. The 32-bit JVM is only capable of addressing around 2G of RAM, which is tight for a full Sakai installation. You can install multiple tomcats on a single application server, and thus take better advantage of the memory available.

Big Iron

A number of sites have chosen to run with a smaller number of more powerful servers (as few as one), which are divided up into a series of virtual machines using solutions like VMWare. Although this may create a single point of failure for instances with only one large server, it offers the ability to dynamically allocate CPU and RAM among multiple virtual machines. It also has great advantages for change management, as a single node can be updated, tested, and then cloned into the appropriate number of updated application servers. Also, the state of a node can be saved for rolling back major changes if problems are detected later on.

Load Balancing Solutions

Sites running sakai in production have chosen to handle load balancing in a multitude of ways. These can roughly be divided into software solutions, which run on existing hardware, and hardware solutions, which run software on dedicated hardware, typically provided by a commercial vendor.

Software Solutions

The simplest software solution is to use an instance of Apache to balance traffic between multiple tomcat installations using mod_jk (apache 1.3 and 2.0) or mod_proxy_ajp (apache 2.2 and higher). Apache 2.2 or higher also offer the ability to use mod_proxy_balancer to balance multiple apache or tomcat installations. For more details on setting up tomcat with mod_proxy_ajp, see the Sakai Admin Guide - Advanced Tomcat (and Apache) Configuration section of the admin guide.

Hardware Solutions

There are a number of dedicated solutions provided by commercial vendors such as Big5 Networks and Zeus. Some solutions offer only the ability to load balance HTTP traffic (comparable to mod_proxy_balancer), while others offer the ability to use AJP (comparable to mod_jk or mod_proxy_ajp). Any solution that provides compatible sticky sessions (see below) should be capable of working with Sakai.

Sticky Sessions and Sakai

Whatever load balancing solution you choose, you must ensure that each client remains on the same app server for the life of their session. There are multiple approaches for monitoring and maintaining sticky sessions. Solutions that use IP-based sessions have problems with virtual private networks and proxies. Solutions that use dedicated cookies seem to work best for most people, but may cause problems with web services calls and some DAV clients. Whichever method you choose, be aware that the sticky session timeout is one of the factors controlling how long idle sessions remain active, as users will be required to log in again if they are sent to a different node after their sticky session times out.

Cluster Options in the sakai.properties File

Key portions of Sakai are designed to be cluster-aware. There are a handful of settings in the sakai.properties file that control the way in which clustering is managed.

Property

Description

expired@org.sakaiproject.cluster.api.ClusterService

The time in seconds after which an inactive server will be expired from the cluster.

ghostingPercent@org.sakaiproject.cluster.api.ClusterService

The percentage of maintenance passes to run the full de-ghosting / cleanup activities, including delisting stale server nodes.

refresh@org.sakaiproject.cluster.api.ClusterService

How often (in seconds) a server should register that it is still aliv