Astrobrowse Installation Information

Astrobrowse V1.7 Installation

This document indicates how an Astrobrowse node might be installed at a remote site. Since Astrobrowse is a developing system this document should be taken as a guide but is not authoritative. If you have questions please contact Tom McGlynn at tam@silk.gsfc.nasa.gov and Christina Heikkila at cwh@lheamail.gsfc.nasa.gov.

Special Requirements

To run Astrobrowse your site needs:

A Web server capabable of CGI scripting.
Perl5.
The libwww-perl library. This can be downloaded from CPAN.
A cache directory writable by CGI scripts.
Optionally, if you want to automatically receive updates to resource files and have changes to your resource files propagated to others in the Astrobrowse network, you need to install GLU. See http://simbad.u-strasbg.fr/glu/glu.html for information on GLU. If you choose not to install GLU, you can still use the short list of resource files provided in this distribution (glu/*.cfg).
Astrobrowse uses SWISH-E to index the resource files. You can get a copy from http://sunsite.berkeley.edu/swish-e/. If you prefer a different index engine, you can alter the script cgi-bin/astrobrowse/findmatch.pl to call the other indexer.

File Organization

The following file organization suggests specific directory locations based upon usage at the HEASARC. Other sites will wish to modify the directory structures to conform with their own conventions. Currently at the HEASARC one may convert a URL to a file path by replacing http://heasarc.gsfc.nasa.gov with /www/htdocs. We use both ways of designating locations below.

Astrobrowse uses a number of CGI scripts. At the HEASARC these are stored at URLs under http://heasarc.gsfc.nasa.gov/cgi-bin/ab. The following scripts are currently available:

queryall.pl: This is the script which reads the Astrobrowse configuration and presents the initial query form.
exploder.pl: This is called by queryall.pl and actually sends a query to each of the selected sites.
status_update.pl: This updates the status of each of the requests the user has made.
form_entry.pl: This reads information a user has submitted about some HTML form, and then presents a modified copy of that form to the user to fill in with special values specified in the file submit.html.
form_analyze.pl: This reads information from the form created by form_entry and generates a GLU-formatted file.
findmatch.pl: This script looks for matches to user input in resource files and calls queryall.pl to present the matching files to the user.
abfeedback.pl: Feedback form, emails the feedback to the Astrobrowse maintainer.
perl/runquery.pl: This routine is called by exploder.pl to send a single query (which it does via the LWP library).
perl/status.pl: This contains subroutines used by status_update.pl and is also called by exploder.pl.
perl/ab_util.pl: Contains subroutines central to many Astrobrowse scripts. Also, all the machine-specific paths are set here.

Perl libraries.

These are general-purpose Perl libraries which are used in Astrobrowse. Two libraries are included in the distribution:

WEB.pm: This provides very simple functionality for formatting and parsing Web query strings. The HEASARC stores this at: /www/htdocs/cgi-bin/lib/WEB.pm .
libwww-perl: This is used to query other sites. The HEASARC currently uses version 5.46.
JavaScript::JSUtil.pm, ::JSCookies.pm, ::ValidateInput.pm: These three modules simply insert javascript code in the HEAD of queryall.pl. These functions have been tested with IE3.0 and Netscape 2.0, and their successors. To ensure no one else is shut out, the javascript functions only add convenience features - non-JS browsers, and those electing not to enable JavaScript, will still be able to use the full functionality of Astrobrowse. The features added are: cookies which remember which catalogs the user last searched; and form validation functions which duplicate the form validation done on the server side, but let the user know more quickly through JavaScript alerts.

HTML files.

A number of HTML files are used in Astrobrowse: http://heasarc.gsfc.nasa.gov/ab and /ab/info/.

