6.1 Common Issues
Out of Memory Errors:
If the screen of a tool fails to load and catalina.out reports an "Out of Memory" error, then you'll likely need to alter your JVM settings. Many modern app-server technologies make use of objects that persist for longer periods of time, and therefore many Sakai deployments have found it beneficial to adjust the JVM with flags to specify enough permanent space to accommodate these objects. Programs that dynamically generate and load many classes (e.g. Hibernate, Struts, JSF, Spring etc.) usually need a larger permanent generation than the default 32MB maximum. The permanent generation is sized independently from the other generations because it's where the JVM allocates classes, methods, and other "reflection" objects.
Specify flag -XX:PermSize=16m to allow the JVM to start with enough memory so that it doesn't have to pause apps to allocate more memory. Specify -XX:MaxPermSize for the size of the permanent generation to be greater than the default 32MB maximum.
When running on servers with multiple cpus, you'd multiply the memory by the number of CPU's. For example, to run a quad-processor machine you'd set the flag to -XX:MaxPermSize=128m.
See also the "JVM Tuning" discussion in the Post-Installation Configuration
6.2 Working with Maven
|Maven in Sakai
| See the maven.pdf posted to the Architecture Docs folder of the sakai-dev site's resources (link below) for a more thorough examination of how maven is used with Sakai. You can also find the "source" of this document as an MSWord file in subversion:
- Newer versions of Maven:
Sakai will fail to build with the latest beta versions of maven (currently 1-1-beta, and 2.0). Maven 1.0.2 has been working reliably with Sakai for over a year, and the Sakai plugins have not been altered to conform to the architecture of Maven 2, so that even if Maven 2 comes out of beta in the near future 1.0.2 should continue to be used.
- Updating the plugin:
You can install the Sakai plugin into your maven environment, which is useful for letting you run maven commands from the modules and projects within Sakai instead of always building the entire code base. Installing the plugin makes it available whenever you use maven, not just for those projects that declare a dependency on the plugin. You will need to do this once each time you upgrade a minor point version of sakai.
Note that the plugin-version is not necessarily the same as the Sakai version. The correct version to use will be available as the value of the sakai.plugin.version property in the sakai/master/project.properties file.
|Maven plugin install
| maven plugin:download -DgroupId=sakaiproject -DartifactId=sakai -Dversion=2.1
- 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.
- Maven -x:
Running maven with the x argument runs it in debug mode, and produces even more verbose output, which can be very helpful if the standard output is not providing enough information about errors.
6.3 Tomcat Logs