Table of Contents
Installation
Requirements
The GDS can run on any UNIX platform for which both Java and GrADS are
available.
You will need a Java Virtual Machine (JVM) that supports Java v1.2 or
higher. Enter java -version at the Unix command prompt to
find out what JVM you have currently installed on your system. The Java
Virtual Machine is a free download either from Sun
Microsystems, or your operating system manufacturer's website.
You will also need GrADS. Because the server uses some new features in
GrADS, you will need version 1.8 or higher. Handling station data and
client uploads requires version 1.9 or higher. The latest version of GrADS
is available at the GrADS home page.
return to table of contents
Download and setup
The latest version of the GDS is available at the GDS
home page as a compressed tar archive.
You do not need root user access to run the GDS. There is no build or
system install process, because it is a cross-platform Java application.
And any number of GDSes can be run on the same system, as long as they
are configured to use different ports (see Tomcat settings)
After unpacking the archive, all you need to do is edit the configuration
file, and tell the GDS where to find GrADS, by editing the <invoker>
tag. If you are not using a full GrADS distribution, make sure the GrADS
executable you specify is capable of opening the types of dataset you
wish to use.
At ths point you should be able to start the server and view the example
dataset.
return to table of contents
Putting your datasets online
Next you will want to put your data online.
First, make sure that all of your datasets are ready to be opened by
GrADS. (for instance, if you have GRIB data, you will need to generate
CTL and map files).
Once this is done, all you need to do to put your datasets online is
tell the GDS where they are, using the configuration file. This is done
by adding <dataset>,
<datadir>, and
<datalist> tags inside
the <data> tag. If
you want, you can organize the way the data appear online using <mapdir>
tags.
Note that the GDS does not attempt to access datasets until the first
time they are requested by a client, so it may not immediately complain
about unusable datasets. Before you invite others to use your server,
therefore, it is a good idea to make sure that all of the datasets you
are serving work properly, by opening them in your own DODS-enabled client.
Also note that DODS does not provide a way to notify clients that a given
dataset has changed. Thus, if you are planning to serve a changing collection
of data, such as real-time observations, plan to always post new data
under new handles, rather than overwriting the contents of existing datasets.
Otherwise, a user making the wrong assumption could unknowingly generate
incorrect results, or become very confused.
Once you have your data loaded and working, it is highly recommended
that you familiarize yourself with the configuration options and administrative
tools available by reading the remainder of this documentation.
return to table of contents
Controlling the server
Starting and stopping
There are four scripts in the server home directory that are used to
control the GDS:
startserver - Starts the GDS as a background task.
stopserver - Shuts down the GDS.
rebootserver - Restarts the GDS
cleanup - Restarts the GDS, deleting all temporary files
Notes:
- In general, the
stopserver script should be preferred
to killing the server process, as it allows the GDS to shut down gracefully.
- Once the GDS is running, it must be stopped before it can be started
again. Otherwise,
startserver will print a Java "ConnectException"
message and fail.
- If the GDS fails because of an invalid configuration, Tomcat will
start anyway. Thus, when the GDS prints an invalid configuration message,
the
stopserver script must be run before starting it again.
return to table of contents
Web-based administration
The GDS has a web-based administration interface which is accessed by
URLs of the form:
/admin?auth=authorization_string&cmd=command_string
The authorization_string given must match the auth
setting given in the <service-admin>
configuration tag. The command_string can be one of the following:
reload: Checks for changes to the server configuration.
This updates the data catalog, privilege sets, and all other settings
contained in the GDS configuration file, without the need to take the
server offline.
clear: Removes all temporary entries from the catalog.
return to table of contents
Checking the server status
The script check_gds, found in the servers' home directory,
can be used to notify the administrator by email and automatically restart
a GDS if it goes offline. This script requires the lynx
web browser, or some other command-line utility that can download documents
via HTTP.
To use the script, edit it to use the base URL and home directory of
the server it is to check, and add it as a cron job with the desired frequency.
Once in the crontab, the script can be temporarily disabled by placing
a file called block_check_gds in the home directory of the
GDS being checked.
return to table of contents
Configuration
Startup parameters
The startup script, startserver, contains the following
settings.
HEAP_SIZE: the amount of memory that the Java Virtual Machine
will reserve for Tomcat and the GDS.
By default, the GDS is set to use 150MB. However, under heavy usage,
with large numbers of datasets, it may need more than this. Conversely,
with only a few datasets online and occasional use, it will need far less.
It is worth experimenting with different heap sizes if you want to reduce
the GDS footprint, or if the GDS is reporting out of memory errors.
CONFIG_FILE: the name of the configuration file to use.
By default this is set to gds.xml. If the pathname is relative,
it is resolved with respect to the home directory of the server.
return to table of contents
Configuration file settings
The GDS derives settings for all of its modules from an
XML configuration file. The name of this file is specified in the startup
script; the default is gds.xml. This file is read every time
the server starts, and every time a reload command is given
using the administrative web interface.
The configuration file reference
describes the XML tags that can be used in this file.
return to table of contents
Tomcat settings
The
configuration file for Tomcat is tomcat/conf/server.xml.
This file can be edited to change
the network port that the GDS runs on, and to increase the size of the
connection pool, among other things.
An explanation
of Tomcat and the settings in its configuration file can be found at the
Tomcat home page
return to table of contents
Security
Both Tomcat and the GrADS-DODS Server support IP-address-based
security. Each can be given its own security settings. Tomcat will allow
or deny access to the server based on the settings in its configuration
files. For finer grained control, use the <ip_range>
and <privilege>
tags in the GDS configuration file. These settings allow or deny access
to specific datasets and server features.
return to table of contents
Advanced Topics
Static web pages
The GDS comes with some static web pages which can be accessed using
Tomcat (including this manual). These pages are located in the subdirectory
tomcat/webapps/ROOT. In general, putting your static content
on a separate web server is recommended, since will usually be more efficient
than using Tomcat for this. However, Tomcat's static content directory
provides an easy way to put up some information about the datasets you
are serving, without setting up a separate web server.
return to table of contents
Integrating with Apache
The GDS can fairly easily be integrated into an existing Apache web site.
All that is required is to set up the link between Tomcat and Apache.
Consult the Tomcat
home page for more on this process.
return to table of contents
Deploying to a different servlet container
It is not necessary to use the copy of Tomcat that is distributed with
the GDS, to run the GDS. Any servlet container that supports the Java
Servlet API 2.2 or higher can be used.
The GDS web application is in the directory tomcat/webapps/dods.
You can generate a Web Application archive (WAR) file by running the makewar
script under the path src/. This will generate an archive
called dods.war. To add the WAR to your servlet container,
follow the servlet container's instructions.
Once you have added it, you will need to set the property anagram.home
to the directory containing the rest of the GDS distribution. This can
be set either as a Java system property (using the -d switch
when invoking Java) or as a servlet context property (follow the servlet
container's instructions).
return to table of contents
Building from source
Source code is included with the GDS, under the path src/.
- To generate Java documentation from the source code, change to
src/
and run the makedoc script.The documentation will be placed
in src/doc/.
- To recompile the source code, change to
src/ and run
the makejar script.
Please note that, while you are welcome to browse and modify the source
for your own purposes, and submit patches and/or new features to COLA,
you are not granted permission to distribute modified versions of this
software.
return to table of contents
|