Copy of OLE Technical Knowledgebase

Kuali Open Library Environment is an open source enterprise software solution to fulfill libraries needs in terms of financial and content management. Financial management is implemented using the already developed Kuali Financial System which is bundled within OLE. Content management has been implemented using the Apache Jackrabbit and Apache Solr technologies, details of which can be found in subsequent sections or tabs on this main page.

KOLE is a mix of ant style and maven style applications. There is a maven wrapper for the ant part of the project (KFS) and so one can build the whole application using few maven commands.

The Kuali configuration management pool manages deployments to DEV and TEST environments in the Amazon cloud. 

1. Dev Environment - Coming soon!
2. Test Environment

OLE is still in the beta phase of development with an installable release expected to be during early 2013. There have been two releases for the user community to experiment with the feature set and performance of the system up to date and the documentation can be found in the sections below;

1. Overall Release Documentation

2. OLE 0.8 Iteration Release Documentation

Developer Setup

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

1. 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. 
2. 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

      <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]</password>
          </server>
        </servers>

   3. Tomcat - OLE is deployed under Tomcat web container. The software can be downloaded from here. Ensure the following jars are in your tomcat.home/lib directory; ojdbc6.jar and mysql-connector-java-5.1.13.jar. 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. 

      Linux

      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.

3. Checking out the codebase - OLE codebase can be checked out from the following SVN location.
4. 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,mysql
         
         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
      4. Module specific configuration file - This is a file that the Rice framework will look for under user.home/kuali/main/dev on the local machine and any properties such as db connection info, application urls etc will be overridden. Copy the following file to your user.home/kuali/main/dev OLE_Rice2-config.xml. Ensure the name of the file is similar to the module name and in this case it is set to OLE_Rice2.
   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
5. Deployment to tomcat
   1. OLEFS - Rename the war file from 4.b.iii to olefs.war and copy it to your local tomcat's webapps folder.
   2. OLELS - Rename the war file from 4.c.iii to olerice2.war and copy it to your local tomcat's webapps folder.
   3. 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"/>

6. 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

   1. localhost:8080/olefs
   2. localhost:8080/olerice2
   3. localhost:8080/oledocstore 

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. 

1. ole.sh - Script to checkout codebase and build to produce the deployable artifacts.
2. 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) )
3. 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

Overriding default properties 

1. OLEFS - In order to override the default properties we need to have a property file created in the right place where the application knows to look for.
   1. From the console change into the project root directory 
   2. cd ole-app/ole-fs
   3. mvn generate-resources -Plocal
      1. This generates a file called ole-fs.properties under user.home/.kuali/ole
2. OLELS
3. OLEDOCSTORE

Overriding default properties contd.

Database Refresh Process/Changes

Database Swaps (MySQL/Oracle)

Performance Tuning

Current coding standards and best practices can be found at https://wiki.kuali.org/display/OLE/Coding+Standards. Even though developers are expected to know these, sometimes the use of code metric tools like PMD, Checkstyle and FIndBugs makes it relatively easy and often aids in code reviews and quick turn around times in identifying potential coding violations. Sonar is an open source platform that just does that i.e. monitors code quality by combining tools such as PMD, FindBugs and Checkstyle etc.

OLE is hooked into Sonar via maven and currently all the modules under OLE get executed on Sonar and metrics reported here





There are few things to look out for that absolutely need to be addressed on a regular basis;

1. Violations : These are indicators in code that need to be reviewed and corrected as soon as possible. Few examples are "empty if stmt", "broken null check" etc.
2. Duplications : As the name suggests, this metric reports redundancy in code and needs to be taken seriously for a reusable and robust codebase.
3. Complexity : This often indicates the level of nesting in a particular method and for readability purposes the lower the number the better it is. There are several design patterns that address this and one of the most common one is the strategy pattern to replace several if-else blocks.
   

# h4. Check out the codebase 

1. 1. Trunk location: https://svn.kuali.org/repos/ole/trunk

2. Building Artifacts

   1. Run the following from the root of the folder where the project was checked out

       mvn clean install -DskipTests=true
      

   2. Copy the following artifacts and place it in the webapps directory of your tomcat installation folder
      1.  

         ole/target/ole-fs-[particular iteration value]-webapp.war; Rename the war to olef.war
         

      2. ole-rice2/ole-rice-webapp/target/ole-rice-webapp-[particular iteration value].war; Rename the war to olerice2.war
         

      3. ole-docstore/ole-docstore-webapp/target/oledocstore.war; Rename the way to oledocstore.war
         

3. Generating the default configuration properties file

   1. Navigate to the ole folder under the main project
   2. Run the following command

      mvn generate-resources -Plocal
      

   3. This will generate a default configuration.properties file under

      ~/.kuali/ole/fs/configuration.properties
      

   4. The default database is mysql and the root password is set to none. You will need to change the root password to the appropriate password as set for your mysql server.

4. Setting up the Database

   1. olefs - navigate to the ole-app folder under the root of the project and run the following command

      The db instance chosen will be the one specified in the configuration.properties under user.home/.kuali/olefs; By default its MySQL.

      mvn clean install -Pdb
      

   2. ole-rice2 - navigate to the ole-rice2/ole-rice-db folder under the project and run the following command

      Ensure the impex.dba.password entry in the mysql.properties under ole-rice2/ole-rice-db/src/main/resources is appropriately set to whatever the password for your mysql server is. By default its set to root.

      mvn clean install -Pdb,mysql
      

   3. ole-docstore - The database schema and appropriate tables gets created when the docstore application starts up as apache jackrabbit manages the setup.

