Kuali Research (KC) for Research Administration is a comprehensive system to manage the complexities of research administration needs from the faculty researcher through grants administration to federal funding agencies. KC is using MIT’s proven COEUS system as its baseline design, updating its technical architecture for vendor independence and integration with other administration systems.
##Installation Prerequisites Maven 3.3.x Java 1.8.x Tomcat 7.x MySQL 5.6.x Git 2.4.x
Instructions The Kuali Research application uses Apache Maven as it's build tool. Inside of Kuali Research's Maven configuration is a list of dependencies. Some of these dependencies may not be available in a publicly available Maven repository. At the very least you will need to install the following projects into your maven repo. These projects may have more than one submodule.
Build Order: The projects required to install Kuali Research must be built in the following order:
- SchemaSpy
- Kuali Research Rice
- Kuali Research API
- Kuali Research S2s Generator
- Kuali Research
Step 1. clone all required projects
cd workspace
git clone https://github.com/kuali/schemaspy
git clone https://github.com/kuali/kc-rice
git clone https://github.com/kuali/kc-api
git clone https://github.com/kuali/kc-s2sgen
git clone https://github.com/kuali/kc
Step 2. determine correct tag versions for dependent projects. Manually search the pom.xml file in the root directory of the Kuali Research project, and find the version numbers for KC Rice, KC Api, Kc S2s Generator, and SchemaSpy
<coeus-api-all.version>x.x.x.x</coeus-api-all.version>
<coeus-s2sgen.version>x.x.x</coeus-s2sgen.version>
...
<rice.version>x.x.x.x</rice.version>
<schemaspy.version>x.x.x.x</schemaspy.version>
Then check out the correct tag before installing.
Cross Project Build Instructions We provide several maven build profiles that may be useful. Some of these profiles are specific to a project while others are available in all projects. When a project specific profile is available, it will be documented in the build step. The following are a list of profiles available in all projects:
GRM Profile: When building Kuali Research Projects you should turn the grm maven profile off as it is on by default. You can do this by sending the following system parameter grm.off on the command line.
mvn clean install -Dgrm.off=true
Enforcer Profile: When building Kuali Research Projects you can turn the enforcer profile on as it is off by default. This will turn on the maven enforcer plugin and fail the build if certain project quality rules are violated.
mvn clean install -Penforcer
jdeps Profile: When building Kuali Research Projects you can turn the jdeps profile on as it is off by default. This will turn on the jdk jdeps tool and fail the build if internal jdk apis are detected.
mvn clean install -Pjdeps
Error Prone Profile: When building Kuali Research Projects you can turn the error-prone profile on as it is off by default. This will turn on the strict error prone compiler and fail the compile step if certain source code errors are detected.
mvn clean install -Perror-prone
enforce-project-quality Property: This property turns on the enforcer, jdeps, and error prone profiles. These profiles are off by default.
mvn clean install -Denforce-project-quality
Disable Javascript Frontend Builds: This property disables building javascript related artifacts and the api documentation. This is not recommended for a production environment, but can be preferred during development as it can speed up builds significantly. The javascript build is enabled by default.
mvn clean install -Dbuild-jsfrontend-node.off=true
Disable cleaning javascript artifacts: This property disables cleaning up after the javascript build process. By default node, npm, and node_modules are cleaned during mvn clean. By using this flag you can disable this step which can save significant time during a non-production build. This is not recommended for a production environment.
mvn clean install -Dclean-jsfrontend-node.off
All Kuali Research projects use standard maven conventions to build and install artifacts. The following documents how to install source, javadoc, and primary artifacts for each maven projects.
Source and Javadoc jars: When building Kuali Research Projects it may be helpful to also build source and javadoc jars. These jars can be consumed by tools such as debuggers. Note: due to changes in the javadoc tool in Java 8, you may need to execute the compile phase before attempting to create a javadoc jar.
mvn clean compile source:jar javadoc:jar install
Step 3: Build SchemaSpy Check out the correct schemaspy version and run maven clean install.
cd schemaspy
git checkout tags/schemaspy-xxxx.xx
mvn clean compile source:jar javadoc:jar install -Dgrm.off=true
Step 4: Build Kuali Research Rice Checkout the correct version of Kuali Research rice and install.
cd ../kc-rice
git checkout tags/rice-x.x.x.xxxxx.xx
mvn clean compile source:jar javadoc:jar install -Dgrm.off=true
Wait until coeus-api has installed successfully before moving to the next step.
Step 5: Build Kuali Research Api Checkout the correct version of Kuali Research api and install.
cd ../kc-api
git checkout tags/coeus-api-xxxx.xx
mvn clean compile source:jar javadoc:jar install -Dgrm.off=true
Wait until coeus-api has installed successfully before moving to the next step.
Step 6: Build Kuali Research S2sGen Checkout the correct version of coeus-s2sgen and install
cd ../kc-s2sgen
git checkout tags/coeus-s2sgen-xxxx.xx
mvn clean compile source:jar javadoc:jar install -Dgrm.off=true
Wait until coeus-s2sgen has installed successfully before moving to the next step.
Step 7: Build Kuali Research Installing Kuali Research
Install without Oracle support
cd ../kc
mvn clean compile source:jar javadoc:jar install -Dgrm.off=true
Oracle Profile: If using an Oracle database make sure oracle profile is used to insure Oracle specific jars are added to the classpath. Application will fail to start up if the Oracle jar is not added.
mvn clean install -Dgrm.off=true -Poracle
Integration Tests: This runs the integration tests. This profile requires a properly configured integration test database and configuration.
mvn clean install -Dgrm.off=true -Pitests
Precompile jsps: This precompiles the Kuali Research jsps for Tomcat 7. This is useful to verify the absence of compile errors in jsps while the Kuali Research Application is being built. Precompilation also helps the initial page load time for all jsps.
mvn clean install -Dgrm.off=true -Pprecompile-jsp-tomcat-7
Include Mysql Driver: This adds the mysql driver to the classpath and is on by default. This profile can be turned off by sending the following system parameter grm.off on the command line.
mvn clean install -Dgrm.off=true -Pinclude-mysql-driver
Include Oracle Driver: This adds the oracle driver to the classpath and is on by default. This profile can be turned off by sending the following system parameter grm.off on the command line.
mvn clean install -Dgrm.off=true -Pinclude-oracle-driver
**Dev Profile:**When developing with KC there are some features that are useful only for development purposes. In order to enable these features you should enable the dev profile. Currently the dev profile only provides the p6spy dependency. See the section below on Configuration for how to use this feature.
mvn clean install -Pdev
**Node Clean:**When building our api documentation, our build process will download node.js and various node dependencies. By default, these artifacts are deleted on every mvn clean execution. You can avoid this clean step by sending the following system parameter clean-jsfrontend-node.off on the command line. This is useful to speed up project builds by avoiding the installation node.js on subsequent clean install iterations.
mvn clean install -Dclean-jsfrontend-node.off
System Dependent Requirements: Kuali Research is now using some node and npm dependencies as part of its build process. These dependencies have all been designed to be downloaded, installed and run without any additional system level requirements, but there are some system specific requirements that cannot be managed by our build process. This seems to primarily affect Windows, but additional systems may be affected depending on local configuration. If you are seeing errors attempting to build Kuali Research that relate to node or npm, please see the failing node project's documentation for what might be expected to be installed on your system. For example, we currently have a dependency on a node project called drafter that builds our api documentation. From their Windows specific documentation, drafter appears to require Visual Studio Express 2012 and Python 2.7. These types of dependencies are beyond our control, but we strive to make the build process as simple as possible.
Step 8: Install Spring Instrumentation
For Tomcat: Download and install tomcat spring instrumentation in the tomcat lib directory Configure the tomcat spring instrumenting classloader in the tomcat context.xml file
<Context>
<!-- ...snip... -->
<Loader loaderClass="org.springframework.instrument.classloading.tomcat.TomcatInstrumentableClassLoader"/>
<!-- ...snip... -->
</Context>
Otherwise: Download and configure java agent in at the jvm level.
-javaagent:/Users/user/.m2/repository/org/springframework/spring-instrument/3.2.13.RELEASE/spring-instrument-3.2.13.RELEASE.jar
Note: Application will fail to start up in spring instrumentation is not installed correctly.
Step 9: Install Graphviz
Download and install Graphviz.
Note: In order for SchemaSpy to be fully functioning, graphviz must be installed and the dot binary accessible on the system path.
##Creating DB
Kuali Research supports MySQL 5.6 and Oracle. We recommend MySQL though as that is the database we develop and support internally and are more easily able to respond to problems with that database. If you choose to use Oracle, please be sure to use the latest Oracle driver version 12 or higher. The version 12 driver will work correctly with older Oracle database servers such as version 11. The build profiles include-mysql-driver and include-oracle-driver can be used to include the database drivers in the application.
Configuration Information
This section contains some useful information about configuring the Kuali Research Application. This is not an exhaustive list of configuration options or a tutorial on configuration. For more options see coeus-impl/src/main/resources/META-INF/kc-config-defaults.xml inside the Kuali Research Application source or the Kuali Rice public documentation.
SchemaSpy: The kc.schemaspy.enabled config param turns SchemaSpy on or off. SchemaSpy is a great tool for visualizing the Kuali Research database and is generally useful on server instances. It does create additional CPU upon application startup while gathering database information. After information gathering is complete, CPU usage will go back to normal as all SchemaSpy information is cached as static content. It is recommended to disable SchemaSpy on developer machines and during integration test runs.
<param name="kc.schemaspy.enabled">false</param>
Monitoring The kc.monitoring.enabled config param turns Monitoring on or off. Monitoring is done through Java Melody and is great for learning about the runtime characteristics of the Kuali Research Application. Java Melody has low overhead and in general can be left on.
<param name="kc.monitoring.enabled">false</param>
P6Spy P6Spy can be a useful tool during development that will allow you to view sql statements that are generated and executed against the database in real time. In order to use it in KC you will need to enable the dev profile mentioned above as well as reconfigure your database connection string and driver similar to the below sample. All other kc-config.xml options should remain the same. Additionally you will need to configure the spy.properties file found in coeus-webapp/src/main/resources/ to specify the correct original driver and potentially the appender method if StdOut is not sufficient.
<param name="datasource.url">jdbc:p6spy:mysql://localhost:3306/kcdev</param>
<param name="datasource.driver.name">com.p6spy.engine.spy.P6SpyDriver</param>