This page describes how to deploy the DSA/Catalog web application to a Tomcat web service container. If you are trying DSA/Catalog in a different container (untested and not recommended), follow the installation instructions for that container.
You can use the Tomcat manager interface to install the DSA/Catalog webapp (see the Tomcat manager instructions).
Alternatively, you can install it "by hand" by simply copying
the DSA/Catalog WAR file into the
webapps directory of your tomcat installation.
Tomcat should then automatically install the web application.
(If it doesn't, try restarting tomcat).
We recommend changing the name of the war file from something
version-specifig (e.g. astrogrid-dsa-catalog-2006.3pl.war) to something generic (e.g. astrogrid-dsa-catalog.war) to
simplify future upgrading.
Once the web application has been installed, a link to its front
page should be visible from within the Tomcat Manager interface
, or you can
visit
http://<hostname>:<port>/<webapp-name>/,
where <hostname> is the fully-qualified
name of the machine where tomcat is installed,
<port> is the port on which tomcat is
installed, and <webapp-name> is the name
of the war file you installed (minus the .war suffix).
Most of the web pages in the DSA/Catalog web application's public interface are password-protected, to restrict access to system administrators only.
To set up administrative access to the protected pages,
edit the tomcat-users.xml file in tomcat's
conf directory, and add the following role:
<tomcat-users>
....
<role rolename="dsaadmin"/>
....
<user username="eurovo" password="eurovo" roles="dsaadmin"/>
....
</tomcat-users>
and then create an administration user who can log in with that role (or add the role to an existing admin user's configuration):
<tomcat-users>
....
<user username="eurovo" password="eurovo" roles="dsaadmin"/>
....
</tomcat-users>
Tomcat will not automatically load the new user and role information, so you will need to stop and start Tomcat to get it to recognise the new user account.
The datacenter uses 'commons-logging' to log messages; on a Tomcat server this is routed to the server's Log4J logger. A default log4j properties file is included in the distribution, and can be found at /WEB-INF/classes/log4j.properties in the web application.
By default, the properties file causes INFO and higher messages to go to std.out (these can be found in the catalina.out file when using Tomcat), INFO and higher messages are stored in pal.log, and DEBUG and higher messages are stored in a rolling file (it is size limited) called pal-debug.log. These latter two are found in ${CATALINA_HOME}/logs/ when running under Tomcat.
When installing several DSA/Catalogs to connect to multiple databases from one server, you can actually share a single physical DSA/Catalog installation between multiple "virtual" DSA/Catalog services.
Each virtual catalog can have its own configuration file, but there will only be a single physical web application installation to upgrade and maintain.
In Tomcat 5, create a new xml configuration file:
$TOMCAT_HOME/conf/Catalina/localhost/$VIRTUAL_DSA.xml
(where $VIRTUAL_DSA is the name you are giving to this particular virtual DSA installation, and $TOMCAT_HOME is the root of your tomcat installation) and put the following contents in it:
<?xml version='1.0' encoding='utf-8'?>
<Context displayName="(Friendly name for this DSA)"
docBase="$TOMCAT_HOME/webapps/$ASTROGRID_DSA"
path="/$VIRTUAL_DSA"
workDir="work/Catalina/localhost/$VIRTUAL_DSA">
<Environment description="Configuration filename"
name="org.astrogrid.config.filename" override="false" type="java.lang.String"
value="/path/to/properties/$VIRTUAL_PROPERTIES_FILENAME">
</Context>
IMPORTANT: Change the cyan element to match the name of your installed webapp in the $TOMCAT_HOME/webapps directory, the blue elements to the desired name for your virtual DSA, the red element to match the full path to the properties file for your new virtual DSA, and the green element to match the full path to your tomcat installation).
Once you have finished, restart tomcat to reload the configuration for your new virtual DSA/catalog webapp.
The new context $VIRTUAL_DSA actually
forwards all requests to the base $ASTROGRID_DSA webapp,
but with the configuring properties set from the file
$VIRTUAL_PROPERTIES_FILENAME. These properties
will not be
overwritten when you update the base $ASTROGRID_DSA
webapp.
Similarly you can have many 'virtual contexts' like this that refer to one docbase, and this saves not only disk space and tomcat's runtime memory, but also effort when updating the software.
In Tomcat 4.x, add this to your server container's server.xml :
<Context path="/$VIRTUAL_DSA"
docBase="$TOMCAT_HOME/webapps/$ASTROGRID_DSA"
debug="9" reloadable="true">
<Environment name="org.astrogrid.config.filename"
value="/path/to/properties/$PROPERTIES_FILENAME" type="java.lang.String" />
</Context>
IMPORTANT: Change the cyan element to match the name of your installed webapp in the $TOMCAT_HOME/webapps directory, the blue elements to the desired name for your virtual DSA, the red element to match the full path to the properties file for your new virtual DSA, and the green element to match the full path to your tomcat installation).
The above entry creates a context
$VIRTUAL_DSA that actually
forwards all requests to the $ASTROGRID_DSA webapp,
but with the configuring properties set from the file
$PROPERTIES_FILENAME. These properties will not be
overwritten when you update the base $ASTROGRID_DSA
webapp.