Installing Sakai OAE from source with MySQL
Recently, I started to install a vesion of “Sakai OAE”:http://sakaiproject.org/node/2239. 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@:
cd $SRC_ROOT git clone git://github.com/sakaiproject/nakamura.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”:https://confluence.sakaiproject.org/display/3AK/Installing+and+Configuring+MySQL+5.5+for+Nakamura+0.11 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:
org.sakaiproject.nakamura base 1.1 ../../pom.xml
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″@:
org.sakaiproject.nakamura org.sakaiproject.nakamura.mysqljdbc 1.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 \ $SRC_ROOT/nakamura/bundles/server/src/main/resources/repository.xml.derby
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/org.sakaiproject.nakamura.app/1.1@
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”:https://confluence.sakaiproject.org/display/3AK/OAE+Configuration+and+Deployment 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 @org.sakaiproject.nakamura.lite.storage.jdbc.JDBCStorageClientPool.cfg@ to have the following content:
service.pid=org.sakaiproject.nakamura.lite.storage.jdbc.JDBCStorageClientPool jdbc-driver=com.mysql.jdbc.Driver jdbc-url=jdbc:mysql://localhost/nakamura?autoReconnectForPools=true password=root username=root
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/org.sakaiproject.nakamura.app/1.1/org.sakaiproject.nakamura.app-1.1.jar \ $WORK_ROOT/
You can run the application:
java -server -DXms1024m -DXmx1024m -XX:MaxPermSize=512m -jar org.sakaiproject.nakamura.app-1.1.jar &
After a couple of log messages, you can follow what’s happening with:
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.