Overview#

Orchard is what we call the network-aware service-oriented software used to run Orc programs online. This page describes how to package, install, and test the Orchard servlet.

Prerequisites:

  • Ant
  • Eclipse
  • Checkouts of the Orchard, OrcSites, Website and OrcJava projects from SVN. I will assume these projects were all checked out into the same parent directory.
This procedure needs updating. See the INSTALL file in the Orchard project.

Install Orc JAR Dependencies#

The WAR file needs to include the JARs for OrcJava and OrcSites. Build these and copy them to the Orchard/lib directory:

(cd OrcJava && ant jar && cp build/orc-?.?.?.jar ../Orchard/lib)
(cd OrcSites && ant jar && cp build/orc-sites-?.?.?.jar ../Orchard/lib)

Create .properties files#

Copy orchard.sample.properties to orchard.properties. Modify it to suit your configuration (i.e. set the mail servers). If you don't plan to run a database or use the various webservice demos you can leave those sections as-is.

If you are using Google OAuth, put the your oauth.jks in the same directory as orchard.properties; the build process will copy it into the orc.orchard package. If you are not using Google OAuth, you should create an empty oauth.jks, i.e. touch oauth.jks.

If you are a member of the Orc team, see JohnThywissen for preconfigured properties and jks files.

Create oauth.jks file#

If you are using Google OAuth, put the your oauth.jks in the same directory as orchard.properties; the build process will copy it into the orc.orchard package. If you are not using Google OAuth, you should create an empty oauth.jks, i.e. touch oauth.jks.

If you are building Orchard for your own use, here is how to create an oauth.jks file for use with Google:

  1. Register your server with Google
  2. Generate the RSA keys and certificate:
    keytool -genkeypair -v -alias google -keystore ./oauth.jks -keyalg RSA -keysize 1024 -sigalg SHA1withRSA -dname "CN=YOURNODE.example.com, OU=Department of NAME, O=The University of NAME at NAME, L=CITY, ST=STATE, C=US" -validity 1461
    with the italicized text replaced with your values. Also, you can change the validity option value to the number of days of validity you want for the certificate.
  3. Output the public certificate to a file:
    keytool -exportcert -rfc -keystore ./oauth.jks -alias google -file oauth_google.pem
  4. Upload the certificate to Google: https://www.google.com/accounts/ManageDomains

If you are a member of the Orc team, see JohnThywissen for preconfigured properties and jks files.

Build the Orchard WAR#

Do a "Clean" build of Orchard from within Eclipse. Then use the External Tool "Build WAR" (which just runs "ant war" using build.xml) to create build/orchard.war.

If you have installed a servlet container, you can deploy this WAR to your servlet container. For example, to deploy to an installed version of Jetty, do this:

sudo cp build/orchard.war /var/lib/jetty6/webapps/
sudo /etc/init.d/jetty6 restart

If you have not installed a servlet container where you want to run Orchard, continue to the next steps to build a standalone JAR which you can run without a servlet container.

Build the Demo JAR#

Make sure that you have the Website project checked out in the same directory as the Orchard project. In the Orchard project, run ant demo-jar. This will create the file build/orchard-demo.jar.

Test the Services#

Run java -jar build/orchard-demo.jar.

A few seconds later your browser window should open to http://localhost:8080/demo.shtml where you will see the Orchard demo page. If this doesn't happen you should see error messages on the console indicating the problem.

Choose a demo, click "Run", and watch for publications in the bottom window. If you are not seeing any publications, check for Javascript errors. I recommend installing the "Firebug" Firefox extension to assist in debugging communication problems with the servlet.

Database (OPTIONAL)#

There is an experimental feature to allow users to log in to use restricted features. I don't recommend that you try and set this up on your own server, but if you really want to try it, follow these instructions:

  1. Install postgreSQL
  2. Log in to postgreSQL as an administrator
  3. Run the script src/orc/orchard/create.sql
  4. Run the script src/orc/orchard/schema.sql
  5. To create accounts, use the JMX Console (see below).

JMX Monitoring (optional)#

To use the JMX console (this has known issues on Java 6, please downgrade to Java 5 if you want to use this feature):

  1. Start jconsole: gksudo jconsole
  2. Select the local agent corresponding to the servlet container and click Connect
  3. Some useful things to do in the JMX console:
    • Under "MBeans", if there are any jobs running they will appear under "orc.orchard"; you can see status, statistics, and stop jobs if necessary.
    • Under "MBeans", you can find the DbAccounts object and create/update restricted accounts. (This assumes you configured a user accounts database.)
    • Under "Threads", you can see which threads are blocked and where.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-8) was last changed on 07-Oct-2014 19:21 by John Thywissen