KOLE 1.5.x Installation Guide

The latest stable patch release of KOLE is 1.5.8 version released on February 5th, 2015. The table below highlights some of the differences in the 1.5.0 and the consecutive patch versions.

The guide below will describe in as much detail as possible the process of building one of the 1.5 tags  and database migration processes for in between versions. 

1. Pre-requisites:
   1. Hardware: Kuali OLE can be built on both windows and linux platforms. The hardware specs will differ from institution to institution, but the default cloud settings where the codebase is deployed on a regular basis is as follows;
      1. Amazon EC2 instance (type m1.medium)
         1. AMD 64 bit
         2. Dual core
         3. 7.5 GB RAM
         4. 840 GB HDD
   2. Software:
      1. Building the application
         1. Maven 3
         2. Java 7
         3. svn client
      2. Running the application
         1. Apache tomcat 6 or 7
         2. MySQL 5.5 or greater

         3. or Oracle 11g

            Configure Tomcat and MySQL/Oracle

            To correctly configure Tomcat and MySQL/Oracle follow the section "Required Software" in the Developer Installation Guide.
2. Checking out the deployable units: Depending on how you intend to run KOLE you can do the following;
   1. Install defaults and deploy the war(s): This is recommended for those who simply want to get the application up and running with the default and demo data.
      1. Checkout the olefs.war from:http://shrub.appspot.com/maven.kuali.org/release/org/kuali/ole/olefs-webapp/${version.number}/olefs-webapp-${version.number}.war (Rename it olefs.war before deploying)
      2. Checkout the oledocstore.war from:http://shrub.appspot.com/maven.kuali.org/release/org/kuali/ole/ole-docstore-webapp//${version.number}/ole-docstore-webapp-${version.number}.war (Rename oledocstore.war before deploying)
      3. Skip to step #5
   2. Customize the build: This is ideal for implementors or others who want to start with a base OLE (without demo datasets) and then add their data.
      1. Checkout the codebase from https://svn.kuali.org/repos/ole/tags/${tag.number}; Here tag.number is the stable release version number .
      2. Build it using the following maven command from the root directory of the project location i.e OLE_DEVELOPMENT_WORKSPACE_ROOT
         1.  Expand source

            mvn clean install -DskipTests=true

         2. The above command will output two war files under
            1. ${project.root.location}/ole-app/olefs/target/olefs.war
            2. ${project.root.location}/ole-docstore/ole-docstore-webapp/target/oledocstore.war
3. Loading bootstrap only for sandbox purposes

   1. Script for building the bootstrap sql

      #!/bin/bash
      cd ${OLE_DEVELOPMENT_WORKSPACE_ROOT} 
      mvn clean install -DskipTests=true
      cd ${OLE_DEVELOPMENT_WORKSPACE_ROOT}/ole-app/ole-db/ole-impex
      mvn clean install -Psql -Dimpex.scm.phase=none
      cd ${OLE_DEVELOPMENT_WORKSPACE_ROOT}/ole-app/ole-db/ole-liquibase/ole-liquibase-changeset
      mvn clean install -Pbootstrap-sql-only,mysql -Dimpex.scm.phase=none

   2. You can skip to step 5.

