[{TableOfContents}]

!!! 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.

%%warning 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:

# [Register your server with Google|https://developers.google.com/accounts/docs/RegistrationForWebAppsAuto]
# 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.
# Output the public certificate to a file:\\
  {{keytool -exportcert -rfc -keystore ./oauth.jks -alias google -file oauth_google.pem}}
# 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:

# Install postgreSQL
# Log in to postgreSQL as an administrator
# Run the script {{src/orc/orchard/create.sql}}
# Run the script {{src/orc/orchard/schema.sql}}
# 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):

# Start jconsole: gksudo jconsole
# Select the local agent corresponding to the servlet container and click Connect
# 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.