Tomcat deploy

Deploy the war file into the Tomcat container, either copying the war file into the WebApps directory, or by using the Tomcat manager deployment tool.

For more details about how to do this, check your Tomcat manual page.

Service properties

To function correctly, the FileStore service needs to know four things

  • The service configuration name
  • The IVO identifier for this service in the global registry
  • The base URL for HTTP access to files in the store
  • The location of the local repository

Service name

If you are only deploying one FileStore service, just set the service name to org.astrogrid.filestore and skip the rest of this section.

In order to support multiple FileStore services within one installation, each FileStore service can be given a different name.

Each service uses its name as a prefix to lookup the configuration properties for that service.

This feature is used primarily in the AGINAB test environment to enable multiple FileStore services to be configured from one shared configuration file.

If the service name is set to my.filestore

Then the service will then look for the rest of its configuration properties using this as a prefix. 

my.filestore.service.ivorn=ivo://authority/resource
my.filestore.service.url=http://hostname:port/context/filestore
my.filestore.repository=/var/filestore/...
This means that one configuration file can support more than one FileStore service. 
#
# Configuration for filestore one
test.one.service.ivorn=ivo://authority/resource
test.one.service.url=http://hostname:port/context/filestore
test.one.repository=/var/filestore/one
#
# Configuration for filestore two
test.two.service.ivorn=ivo://authority/resource
test.two.service.url=http://hostname:port/context/filestore
test.two.repository=/var/filestore/two

The IVO identifier

In order to generate the correct identifiers for containes within the store, the FileStore service needs to know its IVO registry identifier.

This should be set to the same IVO identifier used to register the service in the global registry. 

ivo://authority/resource

The base URL

In order to generate URLs for external components to access data within the store, the FileStore service needs to know the base URL.

This should be set to the URL of the Tomcat server, the context for the deployed WebApplication, plus the servlet name, filestore.

Unless you are modifying the context yourself, the WebApplication context will be the same name as the deployed war file. If the war file is called astrogrid-filestore.war, then the WebApplication context will be astrogrid-filestore.

If the URL for your Tomcat server is http://example.org:8080/, and the deployed war file was called astrogrid-filestore.war, then the base URL will be 

http://example.org:8080/astrogrid-filestore/filestore

The local repository

The FileStore service needs read and write access to a local directory on your system to store its data files. This directory should not be located within the WebApplication itself, otherwise deploying an updated war file may delete the stored data files.

Unix example : 

/var/astrogrid/filestore/
Windows example : 
C:\\astrogrid\\filestore\\

TODO - Need to check the syntax for a Windows file path.

Service configuration

The FileStore service can be configured using one of the following methods

  • Environment entries in the webapp web.xml file
  • Environment entries in the webapp context file
  • Properties in a global configuration file

You only need to use one of the three methods

web.xml entries

To add the configuration properties to the WebApplication web.xml file, deploy the WebApplication war file into Tomcat. If your Tomcat installation is configured to automatically deploy WebApplications, then it will unpack the war file. If not, then you may need to unpack the war file manually.

Once the war file has been unpacked, you can get to the web.xml file located in the WEB-INF directory within the the WebApplication.

Edit the web.xml file and add the following env-entry values between the servlet and servlet-mapping elements. 

<web-app>
    ....
    <servlet>
    ....
    </servlet>
    <env-entry>
        <description>The filestore service name</description>
        <env-entry-name>org.astrogrid.filestore.service.name</env-entry-name>
        <env-entry-value>org.astrogrid.filestore</env-entry-value>
        <env-entry-type>java.lang.String</env-entry-type>
    </env-entry>
    <env-entry>
        <description>The filestore service identifier</description>
        <env-entry-name>org.astrogrid.filestore.service.ivorn</env-entry-name>
        <env-entry-value>ivo://authority/resource</env-entry-value>
        <env-entry-type>java.lang.String</env-entry-type>
    </env-entry>
    <env-entry>
        <description>The filestore service location</description>
        <env-entry-name>org.astrogrid.filestore.service.url</env-entry-name>
        <env-entry-value>http://example.org:8080/astrogrid-filestore/filestore</env-entry-value>
        <env-entry-type>java.lang.String</env-entry-type>
    </env-entry>
    <env-entry>
        <description>The filestore repository location</description>
        <env-entry-name>org.astrogrid.filestore.repository</env-entry-name>
        <env-entry-value>/var/astrogrid/filestore</env-entry-value>
        <env-entry-type>java.lang.String</env-entry-type>
    </env-entry>
    <servlet-mapping>
        ....
    </servlet-mapping>
    ....
