Access Keys:
Skip to content (Access Key - 0)

Metadata

Index Service Administrators Guide

For the purposes of Advertisement and Discovery, caGrid leverages the Globus-provided Index Service. For more information on the Index Service, see the Globus documentation.

Contents

Prerequisites

Installing the Software

In this step you will download and install caGrid, and a grid service container, using the caGrid Installer. If you already have caGrid 1.4 installed on your machine, and a suitable container, you may proceed to the next step.

Once you have installed caGrid, the Index Service software can be found in the directory location where you installed caGrid, in the caGrid/projects/index directory. This guide will refer to that location as INDEX_HOME

To install caGrid/Index Service and setup a container, complete the following steps.

Install caGrid and Configure a Non-Secure Container Using the caGrid 1.4 Installer

  1. Download the caGrid 1.4 Installer. The downloaded installer is contained in caGrid-installer-1.4.zip.
  2. Unzip the file caGrid-installer-1.4.zip. This creates the directory caGrid-installer-1.4. This guide refers to that directory as CAGRID_INSTALLER_LOCATION.
  3. From a command prompt, launch the installer by entering the following command: 
     > cd *CAGRID_INSTALLER_LOCATION\\\\\\\\\* 
     > java -jar caGrid-installer-1.4.jar
  4. Select the I agree to this license checkbox and click  Next.
  5. Select the Install/Configure caGrid Software and the Install/Configure Grid Service Container checkboxes and click  Next.
  6. The installer detects if Ant is already installed. It installs or reinstalls it accordingly. In either case, you must specify the location where you want to install Ant.
  7. The installer detects if Globus is already installed. It installs or reinstalls it accordingly. In either case, you must specify where you want to install Globus.
  8. The installer asks for a location on your local file system to install caGrid. Specify a location to install caGrid and click  Next.
  9. The installer displays a list of tasks that the installer will perform. Click  Next to start the installation process.  The installer downloads, builds, and installs several components. Note: This process takes several minutes.
  10. Once the installer has completed installing all the components, click  Next.
  11. The installer asks which Grid you would like to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes, it is recommended you select the Training Grid. If you do not want to configure caGrid to work with an existing Grid, you may specify that as well. You can modify the installer to support additional Grids.
  12. The installer shows a summary of the tasks to be completed. Click  Next to configure caGrid to use the selected target Grids. Note: This process takes several minutes.
  13. Once the installer has finished configuring the target Grid, click  Next.
  14. Select the Container where you want to deploy your service. This guide provides instructions for Tomcat. As this container does not ensure security, leave the Should this container be secure? checkbox unchecked and click  Next.
  15. In the hostname box, enter the hostname of your server. This should match the hostname used in creating your host credentials. Click  Next.
    If you plan on using this container to deploy the service registered to an existing grid, it is important to use a publicly resolvable DNS name (or static IP); otherwise, you will need to manually edit configuration files later to correct this.
  16. The next screen asks where you want to install Tomcat. In the Directory box, enter a location and then click  Next.
  17. The next screen displays a list of tasks that the installer will perform to install and configure Tomcat. Click  Next.
  18. Once the installer has completed installing all the components, click  Next.
  19. Click  Next. The final screen reminds you to set your ANT_HOME, GLOBUS_LOCATION, and CATALINA_HOME environment variables. Set these variables immediately and then click Finish.
    You can find these instructions in CAGRID_POST_INSTALLATION.txt, which is in the directory from which you ran the installer.
  20. Congratulations! You have successfully installed and configured your Tomcat container. You may now close the installer by clicking  Close.

Configuring the Service

In most cases you will not need to edit any configuration files.

General Configuration

The Index Service project (located at INDEX_HOME), doesn't contain source code or configuration files, just gar (Grid Archive) files for the Globus-provided Index Service. There is no additional configuration necessary to deploy/configure the Index Service, though these gar files can be extracted (using tar or a similar command) and any desired configuration per the Globus documentation can be performed, and the gar files recompressed prior to deployment.

Xindice Configuration

