Skip to end of metadata
Go to start of metadata

Agenda

Location: Exec 226

Wednesday

 

8:15 - 8:30

Welcome & Class Introduction

8:30 - 11:45

Installing & deploying KC; embedded mode configuration

1:00 - 2:15

Configuring Authentication (CAS / LDAP)

2:30 - 4:30

Kuali Nervous System Development 1

Thursday

 

8:30 - 11:45

Kuali Nervous System Development 2

1:00 - 3:00

Strategies for maintaining local customizations

3:15 - 4:45

Users and Roles: Kuali Identity Management

Friday

 

8:30 - 10:15

Routing and Approvals: Kuali Enterprise Workflow

10:30 - 12:00

Business Rules Authoring: Kuali Rules Management System

12:00 - ?

Leftovers and questions

Introduction

Welcome to the KC bootcamp! These instructions will help you set up your environment for the first time in order to be able to run KC and start on customizing it for your environment. This guide will cover environment setup, database setup, code checkout and configuration, and running the server.

Software Installation/Configuration

We use Java, Maven, and Eclipse to develop the application.  The following will guide you in setting up these programs for KC.

Java Development Kit (JDK)

A JDK is required when running Eclipse (not a JRE) due to a Maven requirement. Eclipse and Maven need to be run using Java 1.6.

Maven

We use Maven to handle all of our library dependencies to make it easier for everyone to get set up quickly.

  • Obtain Maven (3.0.3)
    • On Linux, a package manager installation is acceptable as long as the proper version is installed
    • Otherwise, download Maven from http://maven.apache.org/download.html and extract it into a directory with no spaces. Make note of this directory (<M2_HOME>)
  • Add an environment variable, <M2_HOME> with the location noted above
  • Add Maven to your system path
    • On Windows, add %M2_HOME%\bin
    • On Linux/Mac, add $M2_HOME/bin
  • Adjust your repository settings
    • Find or create the file <USER_HOME>/.m2/settings.xml
    • Make sure that the path to your repository has no spaces
      • By default, Maven will store its repository in your user home directory
      • On Windows, this is bad since the path has spaces. Use the following instead
Icon

Mac users may need to create a env var on their system either via an environment tool like RCEnvironment or a global launchd.conf file (requires reboot to take effect)

For more info see: http://stackoverflow.com/questions/135688/setting-environment-variables-in-os-x).

Eclipse

