This guide is still in its infancy, focusing on a handful of the most common issues that plague novice deployers of Sakai, and a couple of the basic methods used to diagnose problems and delve more deeply into understanding the software.
*NOTE: See the maven.pdf resource posted to the Resources area of the sakai-dev site on http://collab.sakaiproject.org for a more thorough examination of how maven is used with Sakai
jar download failures
A first build of Maven on a fresh installation will warn of numerous jar download failures during the clean phase. This is not a problem. Even when doing a clean, maven tries to download dependencies. When the repository is initially empty maven can freak out during the clean phase while looking for jars that the impending build phase has yet to build. Once they are built, maven clean is perfectly happy next "clean build" cycle.
Tomcat write permissions
The most common maven build failures stem from the user running maven not having write access to the Tomcat directories being deployed to. Maven's error messages should make this fairly plain when it happens, and will even specify which copy or delete operation failed.
Beta versions of Maven
Problems have been reported using some of the latest beta versions of maven (currently 1-1-beta). Maven 1.0.2 has been working reliably with Sakai for over a year, and we recommend it over any new, non-stable versions.
Once you have Sakai installed, configured and started, you can monitor Sakai by watching the logs. The log level for the standard Sakai source code and the demo is set to show info and warnings only. If you need to see more information, you can change the logging level to enable debug messages as well for all of Sakai or merely specific components. Sakai uses log4j for logging: see the log4j documentation for more information about how to configure it. Watch for the WARN: messages. There are going to be some "normal" ones at startup, and some will likely slip by at runtime, but any warning is potentially something you might want to check out.
On Mac and *nix systems the most important log is catalina.out in $CATALINA_HOME/logs.
On Windows systems the situation is a little more complicated. The logs are also stored in $CATALINA_HOME\logs, but there are more of them:jakarta_service_%date%.log
The Windows equivalent of catalina.out is the catalina.%date%.log, so focus on that one.
Tomcat can take a long time to load the Sakai application, and it's often a good idea to watch the log in real-time as Tomcat comes up. You can watch for errors, and it will also allow you to be sure when Tomcat is done starting up. To do so on Mac or *nix systems you can run the command:
tail -f $CATALINA_HOME/logs/catalina.out
To change the logging for Sakai, you need to change Sakai source code and re-deploy sakai. The file you need to change is:
The section that pertains to Sakai as distributed is:
To turn on debug logging for all of Sakai, change that to:
To turn on debugging only for one part of Sakai, add a line like the one below:
This, for example, will leave most of Sakai at INFO, but the legacy SQL service will generate DEBUG level messages.
The SMTP server logs from Sakai will be written to the $CATALINA_HOME/sakai/logs directory.
Here is a very brute force and time consuming method which has the benefit of being very "instructional." In a slow way.
Load Sakai into your Eclipse environment (get an Eclipse book if you need to), then start your Tomcat this way:
catalina.sh jpda start
This configures the JVM to open a debugging port (8000) [Security warning: anyone can now access this Sakai instance using the following technique, so it's strongly suggested that you consider changing ports. Take a look at the catalina.sh script for more details.]
Then in Eclipse choose:
Nothing immediately happens, but this is OK. Root around the code in Eclipse to find the RequestFilter over in the kernel project. Set a break point in the doFilter. Near the top will do.
Now access your site via a web browser. At this point you can have the pleasure of walking through the Sakai request using the Eclipse debugging tools.
Eclipse may well shudder a bit and ask if you would like to continue in the debugging perspective. You do. In this perspective you will see some arrows that point down (enter fcn call) and sort of loop over (skip entry, go to next stmt). Check that Eclipse book again if you've not used this part of Eclipse.
In practice you'll more often set these break points far far far further down the call stack; you'll see why after you grovel through this a few times.