5. Configuration Files - Rice2

   You will need to create a file called common-config.xml under user.home/kuali/main/dev with the following entry

   Paths to the keystore file and the log4j.properties files will need to be updated to reflect a more appropriate location in your system.

   Ensure you change the entry for application.url from localhost to the host ip of the server where you are running the application

   Rice2 Config File Expand source

   <\!-\-
   \\
   &nbsp;&nbsp;&nbsp; Copyright 2005-2012 The Kuali Foundation
   \\
   \\
   &nbsp;&nbsp;&nbsp; Licensed under the Educational Community License, Version 2.0 (the "License");
   \\
   &nbsp;&nbsp;&nbsp; you may not use this file except in compliance with the License.
   \\
   &nbsp;&nbsp;&nbsp; You may obtain a copy of the License at
   \\
   \\
   &nbsp;&nbsp;&nbsp; [http://www.opensource.org/licenses/ecl2.php]\\
   \\
   &nbsp;&nbsp;&nbsp; Unless required by applicable law or agreed to in writing, software
   \\
   &nbsp;&nbsp;&nbsp; distributed under the License is distributed on an "AS IS" BASIS,
   \\
   &nbsp;&nbsp;&nbsp; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   \\
   &nbsp;&nbsp;&nbsp; See the License for the specific language governing permissions and
   \\
   &nbsp;&nbsp;&nbsp; limitations under the License.
   \\
   \\
   \-->
   \\
   <config>
   \\
   &nbsp;
   \\
   &nbsp;&nbsp;&nbsp; &nbsp;<param name="rice.logging.configure">true</param>
   \\
   &nbsp;&nbsp;&nbsp; &nbsp;
   \\
   &nbsp;&nbsp; &nbsp;<\!-\- App specific parameters -->
   \\
   &nbsp;&nbsp; &nbsp;<param name="application.id">olerice2</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="app.code">olerice2</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="app.context.name">${app.code}</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="application.url">[http://localhost:8080/$]{app.context.name}</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="production.environment.code">PRD</param>
   \\
   \\
   &nbsp;&nbsp; &nbsp;<\!-\- Misc parameters -->
   \\
   &nbsp;&nbsp; &nbsp;<param name="institution">rice</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="version">03/19/2007 01:59 PM</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="transaction.timeout">3600</param>
   \\
   &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.url">jdbc:mysql://localhost:3306/OLERICE2</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.username">OLERICE2</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.password">OLERICE2</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.ojb.platform">MySQL</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.platform">org.kuali.rice.core.framework.persistence.platform.MySQLDatabasePlatform</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.driver.name">com.mysql.jdbc.Driver</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.pool.maxWait">30000</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.pool.maxSize">20</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="datasource.pool.minSize">5</param>
   \\
   \\
   &nbsp;&nbsp; &nbsp;<param name="keystore.alias">rice</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="keystore.file">${user.home}/kuali/main/dev/rice.keystore</param>
   \\
   &nbsp;&nbsp; &nbsp;<param name="keystore.password">r1c3pw</param> \|
   
   &nbsp;&nbsp; &nbsp;<param name="dev.mode">false</param>
   &nbsp;&nbsp; &nbsp;<param name="useQuartzDatabase">false</param>
   &nbsp;&nbsp; &nbsp;<param name="Routing.ImmediateExceptionRouting">true</param>
   &nbsp;&nbsp; &nbsp;<\!-\- Kuali parameters -->
   &nbsp;&nbsp; &nbsp;<param name="encryption.key">7IC64w6ksLU</param>
   &nbsp;&nbsp; &nbsp;<param name="kfsLocator.useAppContext">true</param>
   &nbsp;&nbsp; &nbsp;
   &nbsp;&nbsp; &nbsp;<\!-\- Change Configurer Modes to LOCAL -->
   &nbsp;&nbsp;&nbsp; <param name="location.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="coreservice.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="ken.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="kim.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="kew.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="krms.mode">LOCAL</param>
   &nbsp;&nbsp;&nbsp; <param name="ksb.mode">LOCAL</param>
   
   <param name="data.xml.root.location">[enter the user.home directory here]/kuali/main/dev/olerice2/workflow</param>
   <param name="data.xml.pending.location">${data.xml.root.location}/pending</param>
   <param name="data.xml.loaded.location">${data.xml.root.location}/loaded</param>
   <param name="data.xml.problem.location">${data.xml.root.location}/problem</param>
   &nbsp;&nbsp; &nbsp;
   &nbsp;&nbsp;&nbsp; <param name="filter.login.class">org.kuali.rice.kew.web.DummyLoginFilter</param>
   &nbsp;&nbsp; &nbsp;<param name="filtermapping.login.1">/*</param>
   &nbsp;&nbsp; &nbsp;<param name="config.location">classpath:META-INF/common-config-defaults.xml</param>
   
   </config>
   

1. Property Files

2. Running the applications

   1. Now that all the three application war files are copied to your tomcat folder, and the database has been set up for olefs and olerice2, its time to start tomcat
   2. Ensure the JAVA_OPTS have the following entry too for the memory settings; -Xms512m -Xmx1g -XX:MaxPermSize=512m
   3. Accessing the applications
      1. OLEFS - http://hostip:8080/olefs
      2. OLERICE2 - http://hostip:8080/olerice2
      3. OLEDOCSTORE - http://hostip:8080/oledocstore

3. Sample Data and Permissions

   In order for the OLE application to be fully functional, there are permissions and sample data files that need to be ingested. This process is automated and every time the applications are brought up (after a fresh install), the following data is ingested;
   a. Workflows/Permissions
   b. Patrons
   c. Locations
   d. Circulation Policies
   e. YPB Ingest Profile