Kuali OLE 1.0 Installation Documentation

Kuali Open Library Environment (KOLE) 1.0 can be downloaded directly from maven central or checked out from the svn repository. 

1. Obtaining the software :

1. Directly downloading the deployable units:
   1. olefs-webapp-1.0.0.war : This artifact deals with the financial and library management features and can be downloaded from http://shrub.appspot.com/maven.kuali.org/release/org/kuali/ole/olefs-webapp/1.0.0/
   2. ole-docstore-webapp-1.0.0.war: This deals with the cataloging/indexing and searching of Bibliographic, Holdings and Item data and can be downloaded from http://shrub.appspot.com/maven.kuali.org/release/org/kuali/ole/ole-docstore-webapp/1.0.0/
   3. Both of the above deployable units are needed for KOLE to function properly. 
2. Checking out the codebase from SVN - https://svn.kuali.org/repos/ole/tags/ole-1.0.0/

2. Running the software : 

1. Depending on how the software was obtained, there are certain steps to be followed and are explained below;
   1. Downloaded directly
      1. Copy the war files into your local tomcat folder (goes under the tomcat.home/webapps)
      2. Ensure the following folders under tomcat home are empty for a clean start
         1. logs folder
         2. work/Catalina/localhost
      3. Rename the war files from olefs-webapp-1.0.0.war to olefs.war and oledocstore-webapp-1.0.0.war to oledocstore.war respectively
      4. Create the following folder(s) in your user.home directly
         1. kuali/main/local/olefs-webapp
            1. Create a file named runonce.properties
         2. kuali/main/local/ole-docstore-webapp
            1. Create a file named runonce.properties

      5. runonce.properties file is used to indicate weather the database should be reset during application startup. Typically db needs to be set up for the very first time.

         runonce.properties

          project.db.reset=TRUE

      6. Customize application urls: By default, once the application is deployed, it can be accessed at http://localhost:8080/olefs and http://localhost:8080/oledocstore respectively. But for a local install the URL needs to be updated from localhost to an address that will be accessible publicly. 
      7. Create a file called common-config.xml under user.home/kuali/main/local. This files contains any default parameters that need to be overridden externally. Contents of the file are as follows
         
         1. appserver.url - This value is the URL of the application
         2. Database section - You can comment out the db params that are not in use. For example if you are using Oracle, comment out MySQL portion and vise versa. 
         3. Email Settings: Fill the param values for your local email server. This is critical for the deliver functionality where notices etc have to be sent out to Patrons etc.
            

             

            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>
            <!-- URL's -->
            <param name="appserver.url">http://[Fill me]</param>
            <param name="application.url">${appserver.url}/olefs</param>
            <param name="ole.docstore.url.base">${appserver.url}/oledocstore</param>
            <param name="docSearchURL">${appserver.url}/oledocstore/</param>
            <param name="app.context.name">olefs</param>
            <param name="app.code" />
            
            
            <!-- Database -->
            <param name="db.vendor">[oracle or mysql]</param>
            <param name="jdbc.username">[fill me]</param>
            <param name="oracle.dba.url">[fill me]</param>
            <param name="oracle.dba.username">[fill me]</param>
            <param name="oracle.dba.password">[fill me]</param>
            <param name="mysql.dba.url">[fill me]</param>
            <param name="mysql.dba.username">[fill me]</param>
            <param name="mysql.dba.password">[fill me]</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</param>
            <param name="mail.smtp.auth">true</param>
            <param name="mail.smtp.username">[fill me]</param>
            <param name="mail.smtp.password">[fill me]</param>
            </config>

      8. Run tomcat
   2. Verify application is up and running:

      1. As part of application startup depending on whether the db reset was required, the file runonce.properties under user.home/kuali/main/local/olefs-webapp and user.home/kuali/main/local/oledocstore-webapp should have the following entry;

         runonce.properties

         project.db.reset=COMPLETED

      2. There are also workflow files that get loaded as part of the application start up only the 1st time when the db is in a clean state. These files have the necessary document types, roles and permissions for the application to function out of the box. Further roles/permissions can be configured via the application at a later stage. To verify roles/permissions got ingested properly, there will be the following folders created automatically during application startup
         1. user.home/kuali/main/local/olefs-webapp/workflow/pending - This is the directory where the default files get unpacked
         2. user.home/kuali/main/local/olefs-webap/workflow/loaded - This is the directory where, once the files have been ingested into the DB properly will be moved to upon success.

         3. user.home/kuali/main/local/olefs-webapp/workflow/problem - This is the directory where files will be moved from pending if there was an error in loading. Tomcat logs will have indications of what might have gone wrong.

            Re Ingesting workflow files

            If an event there files didn't get ingested and got moved to the problem directory, there are couple of ways to re-ingest them. 1. Copy the files from the "problem" folder and place it under the "pending" directory. The application  scans every 5 seconds (XmlPollerService) for any files in the "pending" directory and re-ingests them or 2. Stop Tomcat. a. Delete the workflow folder under user.home/kuali/main/local/olefs-webapp. b. Update the "runonce.properties" files to state project.db.reset=TRUE. c. Restart tomcat.

            Resetting the runonce.propeties file will force the application to reset the DB which in turn will force the workflows etc to be re-ingested.

      3. Once the logs indicate that the server is up, open up a browser and try to access the application. You should see Kuali OLE portal.

   3. Building from SVN - Follow the dev guide avail at Developer's Guide for building from SVN.

      Customize localhost

      You will need to customize the app url(s) once the app is ready to be deployed as by default, the app will run on localhost. So follow steps 2.1.a.iv from above.

      MySQL caution

      When running the application with MySQL on a Unix like OS, you will have to set your database to be case-insensitive (otherwise the database will not initialize properly)

      /etc/my.cnf
      
      

      [mysqld]
      
      

      lower_case_table_names=1

       

      Required database library for Tomcat

      The mysql-connector-java-5.1.13.jar must be in your Tomcat install (lib).  Download page here: http://downloads.mysql.com/archives.php?p=mysql-connector-java-5.1&o=other
      

      Windows installation

      When installing OLE on a Windows operating system: 

      1) You need a MySQL database with a root userid that has no password 
      2) You should (completely) remove the database settings from the common-config.xml file (shown above). The install script will default to MySql with a root userid and no password and the install will work.

      This has been reported as a bug.