Developing with Sakai
The QuickProd files contains the root level project files for Sakai, and all the Sakai module folders.
Unzip this into the folder you designate as your Sakai development folder (called $SAKAI_DEV in these instructions). Get the file here:
Use a Java SDK version 1.4.2 or later: http://java.sun.com/j2se/1.4.2/download.html. Sakai 1.5.1 does not work with Java 1.5.
Set the JAVA_HOME environment variable to point to the base directory of your Java installation. This will enable Tomcat, Maven, and Eclipse find the right Java installation automatically. This may already be setup for you by your Java SDK installation.
- Windows example: JAVA_HOME="c:/dev/j2sdk1.4.2_04"
- Mac example: JAVA_HOME=/Library/Java/Home
Use Maven 1.0 or later: http://maven.apache.org/start/download.html
Maven installation is covered by their documentation in their Getting Started guide. Do "Download" and "Install", and read over the rest. After you install Maven, customize it by placing this build.properties file in your home directory. This file will identify an extra Maven repository for our use, and the location of your Tomcat installation for deployment.
maven.repo.remote = http://www.ibiblio.org/maven/,http://cvs.sakaiproject.org/maven/
maven.tomcat.home = /usr/local/tomcat/
Edit the "maven.tomcat.home" value to show your tomcat root location; leave the first line as is. Please note, and include, the trailing slashes in these settings - the deploy will fail if they are missing
If you are running on Windows, special care is needed in identifying your tomcat home. Maven wants unix-style forward slashes, "/", and is confused by Windows style backslashes "\". If you have your tomcat located in "c:\tomcat", you need to identify it like this:
maven.tomcat.home = c:/tomcat/
It is also possible to leave out the drive letter, if it is clear which drive this will be:
maven.tomcat.home = /tomcat/
Maven's build.properties is stored in your home directory, however that's defined on your platform.
Most Unix machines have this as
On later Windows machines, it's likely to be
"c:\Documents and Settings\userid" (where "userid" is your Windows user id).
For older Windows (95, 98) machines, if your Windows system is configured for single-user mode, your home directory is probably the Windows system directory "c:/windows".
Use Tomcat version 5, 5.0.28 or later: http://jakarta.apache.org/tomcat/index.html. There have been problems reported using Tomcat 5.5 for Sakai 1.5.
Sakai deploys a number of .war and .jar files into your Tomcat environment:
- .war files go into your webapps folder. Tomcat will expand these at startup.
- .jar files are deployed outside of the webapp framework to be shared by all the Sakai webapps. Most of these go into the Tomcat shared/lib folder. This is empty at Tomcat distribution; you can re-empty it when doing a clean deploy of Sakai.
- some .jar files go in Tomcat's common/lib and server/lib folders. The hsqldb-*.jar file goes into common. Some Sakai dav jars go into common and server. If you are using a jdbc database, the driver .jar would likely go here as well. When clearing out an old Sakai installation, be careful not to delete all of tomcat's common/lib or server/lib (as is safe to do with shared/lib).
Depending on how you have your Tomcat configured, you will get log files in the Tomcat logs folder. Some logs will be written to the console window in which you launched Tomcat.
Sakai supports UTF-8 allowing for non-Roman characters.
In order for all of the Sakai tools to properly handle UTF-8 non-Roman characters,
Tomcat must be configured to accept UTF-8 URLs. UTF-8 is the offical
standard for URLs; however Tomcat ships with ISO-8859-1 as the default URL encoding. To change
this setting, edit tomcat/conf/server.xml. Add the attribute URIEncoding="UTF-8"
to the <Connector> element. For example:
port="8080" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
Sakai takes over the "root path" (i.e "/") of Tomcat. Tomcat ships with a webapp called "ROOT". You must remove or rename the "ROOT" webapp so that Sakai can have the root path.
The "sakai-dispatch" webapp acts a the root webapp. One of the context files you deployed using the "maven tomcat_context" step controls this. The webapp is deployed to /usr/local/sakai rather than tomcat's normal webapp area, so it doesn't get Tomcat confused.
The root path is used by Sakai for URL to the server. Dispatchers are installed there to forward requests where they need to go among the various Sakai webapps.
The root webapp is also used as the one webapp that has all the user sessions. These sessions are specially shared among the various Sakai webapps.
You can use Eclipse to develop Sakai. However, it is not necessary to download or use Eclipse in order to build or install Sakai. If you are doing development, any development environment can be used to edit the Sakai source code. Final Sakai builds and deploys are done with Maven commands, not from an IDE like Eclipse.
You can use Eclipse to develop Sakai: http://www.eclipse.org
Eclipse has a feature called Classpath Variables which lets you use variables in project files, share the project files, and have each user define these variables to point at the appropriate, and perhaps different, location on their development machines.
You can set these variables in Eclipse (2.11) under Windows / Preferences / Classpath Variables.
In Eclipse 3.0 these variables can be accessed via project Properties / Java Build path / Libraries / Add Variables.
Sakai uses two variables on our Eclipse projects:
||points at the local maven repository
||points at the root of the tomcat install
(used to get at xercesImpl.jar)
There are some other eclipse variables that are used for source for our support packages. These are used just when browsing code, not for compile. If you have downloaded the source for the support packages we are using, you can set these. Some of the Eclipse projects have these source locations registered, by these variables:
||the spring framework 1.0.1 source
(make sure there's a /src folder within)
||the JavaServer Faces 1.1 source
(note that downloading
the JSF 1.1 source
requires a special license agreement)
||the Velocity 1.3.1 source
(make sure there's a /src folder within)
||the O.K.I. V2 OSIDs
(make sure there's a /src folder within)
||the Hibernate software (version 2.1.6)
(make sure there's a /src folder within)
Each Sakai module can be made into an Eclipse project. The special Eclipse files .classpath and .project are checked in to the CVS and distributed in the source .zip file. Once you have the source on your machine and have the Eclipse classpath variables set up, you can add each Sakai module as a Java Project in Eclipse.
Name the module "sakai-" followed by the Sakai module name. For example, the "chef-tools" module in Sakai should be called "sakai-chef-tools" in Eclipse. When adding the project, make it a Java type, and point it at the appropriate Sakai module directory. Eclipse will find its files and should be happy.
Sakai can be developed and compiled in Eclipse, but do the final compilation and build / deploy using Maven. The Eclipse projects are setup to share the same binary directories as used by Maven.
If you need to upgrade from Sakai 1.0.0, please follow the specific instructions for upgrading from Sakai 1.0.0 to 1.5.0.
If you have installed previous versions of Sakai or CHEF, you will need to clean up your Tomcat before starting with the 1.5.0 release.
It is recommended that your install a fresh new Tomcat. Clean up by clearing out your tomcat webapps, logs, shared/lib, and work folders. Continue cleaning by removing your local maven repository's sakaiproject folder. Also remove any CHEF based webapps from your tomcat; CHEF and Sakai are not compatible in the same Tomcat.
Once you have either checked out the source, or downloaded and unzipped the source, you can from $SAKAI_DEV use the "clean_env" goal of maven:
to delete the following files and folders:
||rm -rf TOMCAT/webapps/sakai-*
||rm -rf TOMCAT/webapps/sakai-*.war
||rm -rf TOMCAT/logs/*
|Tomcat Shared Lib
||rm -rf TOMCAT/shared/lib/*
|Tomcat Common Lib
||rm -rf TOMCAT/common/lib/hsqldb-*.jar
rm -rf TOMCAT/common/lib/sakai*.jar
|Tomcat Server Lib
||rm -rf TOMCAT/server/lib/sakai*.jar
||rm -rf TOMCAT/work/*
||rm -rf ~/.maven/repository/sakaiproject
Warning: use "clean_env" carefully, as it will delete files and folders. Check that your tomcat webapps are "clean" after using this maven goal, as it may not remove all the old webapps.
From the $SAKAI_DEV, issue this command:
This will run the default "clean_full" goal, download all dependent packages, build all Sakai source, install built source in your local Maven repository, and deploy the newly built Sakai to your Tomcat.
At least once, especially if you are working from CVS, issue these commands to fully setup your server for Sakai:
maven tomcat_context (for Unix/OSX)
maven tomcat_context_windows (for Windows)
This sets up the database configuration. If you are on windows, be sure to use "tomcat_context_windows" for the last command.
Other things you can do:
Sakai Maven Goals
|clean and fully build all of the Sakai -modules and deploy to Tomcat
|clean all prior build targets in the development folder
|re-build without cleaning and re-deploy
|clear out the maven repository and tomcat from prior Sakai (see above)
|copy the database configuration files from source to /usr/local/sakai. Note: This configures Sakai with the default HSQLDB configuration. To use MySQL or Oracle, see the section "Using a database".
|copy the tomcat context XML files from source to the tomcat/conf/Catalina/localhost folder. Use this if you are using tomcat 5.0.27, as it does not properly distribute these files from the .war files.
|the version of the tomcat_context goal that should be used if you are deploying on a Windows operating system.
|copy the registration files from source to /usr/local/sakai/reg. If you are working from CVS instead of the QuickDemo, you need to do this before running.
|Create javadocs from the Sakai source. Creates a javadoc folder and a .zip file of the javadocs.
Sakai looks in files on the server to get configured. As shipped, Sakai finds these in:
The contents of this folder can be populated by copying the files and folders from the Sakai reference module's "usr_local_sakai" folder to your machine's /usr/local/sakai/ folder, something like this:
cp -r $SAKAI_DEV/reference/src/usr_local_sakai/* /usr/local/sakai/
(where $SAKAI_DEV is your Sakai development folder)
Make sure that the /usr/local/sakai folder has permissions to allow you (during development) and tomcat (at runtime) to read, create and write files.
Verify after the copy that you end up with the files and folders as listed below.
It is not necessary to edit the local server configuration files in order to run Sakai on your localhost only. However, to run a publicly accessible Sakai instance you will need to modify (at least) the file sakai.properties. To change the selection of configuration of components, you will need to modify the components.xml files.
|Custom Server Configuration
These files contain the top-level convenient Sakai configuration values. This is where to configure the server host name and port, DNS servers for mail handling, and many other server properties.
Settings in these files override settings that can be made in various places in the components.xml files. Setting them here allows you to use unmodified distribution components.xml files.
You can have one or both of these files, and distribute the settings between them.
|Static Data Files
|These you won't have to modify.
|Starter Database Files
These files store and configure the default HSQLDB database.
These files are not used if you configure an external MySQL or Oracle database.
If you are running with the default HSQLDB database as a pilot or in production, you will want to regularly backup this directory.
The maven goal conf_db copies these files from the source into /usr/local/sakai/db
|Custom Service Components Configuration
These files control the choices and configurations of the service components used by Sakai. The default configuration selects and configures a set of components backed by tables on a SQL database.
The maven goal conf_db refreshes these files from the files in the source tree. Any changes you have made in /usr/local/sakai would be overwritten.
This is only one step in setting up for a database configuration. See the notes below.
These files register individual Sakai tools, and well as sets of tools for different types of Sakai sites.
The Sakai dispatcher webapp is deployed here instead of in Tomcat's webapp area. This webapp is configured to act as the root path for Tomcat. The "ROOT" webapp of Tomcat must be deleted or renamed for this to work.
This will be created and updated whenever you run the maven command from the $SAKAI_DEV or $SAKAI_DEV/deploy folder.
Start up Sakai by starting Tomcat. Watch your Tomcat output and monitor the logs! If things are not working, the logs will tell you what's going on.
Once started, you can access Sakai using this URL (modify this if you are using a different host name or port)
The out-of-box administrator's account and password are admin / admin.
In addition to the QuickProd zip file to access the Sakai source code, you can access the latest and prior versions of the code using the Sakai CVS server.
Anonymous access to our CVS is supported by SSH key. We have a public key for the "anoncvs" user installed on our server; you can download the "private" matching key, install it on your development machine, and gain full read access to the Sakai source modules.
Get the private key from here sakai_anoncvs_dsa, and install it in the appropriate place on your computer, likely it's ~/.ssh. Don't change the file name when you install it.
Then add these lines to your ssh config file, located in the same place:
Make sure that the IdentityFile line points at your downloaded key.
Your environment variable "CVS_RSH" must be set as follows:
You can check out the sakai code module like this:
cvs -q -z9 -d :ext:sakai_anon_cvs:/cvs co sakai
This version has been tagged "sakai_1-5-0".
There are other root level modules in the cvs, but only the sakai module is required to build Sakai.
For information on configuring Sakai to use different databases please see the Databases page.
You can also access the web interface to Sakai CVS.
An example, for Oracle:
Set the appropriate driver, connection string, user and password. The maxConnections is the pool size for the connection pool. The maxSlowConnections defines a second pool used for "slow" operations, such as streaming download.
To use the database, you need a set of service component implementations that use the database. Sakai ships with a set, and configurations for selecting them in the components_db.xml files. The easiest way to enable these is to run the maven command
from your $SAKAI_DEV folder. This moves the database configuration files from the source tree into your /usr/local/sakai/*. Any changes you have made to the components.xml files in /usr/local/sakai/* will be overwritten.
Sakai has clustering capability. Multiple Sakai application servers can be run, all using the same back end database. Be sure to set the server.id setting in sakai.properties to a unique value for each server in your cluster.
You may want to set the
default character set of your MySQL server
to be UTF-8.
You may want to set the
to GMT, although this is not strictly necessary.
Large file uploads cause large database queries.
You may need to increase the maximum query size your database allows.
In MySQL this can be accomplished by increasing
the max_allowed_packet property in the the configuration file my.cnf:
Sakai uses a database connection pool to access the database. It's size can be configured (see above). If you have too small a pool, Sakai will slow down somewhat, as various components that need to access the database wait in line for a connection.
If you need to make back end database corrections to the data, by modifying the tables directly, not through Sakai, the Sakai servers in the cluster need to be informed of this. The admin site has a memory tool, and a command to Reset All Caches. This reset command is shared among all application servers in the cluster. When you make a change to the database, reset the caches so that Sakai can become aware of the change.
Prior versions of CHEF and Sakai used the database engine's record locking to implement our exclusive object locking policy. This tended to eat up database connections and, if overloaded, lead to massive gridlock and unresponsive Sakai servers. This version of Sakai uses a locking table in the database to accomplish exclusive locking, and no longer has this scaling problem.