</web-app>

Replace the values shown in bold with your own settings.

Context entries

To add the configuration properties to the WebApplication context, you will need create a new context xml file for the WebApplication.

In the current Tomcat 5.0.x series, the context files are located in the $CATALINA_HOME/conf/[enginename]/[hostname]/ directory.

In a standard deployment of Tomcat, this would be $CATALINA_HOME/conf/Catalina/localhost/

For more details about your specific installation check the Tomcat manual page.

You will need to add the following environment entries to the WebApplication context. 

<Context path="/astrogrid-filestore">
    <Environment
        name="org.astrogrid.filestore.service.name"
	description="The filestore service name"
        override="false" type="java.lang.String"
        value="org.astrogrid.filestore"/>
    <Environment
        name="org.astrogrid.filestore.service.ivorn"
	description="The filestore service identifier"
        override="false" type="java.lang.String"
        value="ivo://authority/resource"/>
    <Environment
        name="org.astrogrid.filestore.service.url"
	description="The filestore service location"
        override="false" type="java.lang.String"
        value="http://example.org:8080/astrogrid-filestore/filestore"/>
    <Environment
        name="org.astrogrid.filestore.repository"
	description="The filestore repository location"
        override="false" type="java.lang.String"
        value="/var/astrogrid/filestore"/>
</Context>

Replace the values shown in bold with your own settings.

Properties file

The third way of configuring the FileStore service is using an external properties file.

This may be useful if you want to put the configuration properties for more than one AstroGrid service in one shared properties file.

You will still need at least one property, the location of the configuration file, in either the WebApplication web.xml or context.

To configure this in the WebApplication web.xml file, add the following environment entry. 

<web-app>
    ....
    <servlet>
        ....
    </servlet>
    <env-entry>
        <description>The astrogrid configuration URL</description>
        <env-entry-name>org.astrogrid.config.url</env-entry-name>
        <env-entry-value>file:///etc/astrogrid.properties</env-entry-value>
        <env-entry-type>java.lang.String</env-entry-type>
    </env-entry>
    <servlet-mapping>
        ....
    </servlet-mapping>
    ....
</web-app>

To configure this in the WebApplication context, add the following environment entry. 

<Context path="/astrogrid-filestore-two-SNAPSHOT">
    <Environment
        name="org.astrogrid.config.url"
	description="The astrogrid configuration URL"
        override="false" type="java.lang.String"
        value="file:///etc/astrogrid.properties"/>
</Context>

The rest of the service properties can be configured in the properties file. 

#
# The filestore service name.
org.astrogrid.filestore.service.name=org.astrogrid.filestore

#
# The filestore service identifier.
org.astrogrid.filestore.service.ivorn=ivo://authority/resource

#
# The filestore service location.
org.astrogrid.filestore.service.url=http://example.org:8080/astrogrid-filestore/filestore

#
# The filestore repository location.
org.astrogrid.filestore.repository=/var/astrogrid/filestore

To configure more than one FileStore service in the same configuration file, set different names in the web.xml or context of each service.

Registry entries

To complete the installation, you will need to register the FileStore service in the global registry.

You will need to create a new resource entry in the registry with the following information 

    <vr:Resource
        status="active"
        updated="2005-03-11T06:03:29Z"
        xmlns="http://www.ivoa.net/xml/VOResource/v0.10"
        xmlns:vr="http://www.ivoa.net/xml/VOResource/v0.10"
        xmlns:vs="http://www.ivoa.net/xml/VODataService/v0.5"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="vr:Service"
        >
        <title>Astrogrid VO Store</title>
        <identifier>ivo://authority/resource</identifier>
        <curation>
            <publisher>Filestore Service</publisher>
            <contact>
                <name>Contact name</name>
                <email>contact@example.org</email>
            </contact>
        </curation>
        <content>
            <subject>VOSpace file store</subject>
            <description>VoStore file store</description>
            <referenceURL>http://www.ivoa.net/</referenceURL>
            <type>Archive</type>
        </content>
        <interface xsi:type="vs:WebService">
            <accessURL use="full">
                http://example.org:8080/astrogrid-filestore/services/FileStore
            </accessURL>
        </interface>
    </vr:Resource>

Replace the values shown in bold with your own settings.

TODO - Add the 'service kind' element ....

TODO - Check this entry is correct ....