The version of the Index Service caGrid uses makes use of an embedded XML database called Xindice. This is solely used for performance reasons, and only acts as "out of core" storage for transient data. That is, the database contents are not expected to survive container restarts, and therefore no backup or maintenance of the database is required. However, by default the database will write its contents to the file system in the directory in which the container was started. This behavior can be configured by passing a system property (xindice.db.home) to the JVM of container, which specifies the desired directory in which to write the database.

For example, if you deploy the Index Service to Tomcat, you specify this property via the CATALINA_OPTS environment variable which the Tomcat startup scripts read to allow one to pass JVM arguments to Tomcat's JVM.

> export $CATALINA_OPTS=-Dxindice.db.home=/tmp/index-service-xindice-db

JBoss has a similar process for specifying container JVM options, using the JAVA_OPTS variable instead (Tomcat actually will read this variable as well). See the JBoss documentation for more information.

Deploying the Service

As opposed to all other caGrid core services, the Index Service is not an Introduce-generated Service, so it does not have the same deploy-time features and configurations as other core services. However, it does support deploying to Tomcat, JBoss, and Globus containers.

Ant Target
Description
deployIndexGlobus Deploys the Index Service to the Globus container at the value of the GLOBUS_LOCATION environment variable
deployIndexJBoss Deploys the Index Service to the JBoss container at the value of the JBOSS_HOME environment variable
deployIndexTomcat Deploys the Index Service to the Tomcat container at the value of the CATALINA_HOME environment variable

For example, to deploy the service to Tomcat from the command line, you can type the following command from the INDEX_HOME directory:

 > ant deployIndexTomcat

You will then want to start up Tomcat so your service is available. For Tomcat, you can run this command:

 > $CATALINA_HOME/bin/startup.sh
or in Windows

 > %CATALINA_HOME%\bin\startup.bat

Starting the Index Service

  1. If you chose a Tomcat container, start Tomcat as follows: 
      $CATALINA_HOME/bin/startup.sh
    Check the $CATALINA_HOME/logs/catalina.out file for any errors.
  2. If you chose a JBoss container, start JBoss as follows:
    1. Windows: 
       $JBOSS_HOME\run.bat
    2. Unix/Mac: 
       $JBOSS_HOME/run.sh

Validating the Service

The Index Service can be validated to be properly functioning by interacting with Discovery API, which communicates with the service directly via its API. This section details the steps you can take to do this validation.

Validating the Service is Running

To ensure the Index Service is working properly, first we need validate the service is actually running, and there are no errors in its log. For example, if you deployed to Tomcat, you should look at the log file in $CATALINA_HOME/logs/catalina.out and make sure there are no exceptions present. Finally, open your web browser, and point it to the URL of your service. This should be of the form:

http:/YOUR_HOST:YOUR_PORT/wsrf/services/DefaultIndexService

For example, if you used the default ports, you should be able to use the following URL on the machine you deployed the Index Service: "http://localhost:8080/wsrf/services/DefaultIndexService".

When you connect to this URL, you should see the following text on the screen:

DefaultIndexService

Hi there, this is an AXIS service!
Perhaps there will be a form for invoking the service here...

If you see an error, the service is not deployed correctly. If you get a connection refused, check that your container is actually running, and that the URL you are using is correct.

Validating the Index Service (command line client)

Once you have verified the service is running you can check some of its functionality from the command line by running the following command from the CAGRID_HOME/projects/discovery directory:

 > ant -Dservice.url=*YOUR_SERVICE_URL* runClient 
[meadowgrain:caGrid/projects/discovery] oster% ant -Dservice.url=http://localhost:8080/wsrf/services/DefaultIndexService runClient
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: /Users/oster/grid/ws-core-4.0.3

defineClasspaths:

runClient:
     [echo] Discovering from Index Service: http://localhost:8080/wsrf/services/DefaultIndexService
     [java] No services found.

BUILD SUCCESSFUL
Total time: 3 seconds

Since you just started your service, you likely will see no service's registered to it (as evident by the "No services found" output).

Managing the Service

The Index Service has no management operations which need to be performed on the running service. The only changes which can be made to the service are described in the Configuration section. Any such changes to the configuration should be done in the files in INDEX_HOME, and the service should be redeployed, and the container restarted.

As specified in the Xindice Configuration section, the Index Service uses an embedded Xindice database, but it should not be backed up.
Last edited by
Clayton Clark (1008 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence