Developer's Guide

Developer Setup

A developer's workstation can be setup by following the steps outlined below;

KIS account - In order to have read/write access to the OLE version control repository, one must have a valid KIS account. Please contact your project manager to have an account created.
Required Software
1. Java SDK - Currently OLE is developed and tested using JDK 1.6 (Java 6) and soon we will be moving to JDK 1.7 (Java 7). The software can be downloaded from here.
2. Maven 3.x - OLE uses maven as the build management tool and the software can be downloaded from here. Maven uses this idea of pulling down the required artifacts (jar files) from a central repository. Sometimes the dependent jars may not be found in the central repository due to licensing issues and so Kuali also maintains a repository that has our own published artifacts. A common example would be oracle jar that is not published to the central repository. In order to download jars from the Kuali repository, the settings.xml under user.home/.m2 folder needs to be updated with the following entries:
  Maven Settings.xml Expand source
```
?xml version="1.0" encoding="UTF-8"?>
 <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <mirrors> 
     <mirror> 
        <id>kuali.private</id> 
        <mirrorOf>*</mirrorOf> 
        <url>http://nexus.kuali.org/content/groups/developer</url> 
     </mirror>
    </mirrors> 
   <servers>
     <server> 
      <id>kuali.private</id>
      <username>developer</username> 
      <password>[check with your project lead or the configuration manager]</password> 
     </server> 
   </servers> 
</settings>
```
3. Tomcat - OLE is deployed under Tomcat web container. The software can be downloaded from here.
  Required database libraries for tomcat
  
  Ensure the following jars are in your tomcat.home/lib directory; ojdbc6.jar and mysql-connector-java-5.1.13.jar. These jars can be found in your user.home/.m2/repository directory as it gets downloaded via maven once you do a build.
  These jars will be required for database connectivity when the applications are launched in tomcat.
4. MySQL/Oracle - OLE supports both MySQL and Oracle and these can be downloaded from here.
  
  Oracle Install
  
  Oracle installation is tricky on a mac/ubuntu workstations, and so as a temporary workaround, install a VM with Windows or Oracle's VirtualBox that comes with Oracle bundled.
  MySQL version
  
  At the moment the latest version of MySQL which is 5.6 wont work with the impex tool that we have. One must install the 5.5 version of the MySQL server.
Checking out the codebase - ~~OLE codebase can be checked out from the following SVN location~~. Until the trunk gets stabilized for 1.0.0, use the following svn location.
Building the OLE modules - OLE is made up of three modules namely OLEFS, OLELS and OLEDOCSTORE.
1. From the root directory of where the OLE codebase has been checked out run the following maven command
  mvn clean install -DskipTests=true
2. Building the OLEFS application - OLEFS is the financial module with KFS as the core. KFS is an ant style project, so even though it may look it has pom file and a maven build process, behind the scenes several ant targets are called to get the application ready for deployment.
  1. Database setup - The default database setup is MySQL and running the following maven command will setup a clean database for OLEFS. The default username and passwords are OLE/OLE. Also the default dba username is root and password is none.
    cd project-directory/ole-app/ole-fs mvn initialize -Pdb
    
    Alternatively if you have your MySQL server setup with a dba username/passoword, then update your maven command to the following and execute; mvn initialize -Pdb -Dmysql.dba.username=[fill me] -Dmysql.dba.password=[fill me]
  2. Verify the database got created by; there should be an entry for OLE in MySQL
  3. Generating the war file - The war file would have been generated as part of 4.a and can be located under project-root-directory/ole-app/ole-fs/target/olefs-[version]-webapp.war;
