Skip to end of metadata
Go to start of metadata
Help Improve Content
Like the Kuali Student (KS) software, the supporting documentation belongs to the Community. If you see errors or missing information in the KS documentation, or if you have a suggestion for improving it, we welcome your input or help. You have a few options:

(question) Need Help? If you have any questions about troubleshooting your installation, please join our Implementation Users Group list serv. Information about the IUG can be found here. Once joined, you can access our forum archives as well as ask questions as you have them. Please also refer to the CM 2.0 Troubleshooting page that provides information about specific issues you may encounter during or after installation.

Introduction

The goal of this guide is to get you up and running with the reference implementation of KS CM 2.0 with minimal steps and overhead following the KS-Bundled deployment strategy. In this deployment strategy, all Kuali Student modules and a preconfigured implementation of Kuali Rice are in a single WAR file. This deployment lends itself well to developers and analysts who want to get something up quickly for customization, testing and analysis.  This setup will get a server running but is not intended as the starting point for implementation but as a way to set up a local sandbox for evaluation purposes.

If this deployment is intended for enterprise use, the community recommends following the KS-Distributed deployment strategy where all Kuali Student modules are in one WAR file and a preconfigured Kuali Rice implementation resides in a separate WAR file. For information on the distributed deployment, please see the KS CM 2.0 Implementation and Deployment Guide.

For more on deployment strategies, see Implementation and Deployment Overview.

1. Prerequisite Knowledge

Familiarity with the following technologies is a necessary prerequisite for installing and deploying Kuali Student Curriculum Management.

  • Source code management using Subversion
  • Building and assembling of projects using Maven
  • Deploying WAR files using Tomcat

2. Set Up the Database

The Curriculum Management database extracts are provided as one combined schema. To setup the database, the following tools are required:

  • Subversion 1.7.x: See http://subversion.apache.org/packages.html to download a Subversion client
  • Oracle or Oracle XE: You will need to install version 10g or later of Oracle or Oracle XE (Oracle Express) locally or be given the password for the Oracle user "SYS". The Oracle user "SYS" has the permissions necessary for setting up the Kuali Student database.
  • JDK (Java Developer Kit) 6

    Icon

    JDK 7 is not supported at this time

  • Maven 3.0.4 or later

Install the Oracle JDBC Driver in maven's local repository

Oracle licenses their JDBC driver in a way that prevents it from being publicly available. You will need to install the jar in your local Maven repository so that it is available to Maven when loading data.

  1. Obtain a copy of ojdbc14.jar
    • The correct version to use is available here or you can download it from Oracle (requires creating an account on OTN)
    • If you have installed Oracle Express Edition locally, this jar file is already on your local system at:

  2. Use the Maven Install Pluginto copy ojdbc14.jar into your local maven repository.

    If the jar is installed correctly, you should see output similar to the following:

Load the Kuali Student Bundled Data

The ks-bundled-db module contains the learning unit management database and the Rice database with KS Curriculum Management configuration and workflow data.

  1. Checkout the data sets module for the 2.0.3 tag:

  2. Change to the directory for the bundled data set:

  3. Review the Maven Impex properties listed in the table below. At a minimum, you will need to supply a value for the ks.impex.dba.password property in the next step.

    Property

    Default Value

    Description

    ks.impex.url

    jdbc:oracle:thin:@localhost:1521:XE

    The JDBC url for the database. Override as needed.

    ks.impex.dba.username

    SYS AS SYSDBA

    Do not override! This is a specific Oracle DBA user with the permissions needed to create/drop Oracle schemas and grant the permissions needed for Kuali Student.

    ks.impex.dba.password

    change_on_install

    Default password for the SYS user when Oracle is installed. Override this with the password for the SYS user for your Oracle instance

    ks.impex.username

    KSBUNDLED

    The Oracle user the Kuali Student application will be connecting to the database as.

    ks.impex.password

    KSBUNDLED

    The password for the Oracle user the Kuali Student application will be connecting as.

    ks.impex.driver

    oracle.jdbc.driver.OracleDriver

    JDBC driver for Oracle.

    ks.impex.sql.drop

    SQL to drop an Oracle user.
    This drops the user as well as any objects owned by the user (tables, indexes, sequences, views, etc).
    This ensures that the Impex process is repeatable by guaranteeing that any previously created data has been removed and that the Impex process will be starting with an empty database.
    Ignore the error if the user does not exist.
    Execution of this SQL is tied to the Maven ""clean"" phase by default.

    ks.impex.sql.validate

    SELECT SYSDATE FROM DUAL

    Simple query for validating a JDBC connection. Execution of this SQL is tied to the Maven "validate" phase by default.

    ks.impex.sql.initialize

    SQL for creating an Oracle user and granting the permissions needed for Kuali Student. Execution of this SQL is tied to the Maven ""initialize"" phase by default.

  4. Validate that Maven can connect to your Oracle instance as follows:

    If validation fails with the error “com.oracle:ojdbc14:jar:10.2.0.3.0”, make sure you have installed the JDBC driver as described in section 1.2 Install the Oracle JDBC Driver above. A successful result is indicated by output similar to the following:

  5. Load the dataset as follows:

