* [Standard caGrid Prerequisites|caGrid13:Software Dependencies]
h1. 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.3 installed on your machine, and a suitable container, you may proceed to [the next step|#Configuration].
{tip}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{_}{*}{tip}
To install caGrid/Index Service and setup a container, please complete the following steps:
{include:caGrid13:Install caGrid and Configure a Non-Secure Container Using the caGrid 1.3 Installer}
h1. Configuration
----
{tip}In most cases you will not need to edit any configuration files.{tip}
h2. General Configuration
The Index Service project (located at *{_}INDEX_HOME{_}*), doesn't contain source code or configuration files, just gar (*G{*}rid *Ar{*}chive) 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.
h2. Xindice Configuration
The version of the Index Service caGrid uses makes use of an embedded XML database called [Xindice|http://xml.apache.org/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.
{noformat}
> export $CATALINA_OPTS=-Dxindice.db.home=/tmp/index-service-xindice-db
{noformat}
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|http://www.jboss.org/community/docs/DOC-11058] for more information.
h1. Deployment
----
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:
{terminal}> ant deployIndexTomcat{terminal}
You will then want to start up Tomcat so your service is available. For Tomcat, you can run this command:
{terminal}> $CATALINA_HOME/bin/startup.sh{terminal}or in Windows
{terminal}> %CATALINA_HOME%\bin\startup.bat{terminal}
h1. Validation
----
The Index Service can be validated to be properly functioning by interacting with [Discovery API|Discovery], which communicates with the service directly via its API. This section details the steps you can take to do this validation.
h2. Validate 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|#Deployment] 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:
{noformat}DefaultIndexService
Hi there, this is an AXIS service!
Perhaps there will be a form for invoking the service here...
{noformat}
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.
h2. Validate the Index Service (command line client)
Once you have [verified the service is running|#Validate the service is running] you can check some of its functionality from the command line by running the following command from the *{_}INDEX_HOME{_}{*}_/../discovery_ directory:
{terminal}> ant \-Dservice.url=*YOUR_SERVICE_URL* runClient{terminal}
{noformat}[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
{noformat}
Since you just started your service, you likely will see no service's registered to it (as evident by the "No services found" output).
h1. Management
----
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|#Configuration]. 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|#Xindice Configuration], the Index Service uses an embedded Xindice database, but it should not be backed up.
Administration
...