4. Loading local data (institution specific): This applies only if you are doing step 2.b.ii
   1. If you want to load your own values for the various reference tables, you will need to first populate them as per the documentation at Impex, Bootstrap, Demo and Local Data (points #7, #8, #9 b or #9 c). Once the data has been made available in .csv files under the appropriate folder, run the following maven commands to output the sql that we will later use to load the database with. The process automatically takes care of generating the right sql for MySQL and Oracle
      1.  Expand source

         cd ${OLE_DEVELOPMENT_WORKSPACE_ROOT}/ole-app/ole-db/ole-liquibase/ole-liquibase-changeset
         mvn clean install -Psql,mysql -Dimpex.scm.phase=none
         mvn clean install -Psql,oracle -Dimpex.scm.phase=none
          

      2. This will generate sql for the data files that you have which the ole build process can later use while setting up the database.

      3. To load the institution specific data after the above executions, execute the following command:

          Expand source

         cd ${OLE_DEVELOPMENT_WORKSPACE_ROOT}/ole-app/olefs
         [For MySQL]
         mvn initialize -Pdb -Djdbc.dba.username=root -Djdbc.dba.password=root
          
         [For Oracle]
         mvn initialize -Pdb,oracle -Djdbc.username=OLE -Doracle.dba.url=jdbc:oracle:thin:system/manager@localhost:1521:XE

      4. Ensure there is a default user in the system. You could create using the sql file in JIRA-7246. Further need to update the web.xml under olefs and replace the defaultUser from ole-quickstart to the newly created user. (If you used ole-quickstart, then there is no need to update the web.xml)
         
         

5. Customizing default parameters
   1. If you are running on a local server where access via localhost is sufficient for local testing and you use the defaults for database username and password, then there is no need to customize the defaults.
   2. For those who want to make the application available to the external public or use their own database username and password will need to override few defaults. Detailed information is available at Externalizable Parameters and pay attention to the entries in ${user.home}/kuali/main/local/common-config.xml. An example is provided here (DEV environment)
      1. common-config.xml Expand source

         <!--
         Copyright 2004-2013 The Kuali Foundation Licensed under the Educational Community License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.opensource.org/licenses/ecl2.php Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
         -->
          <config>
          
         <!-- Generic URL's -->
         <param name="appserver.url">[IP address]</param>
         <param name="application.url">${appserver.url}</param>
         <param name="ole.docstore.url.base">[IP]/oledocstore</param>
         <param name="docSearchURL">${ole.docstore.url.base}</param>
          
         <!-- MySQL Database (The default jdbc.username = OLE and jdbc.password = OLE) -->
         <param name="db.vendor">mysql</param>
         <param name="jdbc.username">[fill me]</param>
         <param name="jdbc.password">[fill me]</param>
         <param name="mysql.dba.url">jdbc:mysql://localhost:3306</param>
         <param name="mysql.dba.username">[mysql dba username]</param>
         <param name="mysql.dba.password">[mysql dba password]</param>
          
         <!-- Oracle Database -->
         <!--
         <param name="db.vendor">oracle</param>
         <param name="jdbc.username">[fill me]</param>
         <param name="jdbc.password">[fill me]</param>
         <param name="oracle.dba.url">[db url]</param>
         <param name="oracle.dba.username">[dba username]</param>
         <param name="oracle.dba.password">[dba password]</param>
         -->
          
         <!-- Email -->
         <param name="mail.debug">false</param>
         <param name="mail.smtp.host">[Fill me]</param>
         <param name="mail.smtp.port">465</param>
         <param name="mail.smtp.ssl.enable">[true or false, choose one]</param>
         <param name="mail.smtps.auth">[true or false, choose one]</param>
         <param name="mail.smtp.username">[Fill me]</param>
         <param name="mail.smtp.password">[Fill me]</param>
          
         </config>

          
6. Deploying to the server:
   1. If this is the first time starting installing the application or you would like to reload the OLE database after a change (typically if you ran the bootstrap or demo or institution profiles to generate new SQL), then follow the steps before deploying and starting tomcat.
      1. Create a file called runonce.properties under ${user.home}/kuali/main/local/olefs-webapp

      2. Contents of the file are as below:

         project.db.reset=TRUE

      3. What this enables is, during the application startup, a spring component will read the value of the project.db.reset and if its "TRUE" then starts the db initialization process automatically. It will automatically be updated to "COMPLETED" when db reset is done.

   2. Once you have the final deployable artifacts olefs.war and oledocstore.war; you can place it in your app server and restart.
7. Testing the application
   1. To access the web apps, http://[host]/olefs and http://[host]/oledocstore should bring the apps up; Ofcourse this is assuming you have two deployables in one single instance. If you haven't customized any parameters then the url will be http://localhost:8080/olefs and http://localhost:8080/oledocstore (assuming tomcat is on 8080)
   2. Type "admin" in the login box; No password required.
8. Upgrades: When upgrading if there are any database changes, they can easily be applied after the above steps have completed. 
   1. Upgrade sql: Depending on which version you are working on, the location is ${SVN.LOCATION}/ole-app/ole-db/ole-sql/ole-liquibase-upgrade-sql/src/main/resources/org/kuali/ole/sql/mysql/
   2. There is mysql and oracle folders with the respective sql.

   3. You can take the sql and manually apply it on your database.

      Remember

      The sql will have some "DATABASECHANGELOG" statements which you can ignore and execute the rest.

Setting OLE Up Behind a Reverse Proxy

If you are experiencing HTTP 501 ("Method Not Implemented") errors, this may be the cause.  Check your Apache version and error logs for messages such as "ajp_marshal_into_msgb - No such method PATCH".

Possible fixes:

1. Use mod_proxy_http instead of mod_proxy_http in your proxy setup.

2. Use at least Apache 2.4.4 with mod_proxy_ajp

3. (Unverified) Use mod_jk instead of mod_proxy_ajp

Configuration for handling Incident Report Email Notification

The Incident Report screen allows an User Input field where system users can add information and submit. This is delivered to a pre-configured email address for further analysis. The following are the parameters that are to be added to make this functional.

The 'From' address on the notification email would be the email address from the contact information of the system user posting the Incident report.

The parameters are added to olefs-config-defaults.xml file.

<param name="mail.transport.protocol" override="false"></param>	<!-- The mail protocol, usually smtp -->
<param name="ole.fs.mail.server"></param> <!-- The mail server -->
<param name="ole.fs.email"></param> <!-- The 'To' address for notifications -->
<param name="ole.fs.exception.email"></param> <!-- The 'To' address for exceptions -->
<param name="mail.debug">false</param>
<param name="mail.smtp.host">${ole.fs.mail.server}</param> <!-- The mail server -->
<param name="mail.smtp.port"></param>
<param name="mail.smtp.ssl.enable"></param>
<param name="mail.smtp.auth"></param>
<param name="mail.smtp.username"></param>
<param name="mail.smtp.password"></param>
<param name="mail.relay.server">${ole.fs.mail.server}</param>
<param name="mail.smtp.host">${ole.fs.mail.server}</param>
<param name="kcb.smtp.host">${ole.fs.mail.server}</param>
<param name="mailing.list.batch">${ole.fs.email}</param>
<param name="kr.incident.mailing.list">${ole.fs.exception.email}</param>
<param name="nonproduction.notification.mailing.list">${ole.fs.email}</param>
<param name="KualiExceptionIncidentServiceImpl.REPORT_MAIL_LIST">${ole.fs.exception.email}</param>

The Incident Report Email Notification currently works only in Kuali Nervous System (KNS) screens and not in the newer Kuali Rapid Application Development (KRAD) screens. This is probably due to a Rice bug which would likely be fixed in Rice v2.4.