3. Download and Configure Kuali Student Curriculum Management 2.0

These instructions explain how to download a single WAR file to install all Kuali Student modules and a preconfigured implementation of Kuali Rice. If instead you would like to deploy the Kuali Student modules and Kuali Rice from separate WAR files in distributed fashion, please see the KS CM 2.0 Implementation and Deployment Guide.

Download the WAR File:

For the bundled configuration, download the file:

Create Property File(s) for WAR Configuration

You will need to create a property file for the WAR file. You will not need to modify the WAR to configure the application. By default the application will look for the property files in the following location:

  • ${user.home}/kuali/main/${environment}/ks-with-rice-bundled-config.xml

where

  • ${user.home} will be the home directory of the user the server runs as.
  • ${environment} defaults to dev, but can be changed with a system parameter.

If it is not possible to store the property file in the user's home directory, an alternate location can be defined by setting a system parameter named additional.config.locations. The filename should be included---for example, -Dadditional.config.locations=/custom/location/config_file_name.xml

Use the following format for the property file (ks-with-rice-bundled-config.xml config file is shown in this example) making sure to substitute the proper values for Oracle SID, keystore.file and the datasource username and password (if you chose non-default values for ks.impex.username in the previous impex loading step):

ks-with-rice-bundled-config.xml example

You can obtain a copy of the rice.keystore file to place in a path in your file system from here or from within the war at WEB-INF/classes/rice.keystore.

Supported Properties for ks-with-rice-bundled

NOTE: When using the ks-with-ricebundled module, the settings for ks.lum.datasource.* and ks.core.datasource.* default to the values of datasource.*

Property

Description

Use

appserver.url

This is the url for the root of the appserver (does not include the context name). ex: http://my.school.edu:1234

required

app.context.name

The name of deployed context

required

keystore.file

The file full path to the rice keystore file, currently located in the WAR WEB-INF/classes/rice.keystore

required

datasource.url

The jdbc connection string for the rice datasource

required

datasource.username

username for rice datasource

required

datasource.password

password for rice datasource

required

ks.lum.datasource.url

jdbc connection string for the lum datasource

optional

ks.lum.datasource.username

lum datasource username

optional

ks.lum.datasource.password

lum datasource password

optional

ks.core.datasource.url

jdbc connection string for the core datasource

optional

ks.core.datasource.username

core datasource username

optional

ks.core.datasource.password

core datasource password

optional

log4j.settings.path

This changes the log4j config file that is used, should include the filename. The default log4j settings are in the project here

optional

ks.core.datasource.minSize

Set the minimum db pool size for the core datasource.

optional

ks.core.datasource.maxSize

Set the maximum db pool size for the core datasource.

optional

ks.core.jpa.showSql

Set hibernate statement logging for the core datasource (true or false).

optional

ks.lum.datasource.minSize

Set the minimum db pool size for the lum datasource.

optional

ks.lum.datasource.maxSize

Set the maximum db pool size for the lum datasource.

optional

ks.lum.jpa.showSql

Set hibernate statement logging for the lum datasource (true or false).

optional

datasource.minSize

Set the minimum db pool size for the rice datasource.

optional

datasource.maxSize

Set the maximum db pool size for the rice datasource.

optional

additional.config.locations

define location of additional configuration parameter files (use a system parameter)

optional

ks.institutional.context

defines the location for a spring context file which can be used to override or add beans/customizations

optional

ks.authentication.context

sets the spring context to be used to configure spring security

optional

ks.default.security.cas.serverAddress

set the url of your CAS server if using one

optional

Configuring CAS with KS Curriculum Management (Bundled Rice)

To configure KS Curriculum Management to use your CAS server for authentication, set the following properties:

   <param name="ks.default.security.cas.serverAddress">CASLoginURL</param>
   <param name="ks.authentication.context">classpath:ks-spring-security-cas.xml</param>