3. Building the OLELS application
  1. Database setup - The default database setup is MySQL and can be done using the following maven command
    cd project-directory/ole-rice2/ole-rice-db mvn clean install -Pdb
    
    Alternatively if you have your MySQL server setup with a dba username/password, then update your maven command to the following and execute; mvn clean install -Pdb,mysql -Dimpex.dba.username=[fill me] -Dimpex.dba.password=[fill me]
  2. Verify the database got created; there should be an entry for OLERICE2 in MySQL.
  3. Generating the war file - The war file would have been generated as part of 4.a and can be located under the project-root-directory/ole-rice2/ole-rice-webapp/target/ole-rice-webapp-[version].war
    
    OLELS uses rice style configuration file for property loading. By default the DB connection info is set to Oracle to make the unit tests work on the CI server. You will need to override some of the values and so will need to create or have in place a file called ole-rice2-config.xml under user.home/kuali/main/local folder with the following entries;
    ole-rice2-config.xml
    <config> <param name="application.id">olerice2</param> <param name="app.code">olerice2</param> <param name="app.context.name">${app.code}</param> <param name="application.url">http://localhost:9090/${app.context.name}</param> <param name="datasource.url">jdbc:mysql://localhost:3306/OLERICE2</param> <param name="datasource.username">OLERICE2</param> <param name="datasource.password">OLERICE2</param> <param name="datasource.ojb.platform">MySQL</param> <param name="datasource.platform">org.kuali.rice.core.framework.persistence.platform.MySQLDatabasePlatform</param> <param name="datasource.driver.name">com.mysql.jdbc.Driver</param> <param name="datasource.pool.maxWait">30000</param> <param name="datasource.pool.maxSize">20</param> <param name="datasource.pool.minSize">5</param> </config>
4. Building the OLEDOCSTORE application
  1. Database setup - OLEDOCSTORE is based on Apache Jackrabbit core and currently running the application sets up the db directly.
  2. Generating the war file - The war file would have been generated as part of step 4.a and can be located under the project-root-directory/ole-docstore/ole-docstore-webapp/target/oledocstore.war

Deployment to tomcat

OLEFS - Rename the war file from 4.b.iii to olefs.war and copy it to your local tomcat's webapps folder.
OLELS - Rename the war file from 4.c.iii to olerice2.war and copy it to your local tomcat's webapps folder.

OLEDOCSTORE - Simply copy the oledocstore.war to your local tomcat's webapps folder.

If you dont want to perform steps a, b and c, alternatively you can point your local tomcat to the individual modules. The following lines need to be added to the file named server.xml under the tomcat.home.directory/conf folder and within the <Host> </Host> tags.

<Context docBase="project-root-directory/ole-app/ole-fs/target/ole-fs-webapp" path="/olefs"/>
 
<Context docBase="project-root-directory/ole-rice2/ole-rice-webapp/target/ole-rice-webapp" path="/olerice2"/>
 
<Context docBase="project-root-directory/ole-docstore/ole-docstore-webapp/target/ole-docstore-webapp-webapp" path="/oledocstore"/>

Verify the applications are up and running:

Ensure the JAVA_OPTS have the following entry too for the memory settings; -Xms512m -Xmx1g -XX:MaxPermSize=512m

The above steps have been tested and verified to get a working OLE codebase on a local developer's machine (Mac/Ubuntu). The steps should be very similar on windows too and if there are any issues, contact devops@ole.kuali.org. There are few scripts attached here also that essentially perform the steps above in an automated fashion.

System Variables

Ensure the following system properties are set;

OLE_WORKSPACE_ROOT
TOMCAT_HOME

On a Mac/Ubuntu this will be typically found in the .bashrc or the .profile files;

On a windows machine its set in the environment variables section under Advanced Settings in the Control Panel

ole.sh - Script to checkout codebase and build to produce the deployable artifacts.
db-refresh-mysql.sh - Script to refresh local MySQL DB for OLEFS and OLELS ( Ensure to update this script with the appropriate impex.dba.password (root password for your MySQL installation) )
InitializeAndStartTomcat.sh - Script to copy the deployable artifacts to local tomcat and bring up the applications.

IDE Setup

- Developers are free to use IDE of their choice, but in Kuali the two most common ones are Eclipse and IntelliJ