Deploying STILTS as a CEA application
=====================================

[If you don't know what a CEA is, you should almost certainly ignore 
this file].


Background
----------

STILTS can be deployed as an application in the context of the Common 
Execution Architecture.  CEA deployment requires an application 
description file (app-description.xml) to be made known to the CEA 
server.  Since STILTS provides a number of different tasks, its 
app-description file is quite complicated.  Fortunately, it can 
supply its own app-description file as described below.

The auto-generated app-description file, like most of the XML and 
on-line task and parameter documentation, is generated from the same 
code which the package uses at run time to parse and execute commands.
This helps keep the app-description file up to date with the current 
state of the application itself.  For this reason, the 
app-description.xml file describing a STILTS installation should 
always be one that is automatically generated by that version of the 
package.  If you need to modify this app-description file by hand to suit
local requirements following auto-generation, it would be a good idea 
to notify the maintainer of STILTS so that future versions of the 
auto-generation code can provide suitable options; otherwise local 
modifications will get lost if later versions, with new auto-generated 
app-description files, are installed.

Since there are some differences between the CEA environment and the 
client-side environment which is STILTS's more natural habitat, 
there may be some errors and discrepancies in the auto-generated 
app-description file.  It is attempted to keep these to a minimum - 
please inform the STILTS maintainer if you spot some.


Generating the XML configuration files
--------------------------------------

To generate the XML configuration file(s), use the following command:

   java -classpath stilts.jar uk.ac.starlink.ttools.cea.CeaWriter

If executed with the "-help" flag, this will output a usage message,
something like:

   Usage:
      CeaWriter -help
      CeaWriter -impl -path <app-path> [-task <task>] [-redirects]
      CeaWriter -service [-task <task>] [-redirects]

As this indicates, it can run in two modes: with the -impl flag it 
generates the app-description file used where the service is deployed,
and with the -service flag it generates the service registration 
document which describes the registry entry.  The generated XML is 
written to standard output and can be redirected in the usual way.

In -impl mode it is necessary to give the path of the executable which
will run the STILTS application.

If the optional -task flag is supplied, an app-description which provides
access only to a single STILTS task (contains only a single CEA interface)
will be written.  This may be desirable if an application providing a
less-bamboozling CEA interface is required - it was introduced at user
request so that a standalone tskymatch2 application could be deployed.


Preparing the execution script
------------------------------

The command specified by the -path flag to CeaWriter (see above) can 
just be the stilts script that comes with the STILTS package.  
To use this, extract it from the top level of the stilts.jar file 
(jar xf stilts.jar stilts), set it executable (chmod +x stilts) and 
make sure it is installed in the same directory as the stilts.jar file 
in order to run.

However, it may be better to write a simple invocation script yourself -
this allows you to control items such as the location of the JRE,
heap memory size, and so on.  Here is a template script file:

   #!/bin/sh
   /usr/java/jre1.5.0_10/bin/java \
        -Xmx128M \
        -Djava.io.tmpdir=. \
        -jar /usr/local/cea/stilts.jar \
        -batch \
        -disk \
        "$@"

Line by line:

   java -jar stilts.jar "$@"
      This is the essential part.

   -Xmx128M
      This controls the heap size available to STILTS at run time.
      Using the default (i.e. omitting any -Xmx flag, which may or may
      not be equivalent to -Xmx64M) is probably reasonable, but large 
      crossmatches in particular might require larger values here.

   -batch
      Prevents STILTS from prompting on standard input for missing 
      parameter values.

   -disk
      This causes STILTS to use disk-based temporary storage rather than
      memory-based.  Probably a good idea to include this.

   -Djava.io.tmpdir=.
      -disk (see above) causes temporary files to be written in a directory
      controlled by the java.io.tmpdir system property.  The default is
      probably somewhere like /tmp - if that's of limited size you might
      want to make this assignment so that the space private to the 
      CEA application's execution is used for scratch files instead.


Steps for installation
----------------------

So to deploy STILTS as a CEA application, do something like:

   1.  Obtain the stilts.jar file corresponding to the version of the
       package that you want to deploy:
          wget http://www.starlink.ac.uk/stilts/stilts.jar

   2.  Obtain or write an invocation script (see above).

   3a. Generate the app-description file for the full STILTS deployment
       with the path set to the location of the script:
         java -classpath stilts.jar uk.ac.starlink.ttools.cea.CeaWriter \
              -impl \
              -path /usr/local/cea/bin/run-stilts \
              >app-description.xml

       ... and/or ...

   3b. Generate the app-description file for one or more single STILTS task
       deployments with the path set to the location of the script:
         java -classpath stilts.jar uk.ac.starlink.ttools.cea.CeaWriter \
              -impl \
              -path /usr/local/cea/bin/run-stilts \
              -task tskymatch2 \
              >tskymatch2-app-description.xml

   4. Perform the usual CEA deployment using the app-description.xml file(s)
      (see CEA server documentation).
        

You will also need to prepare a CEA application registration record,
perhaps using the -service flag to the CeaWriter class, but I don't
entirely understand this part - talk to someone who does (Paul Harrison?)

...........................................................................

An up to date copy of this file should be present at the top level of
the stilts.jar distribution file (jar xf stilts.jar README.cea).

Mark Taylor

$Id$
