Installing Sakai OAE from source with MySQL

Recently, I started to install a vesion of “Sakai OAE”: I am writing this post to share my experience with it simply because I think although Sakai Project is a very powerful and nice product, it does not have straightforward documentation. Generally, you can take two approaches: (1) download the application and try to configure and deploy it, (2) build from source with your configuration. For a while, I tried to use (1), however, I finally did not manage to get what I wanted. So, I turned to (2).

h3. Check out source

You can find the source code for *nakamura* on GitHub, that is core product from Sakai project. I checked out the source into a directory I call @SRC_ROOT@:

git clone git://

It creates a @nakamura@ directory after source checkout.

h3. Choose your version

Since there is ongoing development, I decided to use a release version so I used Version 1.1:

cd $SRC_ROOT/nakamura
git checkout 1.1

And, in this post, the version used for other modules will also be 1.1.

h3. MySQL Configuration

“This page”: describe how to configure to use MySQL JDBC bundle at the time of deployment. But, we will do the configuration before building the application so that the final artifact includes a default deployment of MySQL JBDC bundle. I’ll use the same page with some modifications to do so.

h4. Including MySQL JDBC Bundle in the default build process

First, we need to install this bundle as a pre-requisite for @nakamura@. Verify and edit @$SRC_ROOT/nakamura/contrib/mysql-jdbc/pom.xml@ to look like in the beginning of the file:


In the wiki page, there is a typo with @relativeUrl@ instead of @relativePath@. Now, we need to include the bundle for the default build process. Edit @$SRC_ROOT/nakamura/app/src/main/bundles/list.xml@ and add the following to the section with @startLevel=”1″@:


h4. Configuring JackRabbit to use MySQL instead of default Apache Derby

JackRabbit is required to be configured to use MySQL. It uses Apache Derby by default. Let’s first make a back-up of the original configuration:

cp  \
	$SRC_ROOT/nakamura/bundles/server/src/main/resources/repository.xml \ 

Now, edit the @repository.xml@ in the above address. In the configuration section for @Workspace@ add the following configuration instead of the default Derby configuration:


And, in the section for @Versioning@:


Remember to change the database name, user, and password for your installation. Also, in the wiki page, it mentions to use class @org.apache.jackrabbit.core.state.db.SimpleDbPersistenceManager@ which is deprecated by JackRabbit and replaced in the above configuration.

h3. Installing the application in a local repository

The configuration for building the application is complete:

cd $SRC_ROOT/nakamura
mvn install

You can verify that the application should be installed at @$MAVE_REPO_PATH/org/sakaiproject/nakamura/

h3. Preparing for deployment

To start and run nakamura, you need to have a working directory. So, create a directory somewhere and let’s call it @WORK_ROOT@.

h4. Configuration directory

Whenever nakamura starts, it looks at a special directory at @$WORK_ROOT/load@. So, we will create it and place some initial configuration under this directory. As far as I have understood, there are two standard ways to configure nakamura for runtime:

# @$WORK_ROOT/load@: In this directory you will place @*.cfg@ files to hold different properties. The configuration files are actually standard Java properties files. The configuration is done using the “fully qualified name” of the class that will read the configuration. We will have example in the following sections.
# @$WORK_ROOT/sling/config@: When you start the application, it will create a Sling Home Directory at @$WORK_ROOT/sling@ by default. In this directory, there can be different configuration files @*.config@ under @sling/config@. The directory path structure here is created based on the fully qualified names used in @load@ directory. Additionally, the @*.config@ files are *not* standard Java properties files and they are OSGi configurations containers. So, if you need to modify them pay attention to the difference of the way you should introduce a property.

“This page”: also provides an overview of the same topics before deployment.

h4. Server protection service configuration

Create @org.sakaiproject.nakamura.http.usercontent.ServerProtectionServiceImpl.cfg@ under @load@ directory to have the following content:


*Note* that @MY_SERVER_NAME@ includes public valid IP/address and local network names. Local invalid IPs *do not* work.

h4. JDBC storage client configuration

Create to have the following content:

Remember to match the information here to what you provided for the @repository.xml@.

h3. Running nakamura

Before running the application, make sure that the database for the application is created with proper permissions and there is no tables in there. As the final step, copy the application JAR file to @$WORK_ROOT@:

cp \ 
	$MAVEN_REPO_PATH/org/sakaiproject/nakamura/ \ 

You can run the application:

java -server -DXms1024m -DXmx1024m -XX:MaxPermSize=512m -jar &

After a couple of log messages, you can follow what’s happening with:

tailf $WORK_ROOT/sling/logs/error.log

When the application is started, there should be around 28 tables in the database. You can browse the root of the application with @/index.html@ at the address you specified in the configurations.

I’m still having problems with this configuration including getting e-mail service to work or the huge *WARN* messages from JackRabbit. Anyway, I hope this would be helpful for those starting Sakai as me.