Deploying the Demonstration War from Github

The instructions below are temporary instructions to allow early adopters/testers to be able to build, deploy, and demonstrate the OpenRegistry project in its current state. The instructions below are not a reflection on how the final project may be built, packaged and deployed. The final project may look entirely different.

Deployment Checklist

This checklist can be used in conjunction with the instructions below. It was created as part of a test deployment in August 2012.

Disable spock plugin in pom.xml (for Maven 3+)
Build: mvn clean package'
Copy openregistry-webapp/src/openregistry.xml to tomcat/conf/Catalina/localhost and configure e.g. jdbc settings, etc.
Create database schema username (specific to the database in use)
Create OR-Database using scripts (Oracle ,MySQL5.x)
Deploy open registry for the first time

Also see: https://github.com/UniconLabs/openregistry-springbatch-poc

Retrieve the Source from Source Control

Step 1 is to retrieve the current source code from source control. Information about source control can be found here. Currently, you'll want to check out trunk.

Future steps will refer to the following:
$OPEN_REGISTRY_PROJECT - the location where you checked out the OpenRegistry project to
$TOMCAT_HOME - location of your tomcat directory, i.e. /opt/apache-tomcat-6.0.18

Modify the Source Files for Your Institution

Step 2 is to locate the openregistry-webapp web app (most likely under $OPEN_REGISTRY_PROJECT/openregistry-webapp). Find the WEB-INF/applicationContext.xml and open it with your favorite text editor. Locate the property "hibernate.dialect" and replace the value with the value for your local database. Example Hibernate dialects can be found on the Hibernate web site.

Build the WAR File

Step 3, assuming you have Maven2 installed, is to cd to $OPEN_REGISTRY_PROJECT and type "mvn clean package install". This will generate a WAR file called $OPEN_REGISTRY_PROJECT/openregistry-webapp/target/openregistry.war. If you don't have Maven2 installed, please install it first.

Set Up Tomcat

Step 4 assumes you have a Tomcat instance set up. OpenRegistry will deploy to other containers, but they have not been tested. Place the openregistry.war in $TOMCAT_HOME/webapps

Step 5 is to set up your database access. You'll need to create an openregistry.xml similar to the one below and place it in $TOMCAT_HOME/conf/Catalina/localhost

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/openregistry">
	<!-- Turn off tomcat session persistance -->
   	<Manager className="org.apache.catalina.session.PersistentManager" saveOnRestart="false">
    	<Store className="org.apache.catalina.session.FileStore"/>
   	</Manager>

	<Resource
   		name="jdbc/MyDataSource"
   		auth="Container"
   		type="com.mchange.v2.c3p0.ComboPooledDataSource"
        description="OpenRegistry Database"
        factory="org.apache.naming.factory.BeanFactory"
        acquireIncrement="5"
        minPoolSize="5"
        maxPoolSize="256"
        maxIdleTimeExcessConnections="900"
        driverClass="oracle.jdbc.driver.OracleDriver"
        jdbcUrl="jdbc:oracle:thin:@databaseserver.com:dbalias"
        user="@@@username@@@"
        password="@@@password@@@"
        maxStatementsPerConnection="37"
        numHelperThreads="5"
        testConnectionOnCheckin="true"
        idleConnectionTestPeriod="300"
        preferredTestQuery="SELECT SYSDATE FROM DUAL"/>
</Context>

The above example utilizes C3P0 Connection Pooling Library and the Oracle Driver. You'll need to replace those with your connection pool and database information. Remember to place your connection pooling jar and database driver jar in the Tomcat shared locations (which vary based on Tomcat version).

Assuming your user has the appropriate permissions, the database structure will be created for you. You'll need to populate it with some basic data though (Phone Types, People, etc.) before you can really use it. See Sample Reference Data and Sample Rutgers Specific Reference Data, in that order. As of this writing, the "Add Person" and "Add Role" use cases are mostly complete. The Sample Database Inserts examples can now be added directly via the "Add Person" use case and those examples will probably get out of date compared to any changes to the data model.

Start Tomcat & Test

Assuming you have Tomcat running on port 8080, start up Tomcat ($TOMCAT_HOME/bin/startup.sh or $TOMCAT_HOME/bin/startup.bat) and point your web browser to:

http://localhost:8080/openregistry/addPerson.htm

or

http://localhost:8080/openregistry/addRole.htm?sorPersonKey=2&roleInfoKey=1

(sorPersonKey and roleInfoKey are dependent on what's in your database)

Run the Demonstration War from within Intellij IDEA

If you use Intellij IDEA for Java development, you can run the demonstration code from within the IDE, making it easier to debug and explore the code. See Running from Intellij IDEA for setup instructions.