where CASLoginURL is the URL for your CAS server login (for example, *https://login.ks.edu/cas*

If your CAS server is using the Proxy Mechanism or if you want to enable it, set the following property:

   <param name="ks.default.security.cas.useCasProxyMechanism">true</param>

Note: You must configure the server for SSL if you want to use the Proxy Mechanism.

4. Deploying the Application in Tomcat

To deploy the application in Tomcat perform the following steps (if you are not using Tomcat as the application server, you will need to perform appropriate steps pertinent to that server).

  1. Add the following memory settings to your server configuration

    For Unix, add these settings to CATALINA_OPTS environment variable for the user starting tomcat.

  2. Add the Oracle JAR to your Tomcat server's classpath (typically done by copying the JAR in TOMCAT_HOME/lib directory).
  3. Copy the WAR file into TOMCAT_HOME/webapps (it is recommended that the version number be removed from the war filename before copying).
  4. Start Tomcat

5. Access the Application

To access the application, go to the appserv.url that you specified in your property file.

You should be presented with the login screen. By default, the administrative user name is "admin" and the password is "admin".

NOTE: An index page will be available at http://yoururl.edu/warname/ where warname is the name of the WAR file you deployed.

To find other predefined users, go into Rice, click the Administration tab, then click the person link to search for usernames. The default password for all users is the username.

6. Source Code

The source code for KS Curriculum Management 2.0 releases can be download here.

  • No labels

3 Comments

  1. Hindsight after completing my "sandbox" installation of Kuali and inching my way into reading the Student Developer Guide, I'm wishing I scanned through that guide.  Particularly 2. Set Up the Development Environment.

    System Requirements are posted on that primary link which is not stated in this guide.

    Mind you not all the instructions apply (For example: in Developer guide, it directs you to install Java SE 7 SDK or higher whereas for quickstart you need to use JDK 6)  The level of detail in section 2 (Particularly 2.1 Install JDK2.2 Install Maven, 2.4 Install and Configure Oracle XE, and 2.6 Install Tomcat Server) is very helpful.

    The tricky part is knowing what of Section 2 not to use (ie using JDK6 instead of JDK 7 and ojdbc14.jar instead of ojdbc6_g.jar)

  2. Haroon Rafique and Larry Symms, perhaps this is a comment that you all can consider in revisions of the material to make sure the developer guide and the quickstart guide make sense together?

    Thanks!
    Cheryl 

  3. My personal notes for installing Kuali CM on Windows 7 32 bit system are outlined as follows:

    Install Subversion for Windows
    Install Oracle Database Express (Free version)
    Install JDK 6
    Setup Tomcat
    Setup Maven
    Load the Kuali Student Bundled Data
    Download and Configure Kuali Student

    I have a rtf attachment posted in forums under "Help with Kuali QuickStart Installation". The attachment is toward the end of the thread.

    There have been some updates to the quickstart instructions since then, so if you do use my notes, please compare my notes against the current quickstart instructions and update your copy of my notes as necessary (for example my notes are based on ks-with-rice-bundled-2.0.1-cm.war; current version is w.0.w-cm.war)

    I wanted to add more notes to the "Help with Kuali QuickStart Installation" thread but was unable to do so so I'll add them here.

    My ks-with-rice-bundled-config.xml file which I have stored in C:\users\mokumaadm\Kuali\main\dev has the following information in it:

    <config>
       <param name="ks.ignore.rice.login">true</param>
       <param name="db.vendor">oracle</param>

       <param name="appserver.url">http://localhost:8888</param>
       <param name="app.context.name">ks-with-rice-bundled</param>

       <param name="datasource.url">jdbc:oracle:thin:@localhost:1521:XE</param>
       <param name="datasource.username">KSBUNDLED</param>
       <param name="datasource.password">KSBUNDLED</param>

       <param name="ks.lum.datasource.url">jdbc:oracle:thin:@localhost:1521:XE</param>
       <param name="ks.lum.datasource.username">KSBUNDLED</param>
       <param name="ks.lum.datasource.password">KSBUNDLED</param>

       <param name="ks.core.datasource.url">jdbc:oracle:thin:@localhost:1521:XE</param>
       <param name="ks.core.datasource.username">KSBUNDLED</param>
       <param name="ks.core.datasource.password">KSBUNDLED</param>

      <param name="keystore.file">C:\users\mokumaadm\Kuali\main\dev\rice.keystore</param>
    </config>

    I'm not sure if it is the lum or core parameter set that enables the RICE menu option from the "Select an area" drop down menu.