astrobrowse.html (linked to .index.html): The main page.
search_form.html: This form allows users to search your GLU library to see what resources they might want to query.
submit.html: This displays a form which can be used to generate and/or submit GLU-format files to be used in Astrobrowse. This form is entirely optional. But even it you don't use offer it to your users, you may wish to keep it around since it greatly aids in the creation of GLU entries.
skeleton.html_stub: This is a stub for the skeleton.html pseudo-html file. You can create a skeleton.html to help format information about what sites are visitable by Astrobrowse. The stub should be customized by each site according to its needs. Comments in the beginning of the stub describe how it may be used.
quick.html: A short version of the skeleton file.
education.html: A skeleton file suitable for use by non-astronomers.
blank_results.html: This page is displayed in the query results frame until a user actually selects a result to look at.
frametop.html: This document is displayed in the top frame of the query results page.
install.html: This document.
glu_help.html: This describes the format of the GLU entries.
astrobrowse_help.html: Detailed help for users.
tutorial.html: A shorter help document.
cookiehelp.html: Explanation of what users can do by setting cookies.
search_help.html: How to use the search form to find resources.

Images used in Astrobrowse.

All images used in the Astrobrowse system are contained under http://heasarc.gsfc.nasa.gov/ab/images.

astrobrowse.gif: The Astrobrowse logo.
astrobrowse_big_flat.jpg: The Astrobrowse logo, with a drop shadow. This one is the default.
astrobrowse_button.gif: A small logo, suitable for use as a button.
GLUlogo.gif: The logo for GLU.
swish-e2.gif: The logo for SWISH-E.
ssdslogo_sm.jpg: The logo for SSDS.
working.gif: Used to indicate that a given request is still running.
stop_good.gif: Used to indicate that a request completed successfully.
stop_error.gif: Used to indicate that a request completed but an error was detetected. Currently this is assumed when the output file is non-existent or of zero length.
Bluedot.gif: Button to break a results page out of frames.
Redx.gif: Button to delete a resource from the results frame.
checked.gif: Button to check all the checkboxes on the page.
unchecked.gif: Button to uncheck all the checkboxes on the page.

Results cache.: A results cache directory is needed to store results as they are retrieved by Astrobrowse. For the HEASARC the results cache is at http://heasarc.gsfc.nasa.gov/ab/tmp/.
Resource files (glu/*.cfg): These are provided to get you started. If you install GLU, you will use the script glusplit.pl to create the resource files and keep them up to date.
Files which manipulate the resource files: gluexpand.pl Expands the GLU 'short-format' resource entries to the GLU 'long-format' which is needed by Astrobrowse. You shouldn't need this script unless you use the ascii version of the glu.dic. glusplit.pl Splits the GLU resource entries from one large file into one file for each resource. Uses whitespace to determine resource separations, and uses the %ActionName field for the name of the file. update_cfg Creates the index, which is used by the script findmatch.pl.

Setting up an Astrobrowse site

Download the Astrobrowse distribution file http://heasarc.gsfc.nasa.gov/astrobrowse/astrobrowse_v1.5.tar.gz.
Uncompress and untar the distribution file in a scratch area. It will create the subdirectories: cgi-bin, docs, lib, and glu, the README file and an install script. The first directory contains the files that belong in the CGI area for Astrobrowse. The second contains the HTML files and images which belong in the HTDOCS area for Astrobrowse. The lib directory contains the perl modules used. A full libww-perl distribution is included even though only a portion of it is used in Astrobrowse. The vast bulk of the tar file is the libwww-perl library.
Read the README file for instructions on running the install script, then run it.
Make sure that the CGI scripts will have permission (and space) to write data into the cache directory. This may require the cache directory to be owned by the user id under which your HTTP server runs, or to give world-write permission to the cache directory.
Modify the documentation and such to reflect your local site, e.g., you may not wish to display the HEASARC logo or name on the pages.
[Optional] Customize the appearance of sites by editing the skeleton.html file. The skeleton file is used by queryall.pl when presenting a menu of resources to the user. You can create more skeleton files by copying and changing this file.
Try running the queryall.pl script in your Web browser to see if things are working.
Download and install SWISH-E (or some other file indexer) for the search form. If you use a different indexer, you will need to modify the script findmatch.pl.
[Optional] Install GLU, and start your GLU daemon.
Set up a cron table for the scripts that need to be run periodically. There is an example file called crontab_example in the glu directory (the final GLU directory, not the one which was created from un-tarring the distribution file). To create a crontab table, type 'crontab -e', and cut/paste the lines from crontab_example. NOTE: if you are not going to run GLU, then you only need the line that runs CleanupTempDirectory.pl.