Any distribution based on Helios (3.6 series) is fine, although we recommend the Eclipse IDE for Java Developers distribution to start out with.

  • Obtain Eclipse
  • Edit <IDE_HOME>/eclipse.ini to add/modify the following settings
  • Start Eclipse
  • The Maven plugin for Eclipse (m2eclipse) will be installed using Eclipse Software Update
    • Go to Help > Install New Software and enter http://m2eclipse.sonatype.org/sites/m2e
    • When the list loads, check Maven Integration for Eclipse and complete the install procedure
    • Restart Eclipse.
    • Go to Window > Preferences > Maven > Installations and add and select the Maven installed previously
  • Install and configure SVN
    • Go to Help > Install New Software and choose the software site for your Eclipse version (typically http://download.eclipse.org/releases/<release.name>) from the dropdown
    • Expand Collaboration and check Subversive SVN Team Provider (Incubation) and complete the install procedure
    • You will be prompted to select a connector the first time you access SVN from within Eclipse; we recommend the Java SVN Kit, but there are other options that may work better for your environment (see the Subversive documentation for more information)
    • Restart Eclipse
Icon

It is necessary for Windows users to make sure that their workspace is in a directory path without spaces. Using such paths (such as in C:\Documents and Settings\<username>) has been known to interfere with unit tests finding files in the checked out project.

Download the Projects

We use SVN as our code repository system. We have created a special branch to use specifically for this boot camp.

Database

You can use either MySQL or Oracle for the boot camp. We are officially supporting MySQL since it works on more systems but using Oracle is also an option.  We will be using three databases in the bootcamp

  • KCBND: The bundled server database
  • KCEMB: The embedded KC-side database
  • KREMB: The embedded Rice-side database
Icon

We highly recommend you start out with the bundled environment.  It only involves maintaining one database and one configuration file and is the minimal setup for KC.  Embedded is a more advanced configuration and will be covered later in the boot camp.

MySQL

MySQL is a nice way to start out on KC, especially if you use OSX (which Oracle does not support). Many developers find it does not take up as much of a memory imprint as Oracle and thus choose to use it for their development environments.

  • Download and install the MySQL Community Server.
  • If you are on a case-sensitive system like OSX or Linux, set the following in your my.ini or my.cnf file
  • Open the MySQL command line client or the MySQL Workbench GUI client and sign in with the system user password that was created during the setup.
  • For each database create a user and a schema for that user and grant all privileges for that user on that schema:
Icon

It might be necessary to increase the default value of the max_allowed_packet parameter for your MySQL server, which by default is set to 1M (1 megabyte). If you receive max_allowed_packet size exceeded exceptions, add this line to your my.ini or my.cnf file in the [mysqld] section and restart your MySQL server.

Oracle and the Oracle Driver (Optional)

Oracle is an excellent choice for KC, especially if you know your institution will be using it for production and your OS is supported and your machine can handle it.

  • Download Oracle 10g XE from http://www.oracle.com/technetwork/database/express-edition/database10gxe-459378.html
  • Install Oracle according to the directions. Make a note of the home directory (<ORACLE_HOME>).
    • Windows Users: Oracle installation must occur as an administrative user on the local machine, not a domain user
    • Linux Users: After installing the package from the website, be sure to run su -c "/etc/init.d/oracle-xe configure" if it doesn't run automatically
  • The Oracle JDBC Driver will be under <ORACLE_HOME>/app/oracle/product/10.2.0/server/jdbc/lib/ojdbc14.jar
  • Run the following command in your project directory (the one with a pom.xml) to install the Oracle driver into the Maven Repo
  • Open a SQL Command line from the Oracle menu and run the following commands (entire session reproduced below for clarity).
    where 8087 needs to be a port other than 8080.
  • Open a browser and go to: http://localhost:8087/apex, substituting the port selected in the last step for 8087, and validate that the Oracle http interface in running on the new port.
  • Log in as SYSTEM and go to Administration > Database Users > Create User
  • Create each database with an appropriate username and password and click the Check All link in the User Privileges section.
Icon

If you start seeing java.sql.SQLException: Listener refused the connection with the following error: ORA-12519, TNS:no appropriate service handler found messages, you will need to increase the Oracle XE connection limit by executing the following and then restarting the server.

Run the Code

It is now time to prepare the database and launch the application.

Build the Bootstrap Database

We will be using the official release scripts to create the database. This process is very similar to how implementers install production environments.

  • Go to <kc_project_directory>\src\main\config\sql\RELEASE-SCRIPTS and run either KC_Install.sh or KC_Install.bat.
  • Depending on what you are setting up, select BUNDLE or EMBED for the environment, select Y if you are prompted for a Rice upgrade, select ORACLE or MYSQL for the database, select NEW for installing a new database, and finally enter your username, password, and Schema/TNS name.

Rebuild, Configure, and Run the Web Application

We now need to generate extra sources and then do final configuration file setup before we can start the server.

  • Build kc_project by right-clicking on the project and selecting Run As > Maven clean followed by Run As > Maven generate-sources. Make sure all of the Maven dependencies have completed downloading.
  • Copy the contents of the <kc_project_directory>\src\main\config\userhome directory into your user home directory (<USER_HOME>).
  • Prepare the configuration files for the environment of your choice
    • For bundled, copy the file <USER_HOME>\kuali\main\dev\kc-config.xml.bundled.developer.template to <USER_HOME>\kuali\main\dev\kc-config.xml and update the values as needed.
    • For embedded, you will need to copy and edit two files
      • Copy the file <USER_HOME>\kuali\main\dev\kc-config.xml.embedded.developer.template to <USER_HOME>\kuali\main\dev\kc-config.xml and update the values as needed.
      • Copy the file <USER_HOME>\kuali\main\dev\rice-config.xml.embedded.developer.template to <USER_HOME>\kuali\main\dev\rice-config.xml and update the values as needed.
  • Launch the environment of your choice from the <kc_project_directory>\scripts\launch folder
    • For bundled, right click on the Jetty 7 [bundled].launch file, and choose Run As > Jetty 7 [bundled]
    • For embedded, you will need to first do some additional setup
      • Right click on the Jetty 7 Rice-CopyWAR[embedded].launch file, and choose Run As > Jetty 7 Rice-CopyWAR[embedded]
      • Right click on the Jetty 7 Rice[embedded].launch file, and choose Run As > Jetty 7 Rice[embedded]
      • Right click on the Jetty 7 KC[embedded].launch file, and choose Run As > Jetty 7 KC[embedded]
  • Open a browser and go to http://localhost:8080/kc-dev
  • Login as admin if you encounter a login screen. Not much is available to look at until you complete the next step.

Ingest the KEW files

In order to make workflow configuration easier, KC uses Rice KEW workflow file ingestion to manage this portion of the database. This makes it easier for implementers to make rapid changes to the workflow structure while the application is running.

  • In your KC application, go to the System Admin tab and click on XML Ingester in the right top column.
  • Click Browse... and find the file <kc_project_directory>\src\main\config\sql\RELEASE-SCRIPTS\Full-KC-KEW.zip file and then click Upload XML Data
  • Wait for a while until all of the files are listed in red on the page. Ingestion is complete; you should now be able to initiate documents and play with them.

Add the Demo Data to the Database

We also provide demo data to help you get off the ground in exploring many of KC's features.  It adds a new superuser quickstart as well as specifying a Committee to submit IRB Protocols to.  You should only install this after you have installed the KEW files and stopped your server.

  • Go to <kc_project_directory>\src\main\config\sql\RELEASE-SCRIPTS and run either KC_Install_Demo.sh or KC_Install_Demo.bat.
  • Depending on what you are setting up, select BUNDLE or EMBED for the environment, select ORACLE or MYSQL for the database, and finally enter your username, password, and Schema/TNS name.

Cleanup Tips

  • You may wish to change to Maven offline mode once you get the project up and running, just to limit the bandwidth you are using per build. To do this, in Eclipse go to Window > Preferences > Maven and check Offline.

Advanced Configuration

A more advanced configuration involves setting the system up in embedded mode.

Embedded Mode Configuration

The following steps will help you set up your embedded mode and start it up in Eclipse.

  • Install the embedded databases (KCEMB, KREMB) using the scripts described above.
  • Move the files for embedded mode (<USER_HOME>\kuali\main\dev\kc-config.xml.embedded.developer.template and <USER_HOME>\kuali\main\dev\rice-config.xml.embedded.developer.template) to their respective names (kc-config.xml and rice-config.xml) as described above.
  • For the KC database, in both files, edit the following to match your database connection parameters:
  • For the KR database, in rice-config.xml, edit the following to match your database connection parameters:
  • Start the application in Eclipse as described above for embedded mode.

KC Customizations

KC Customization Documentation Page

Presentation Links

  • No labels