Development Standalone Rice

Financials development requires a standalone Rice instance.  Here are instructions to setup a standalone rice instance and database to use for development.

Software Requirements

• Java JDK 8
• Maven version 3.3 or higher
• Tomcat version 8 or higher
• Mysql version 5.6
• Mysql JDBC driver version 5.1.25 or higher

Note:  Financials will work with an Oracle 11g or greater database.  It does not work with the Oracle 12 JDBC driver.  If you are using Oracle 12, use the Oracle 11g JDBC driver.  These instructions only cover Mysql but should work with Oracle after making the appropriate changes.

Setup Database

You will need to change some Mysql database settings.  See Development Environment for details on making the configuration changes.

These procedures will create 3 databases in MySql:

• kfs - This database contains Financials tables and no Rice tables.  It is used by Financials when running with standalone Rice.
• rice - This database contains Rice tables only.  It is used by the standalone rice instance.
• unit - This database contains both Financials and Rice tables.  It is used for the unit tests.

Steps

1. Login to Mysql as the root user.  Run these commands to create the databases, users and permissions.

   create database kfs default character set 'utf8' default collate 'utf8_bin';
   create database rice default character set 'utf8' default collate 'utf8_bin';
   create database unit default character set 'utf8' default collate 'utf8_bin';
   
   create user kfs@localhost identified by 'kfs';
   create user kfs@'%' identified by 'kfs';
   
   create user rice@localhost identified by 'rice';
   create user rice@'%' identified by 'rice';
   
   create user unit@localhost identified by 'unit';
   create user unit@'%' identified by 'unit';
   
   grant all on kfs.* to kfs@localhost;
   grant all on kfs.* to kfs@'%';
   
   grant all on rice.* to rice@localhost;
   grant all on rice.* to rice@'%';
    
   grant all on unit.* to unit@localhost;
   grant all on unit.* to unit@'%';
   

2. Create a properties file for LiquiRelational to populate the kfs and rice databases.  Name the file lr-kfs.properties.  Here are the contents:

   datasource.driver=com.mysql.jdbc.Driver
   
   kfs.datasource.ddl.username=kfs
   kfs.datasource.ddl.password=${kfs.datasource.ddl.username}
   kfs.datasource.ddl.url=jdbc:mysql://localhost/${kfs.datasource.ddl.username}
   
   rice.datasource.ddl.username=rice
   rice.datasource.ddl.password=${rice.datasource.ddl.username}
   rice.datasource.ddl.url=jdbc:mysql://localhost/${rice.datasource.ddl.username}
   
   updateDatabaseFullRebuild=true
   updateDatabaseContext=demo

3. Create a properties file for LiquiRelational to populate the unit database.  Name the file lr-unit.properties.  Here are the contents:

   datasource.driver=com.mysql.jdbc.Driver
   
   kfs.datasource.ddl.username=unit
   kfs.datasource.ddl.password=${kfs.datasource.ddl.username}
   kfs.datasource.ddl.url=jdbc:mysql://localhost/${kfs.datasource.ddl.username}
   
   rice.datasource.ddl.username=unit
   rice.datasource.ddl.password=${rice.datasource.ddl.username}
   rice.datasource.ddl.url=jdbc:mysql://localhost/${rice.datasource.ddl.username}
   
   updateDatabaseFullRebuild=true
   updateDatabaseContext=unit

