Skip to topic | Skip to bottom
Grimoires
Grimoires.InstallationManual

Start of topic | Skip to actions

Grimoires Installation Manual

Installing Grimoires to OMII Container

  1. Choose one of two war files to download: one is Grimoires for OMII Container 1.2.0 without signed SOAP message support, the other is with signed SOAP message support.
  2. Use the standard ways to deploy these war files to the OMII tomcat. For instance, assuming OMII Tomcat is installed at http://hostname:18080, go to http://hostname:18080/manager/html (The tomcat manager username/password are required.), scroll down to the form with the title "WAR file to deploy", select the war you have downloaded, and click the "deploy" button to deploy the war file.
  3. Test the installation. Assume you install OMII container at http://hostname:18080, and you deploy Grimoires at /grimoires, by clicking http://hostname:18080/grimoires/services, you will be able to see all the deployed services. The Grimoires services are:

By clicking them, you will be able to see a messsage "Hi there, this is an AXIS service!". It means Grimoires is successfully deployed. You can also click the "wsdl" link to get the corresponding wsdl file.

Test

The JUnit test suite and UDDI browser can be used to test a Grimores without signed SOAP message support. To test a Grimoires with signed SOAP message support, the OMII secure client must be used instead.

JUnit Test Suite

  1. Download and unzip Grimoires junit test suite (wstester.zip). You will see a directory called "wstester".
  2. cd wstester.
  3. Config bos.properties to specify the URL of Grimoires (assuming Grimiores is deployed on the http://localhost:18080/grimoires/): registryBaseURL = http://localhost:18080/grimoires/services
  4. Run ant. Note: not all the unit tests can pass. There are about 5 errors and 2 failures. Please look at the detail test report.

OMII Secure Client

  • This document describes how to install and set up the OMII secure client. It will provide potential developers with enough information to develop their own secure Grimoires client.
  • For more information of OMII's security framework, please read this.

UDDI Browser

You may also use UDDI browser to test Grimoires. Please refer to UDDI Browser's document for its usage.

Installing Grimiores to Other Containers

Apache Tomcat

  1. Download the war file for Apache Tomcat.
  2. Use the standard ways to deploy the war file to Apache Tomcat. For instance, assuming Tomcat is installed at http://hostname:8080, go to http://hostname:8080/manager/html (The tomcat manager username/password are required.), scroll down to the form with the title "WAR file to deploy", select the war you have downloaded, and click the "deploy" button to deploy the war file.
  3. Test the installation. Assume you install Tomcat at http://hostname:8080, and you deploy Grimires at /grimoires, by clicking http://hostname:8080/grimoires/services, you will be able to see all the deployed services. The Grimoires services are:

By clicking them, you will be able to see a messsage "Hi there, this is an AXIS service!". It means Grimoires is successfully deployed. You can also click the "wsdl" link to get the corresponding wsdl file.

Globus Toolkit 4

  1. Download and install GT 3.9.5 Java WS Core Binary.
    1. Download and unzip GT 3.9.5 Java WS Core Binary. Assume it is in $GT395.
    2. export GLOBUS_LOCATION=$HOME/GT4 (specify your GLOBUS_LOCATION)
    3. cd $GT395; ant
  2. Download Grimoires binary release for GT4: grimoires.gar.
  3. export ANT_HOME=/usr/local/apache-ant-1.6.2 (specify your ANT_HOME)
  4. Deploy Grimoires: $GLOBUS_LOCATION/bin/globus-deploy-gar grimoires.gar
  5. Copy "lib/grimoires.properties" in the source code release to $GLOBUS_LOCATION.
  6. Start GT4 ($GLOBUS_LOCATION/bin/globus-start-container -nosec). You will see the following services are deployed:
  7. Undeploy Grimoires: $GLOBUS_LOCATION/bin/globus-undeploy-gar grimoires

Installation from Source Code

The contents below is both a guide for Grimoires users and a memo for Grimoires developers. To compile and deploy Grimoires from source code, you need to modify the properties file properly, and then call the well defined ant targets.

Grimoires source code directory structure

  • src/: source code
  • lib/: where Grimoires server jar is generated, and all third party jars required by Grimoires
  • docs/: documentation
    • api/: javadoc
  • wsdl/: wsdl files and xsd schemas for all Grimoires services
  • config/: configuration files for various containers
    • axis/: configuration files for standard Apache Tomcat
    • gt4/: configuration files for GT4 container
    • omii/: configuration files for OMII 1.2.0 without signed SOAP message support
    • omii-sec/: configuration files for OMII 1.2.0 with signed SOAP message support
  • dist/: where binary release files (war file or gar file) for various containers are generated
    • client/: Grimoires client
    • server/: Grimoires server
      • axis/: where the war file for standard Apache Tomcat is generated
      • gt4/: where the gar file for for GT4 container is generated
      • omii/: where the war file for OMII 1.2.0 without signed SOAP message is generated
      • omii-sec/: where the war file for OMII 1.2.0 with signed SOAP message is generated
  • wstester/: junit test suite
  • init.properties: set up the compilation and deployment options for Grimiores. Users need to edit this before compilation and deployment.
  • build.xml: Ant build file containing all ant targets to compile and deploy Grimoires. Users do not need to edit this file to compile and deploy Grimoires.

init.properties

All the configurable options to compile and deploy Grimoires are in init.properties.

  • [Required] Target container: omii-sec, omii, axis, or gt4. For instance,
container = omii

Grimoires has three target containers, OMII 1.2.0, Tomcat 5.0, GT4. Here, omii stands for OMII 1.2.0, axis for Tomcat 5.0, and gt4 for GT4. In addition, omii stands for a Grimoires without signed SOAP message support in OMII 1.2.0, while omii-sec for a Grimoires with signed SOAP message support in OMII 1.2.0.

  • OMII specific options, which are REQUIRED if "container = omii" or "container = omii-sec" is set. For instance,
tomcat.host = http://gallagher
tomcat:port = 18080
omii.context.path = grimoires
omii.tomcat.username = tomcat
omii.tomcat.password = tomcat

In the above case, Grimoires will be deployed in http://gallagher:18080/grimoires. The username of a valid tomcat account of a manager role is "tomcat", and the corresponding password is "tomcat".

  • Axis specific options, which are REQUIRED if "container = axis" is set. For instance,
axis.tomcat.url = http://localhost:8080/
axis.context.path = grimoires
axis.tomcat.username = tomcat
axis.tomcat.password = tomcat

In the above case, Grimoires will be deployed in http://localhost:8080/grimoires. The username of a valid tomcat account of a manager role is "tomcat", and the corresponding password is "tomcat".

  • GT4 specific options, which are REQUIRED if "container = gt4" is set. For instance,
gt4.url = http://localhost:8080
gt4.home = /home/gt395/gt4 

build.xml

After you set up the options in init.properties to the proper values in your environment, you can call the ant targets in build.xml to compile and deploy Grimoires to your selected container. Here we list all the ant targets for public use:

  • clean: clean up all the compiled classes and generated jars. This should be called if you choose another container in init.properties. For instance, if you set "container = omii" then modify it to "container = axis", you need to call "clean" before you compile Grimoires.
  • release: print the version information of Grimoires.
  • build-all: build java doc, generate the war file or gar file (for GT4) which is deployable, based on the options set up in init.properties, and build the client.
  • deploy: deploy Grimories (war file or gar file) to the container, based on the options set up in init.properties. "deploy" will call "make-dist".
  • undeploy: undeploy Grimoires from the container, based on the options set up in init.properties.
  • test-install: Test whether Grimoires is deployed in a container properly. It will access each deployed Grimoires service using http protocol, and print the information it get. For instance, it will get http://localhost:18080/grimoires/services/publish. If the publish servie is successfully deployed, you will see
<h1>publish</h1>
<p>Hi there, this is an AXIS service!</p>
<i>Perhaps there will be a form for invoking the service here...</i>

OMII security framework

The Grimoires with signed SOAP message support needs to leverage the functionalities provided by OMII's security framework.

  • This document provides the general idea of signing SOAP messages for a secure OMII service.
  • This document provides the general description of the principles underlying OMII security framework.

Notes

  • A typical deployment procedure should look like:
    • Set up init.properties.
    • ant deploy
    • ant test-install
    • ant test-junit
  • When to modify the configuration files under config/?
    • The files under config/ will be included in the corresponding war or gar file. For instance, under config/omii-sec/, there are server-config.wsdd, and web.xml, and classes/. The latter contains all the configuration files setting up OMII's security framework.
    • If Grimoires' web service interface is changed, for instance, the wsdl file is changed, or the Java mapping for the wsdl is changed, server-config.wsdd should be changed.
    • If "container = omii-sec" in init.properties, all the security configuration files under config/omii-sec/classes/ need to be ensured to be correct.
  • We assume OMII container is installed at /usr/local/OMII/. OMII Tomcat is at /usr/local/OMII/jakarta-tomcat-5.0.25/. They are default settings by OMII. They will not affact Grimoires without signed SOAP message support, but they will affect Grimoires with signed SOAP message support, because those security configuraiton files have hard coded OMII's absolute path. However, it is very staightforward to reconfig those files if OMII is installed in another location.

Configuration

grimoires.properties

In Grimoires source code, grimoires.properties is in src/. After Grimoires is deployed, grimiores.properties appears in grimoires/WEB-INF/classes, assuming Grimiores is deployed under grimoires/. All the options controlling Grimiores' runtime behavior appear here. Currently it is used to decide the Jena backend of Grimoires. A grimoires.properties file looks like:

# configuration of backends for grimoires

# store states the RDF backend used by grimoires
# by default an in-memory backend is used
store = memory

# Memory model backed by files
###################
# store = file
# root = L:\\Documents and Settings\\wf\\My Documents\\workspace\\Grimoires\\store\\

# Berkeley DB store
###################
# store = bdb
# dbfile = c:\\BDBStore
# dbname = Grimoires

# MySQL
###################
# store = mysql
# url = jdbc:mysql://localhost:3306/grimoires
# user = grimoires
# password = grimoires


# PostgreSQL
###################
# store = postgresql
# url = jdbc:postgresql://localhost/Grimoires
# user = grimoires
# password = grimoires

Using a persistent store

Memory model backed by file

  • Comment the line "store = memory"
  • Uncomment the line "store = file"
  • Uncomment the line "root = L:\\Documents and Settings\\wf\\My Documents\\workspace\\Grimoires\\store\\". Set the "root" value to where the file is.

Berkeley DB

  • Comment the line "store = memory"
  • Uncomment the lines
store = bdb
dbfile = c:\\BDBStore
dbname = Grimoires

PostgreSQL?

  • Comment the line "store = memory"
  • Uncomment the lines
store = postgresql
url = jdbc:postgresql://localhost/Grimoires
user = grimoires
password = grimoires

  • In the above case, you need to create a PostgreSQL? user "grimiores", which password is "grimoires", and to create a database called "Grimoires" owned by user "grimoires". You also need to create tables in the database "Grimoires" using the sql script "config/postgresql.sql".

-- WeijianFang - 05 Apr 2005
to top


You are here: Grimoires > SoftwareReleases > GrimoiresRelease101 > InstallationManual

to top

Copyright 2004 by the University of Southampton