Sakai Admin Guide - Verifying and Troubleshooting Your Sakai Installation

Owned by Former user (Deleted)
Last updated: Sept 03, 2013 by Former user (Deleted)
2 min read

Verifying and Troubleshooting Your Sakai Installation

Verifying Your Installation

Whether you are performing your first install of Sakai or upgrading to a newer revision, it is advisable to test the functionality you care about after each round of configuration changes.

A good source of information for running a Sakai installation through its paces are the test scripts coming out of the QA Working Group. In all likelihood, you will want to test a subset of the functionality covered by the test scripts according to the tools and use cases at your site.

When you develop your local test protocol, you will want to exercise the full range of options in each of the tools you plan to support. This will help uncover configuration issues local to your institutions. It may also help you build familiarity with known bugs and workarounds with your version of Sakai.

In addition to having your test users record problems that occur using a methodology like the critical incident technique, you should pay close attention to messages that appear in the tomcat system log (usually TOMCAT_HOME/logs/catalina.out).

Once you have verified functionality, go through the Sakai Admin Guide - Load Balancing and Scaling and Sakai Admin Guide - JVM Tuning sections of the admin guide for information on making sure your instance is configured to perform reliably under load.

Automated Verification of Your Installation

Some groups have had positive experiences using Selenium to perform automated tests on a Sakai installation. For more information, see one of the following links:

Troubleshooting Your Installation

When you encounter an unexpected behavior with your Sakai installation, there are a handful of sources of information that can help you diagnose the problem:

  1. Any onscreen messages
  2. Your tomcat logs (usually TOMCAT_HOME/catalina.out)
  3. Any component logs (such as that generated by James)
  4. The SakaiPedia and other Sakai Confluence pages
  5. The Sakai JIRA bug database
  6. Searching the archives of tool-specific mailing lists (such as OSP)
  7. Searching the sakai-dev gmane archives (for general problems)

If there are no stack traces or error messages, you may find it useful to increase the verbosity of logging. The log levels in Sakai can be changed by adding log.config directives to your sakai.properties file as specified here:
http://confluence.sakaiproject.org/confluence/display/BOOT/Controlling+logging+from+sakai.properties

If you reach the point where you have searched other sources of infomration and are asking the sakai-dev list for help, please make sure you provide:

  • Minimal details about your installation (Platform, OS, Sakai version, Java version, Tomcat version)
  • A description of the problem behavior and the steps required to reproduce
  • The text of any on-screen error messages you received
  • The text of the stack trace(s) recorded in your log files.

If you are able to verify that the problem is not an existing open bug and that it's not a local configuration problem, best practice is to report the bug using JIRA.