4. Run LiquiRelational for kfs and rice.  Make sure to adjust the paths appropriately.  You must be in the root of the financials project when running this.

   mvn -DskipTests clean package
    
   java -classpath ./kfs-web/target/kfs-web/WEB-INF/lib/*:/Users/user/java/drivers/mysql-connector-java-5.1.36.jar -Dadditional.kfs.config.locations=/Path/lr-kfs.properties org.kuali.kfs.sys.datatools.liquirelational.LiquiRelational
    
   For Windows (using Command Prompt):
   java -classpath ./kfs-web/target/kfs-web/WEB-INF/lib/*;/Users/user/java/drivers/mysql-connector-java-5.1.36.jar -Dadditional.kfs.config.locations=/Path/lr-kfs.properties org.kuali.kfs.sys.datatools.liquirelational.LiquiRelational

5. Run LiquiRelational for the unit test database.  Make sure to adjust the paths appropriately.  You must be in the root of the financials project when running this.

   mvn -DskipTests clean package (you do not need to run this again if you ran it in step 4 without making code changes)
    
   java -classpath ./kfs-web/target/kfs-web/WEB-INF/lib/*:/Users/user/java/drivers/mysql-connector-java-5.1.36.jar -Dadditional.kfs.config.locations=/Path/lr-unit.properties org.kuali.kfs.sys.datatools.liquirelational.LiquiRelational
    
   For Windows (using Command Prompt):
   java -classpath ./kfs-web/target/kfs-web/WEB-INF/lib/*;/Users/user/java/drivers/mysql-connector-java-5.1.36.jar -Dadditional.kfs.config.locations=/Path/lr-unit.properties org.kuali.kfs.sys.datatools.liquirelational.LiquiRelational

Setup Standalone Rice

Steps

1. Download the newest Tomcat 8+ core.  Unzip that to the folder where you would like to run rice.
2. Download spring-instrument-tomcat-3.2.12.RELEASE.jar and put it in the tomcat lib folder.
3. Copy the mysql driver to the tomcat lib folder.
4. Delete everything under the webapps folder.
5. Download the rice server file.  This this link was the most current version of Rice at the time this page was created.  Rename the file to kr-dev.war and copy the file to the webapps folder inside the tomcat folder.
6. Edit the server.xml file in the tomcat conf folder.  Change port 8005 to 8006, port 8009 to 8010 and port 8080 to port 8081.  This is required so this version of tomcat will not interfere with the version of tomcat used to run financials.
7. Create a folder inside tomcat named rice.  Under this folder make the folders plugins, kew_attachments, xml.
8. Copy the rice-config.xml, log4j.properties and rice.keystore files into the rice folder.  Edit the rice-config.xml and make sure paths are correct.
9. Run the SQL here (to update db for Rice 2.6 changes).

10. If you are on Windows, edit the file bin/setclasspath.bat, otherwise bin/setclasspath.sh.  Add a line after the comment.  Adjust the path as necessary:

    bin/setclasspath.sh should have this line added:
     
    export JAVA_OPTS=-Dadditional.config.locations=$CATALINA_BASE/rice/rice-config.xml
    
    bin/setclasspath.bat should have this line added:
     
    set JAVA_OPTS=-Dadditional.config.locations=$CATALINA_BASE/rice/rice-config.xml

Running Standalone Rice

Run catalina.bat run on Windows or catalina.sh run if not.

When tomcats starts up, you can access rice at http://localhost:8081/kr-dev/

Configuring Financials

Financials will need to know about your Rice instance.  You will need to create a properties file and pass the name of that file to Financials using the additional.kfs.config.locations system property.  Here is an example of that properties file:

base.url=http://localhost:8080

rice.server.url=http://localhost:8081/kr-dev
rice.url=http://localhost:8081/kr-dev
rice.ksb.registry.serviceUrl=${rice.url}/remoting/soap/ksb/v2_0/serviceRegistry

keystore.file=/Users/user/git/financials/kfs-core/src/main/config/demo/rice.keystore
log4j.settings.file=/Users/user/kfs/log4j.properties

kfs.datasource.username=kfs
kfs.datasource.password=${kfs.datasource.username}
kfs.datasource.url=jdbc:mysql://localhost/${kfs.datasource.username}
kfs.datasource.validating.query=select 1
kfs.datasource.pool.maxActive=50
kfs.datasource.pool.minIdle=5
kfs.datasource.pool.initialSize=5

kfs.datasource.ddl.url=${kfs.datasource.url}
kfs.datasource.ddl.username=${kfs.datasource.username}
kfs.datasource.ddl.password=${kfs.datasource.password}

rice.datasource.username=rice
rice.datasource.password=${rice.datasource.username}
rice.datasource.url=jdbc:mysql://localhost/${rice.datasource.username}
rice.datasource.validating.query=select 1
rice.datasource.pool.maxSize=50
rice.datasource.pool.minSize=5

rice.datasource.ddl.url=${rice.datasource.url}
rice.datasource.ddl.username=${rice.datasource.username}
rice.datasource.ddl.password=${rice.datasource.password}

# Set this to true the first time you run financials.  It will ingest all the document types.
# After that, set it to false.  Leaving it set to true will make financials startup take
# longer.
updateWorkflowOnStartup=true
updateDatabaseOnStartup=true
updateDatabaseContext=demo
 
workflow.path=classpath:org/kuali/kfs/sys/workflow/parent/*.xml,\
  classpath:org/kuali/kfs/sys/workflow/child/*.xml,\
  classpath:org/kuali/kfs/module/ar/workflow/*.xml,\
  classpath:org/kuali/kfs/module/cam/workflow/*.xml,\
  classpath:org/kuali/kfs/module/cg/workflow/*.xml,\
  classpath:org/kuali/kfs/module/ec/workflow/*.xml,\
  classpath:org/kuali/kfs/module/ld/workflow/*.xml,\
  classpath:org/kuali/kfs/module/purap/workflow/*.xml