========================================================================
=============             INSTALL_NOTE FOR UPC            ==============
========================================================================

upc can be used in one of 2 modes:
        - as a character-cell (commandline) interface
        - as a cgi-script on a web server

The commandline interface comes automatically when you install upc in the
"usual" way:

	$ setup upc
	$ upc [options] [products]

(For detailed instructions, see "upc -?" or "man upc").

The cgi-script option requires some configuration on the web serving node.
In brief:
  1) The web server must be configured so that cgi scripts know and can use
     the environmental variables $UPC_DIR, $UPS_DIR and $UPD_DIR.  It must
     also have a suitable version of perl in its path and have PERL5LIB
     defined.
  2) The web server must be able to invoke $UPC_DIR/cgi-bin/upc.cgi as a
        cgi script
  3) [optional, but recommended] You need a "front-page" web form in a known
     location which knows how to call the upc cgi script
      
There are many ways of accomplishing each of the above steps, and you are
free to configure your web server in whatever way suits you best.  The
steps described below are possibly the easiest way, but by no means the
only way, to configure your web server so that it can examine the contents
of various ups databases.

======================================================================

1) The web server must be configured so that cgi scripts know and can use
   the environmental variables $UPC_DIR, $UPS_DIR and $UPD_DIR.  It must
   also have a suitable version of perl in its path, and have PERL5LIB
   defined.

You need to configure your web server to pass these environmental
variables.  For apache (the Fermilab standard web server), you need to
edit the srm.conf file and add (or modify) the line

	PassEnv UPS_DIR UPD_DIR UPC_DIR PATH PERL5LIB

This allows the web server to have access to these variables -- IF they
are defined.  To define the variables on a FUE system using the usual "ups
start" mechanisms, you can "setup upc, ups" (which implicitly sets up upd
and perl) before you start the web server.

For example, if your web server is started via the "ups start" mechanism,
then you may have a file named

	mynode.products

in your $PRODUCTS/.upsfiles/startup directory.  Edit this file and make
sure that it sets up (at least) upc and ups before it does the

	ups start apache

command.

======================================================================

2) The web server must be able to invoke $UPC_DIR/cgi-bin/upc.cgi as a
   cgi script.

You could do this by copying the file $UPC_DIR/cgi-bin/upc.cgi into your
cgi-bin directory.  If you do this, you will need to make sure that you
update the copy in your cgi-bin directory whenever you update the upc
product.

Another way would be to make a link from your cgi-bin directory to the
$UPC_DIR/cgi-bin/upc.cgi script.  Again, you need to make sure that you
keep this link up-to-date when you update the upc product; but with a
symbolic link, it is easy to do an "ls -al" and see where the link points
in order to determine if its pointing to the current release or not.

For web servers on nodes which have an area "/usr/local/products" into
which product maintainers may write, a third semi-automatic way has been
provided:  indirect links to the "current" release of the product, in
/usr/local/products.  (In earlier releases of ups, many of our products
relied upon links in /usr/local/products).

To do this, you need to make a link in your cgi-bin area:

	cd [your-cgi-bin]
	ln -s /usr/local/products/upc/current/cgi-bin/upc.cgi ./upc.cgi

Then, to make sure that the links in /usr/local/products are correct, make
sure that the correct version of upc is declare current in your ups
database, and then 

	ups makelinks upc


When you update to new versions of upc, you will need to 

	ups makelinks upc

in order to update the links in /usr/local/products.

======================================================================

3) [optional, but recommended] You need a "front-page" web form in a known
   location which knows how to call the upc cgi script.

You could write your own web form and put it anywhere you want; the *.html
files in $UPC_DIR/www can provide you with examples of what is needed in
the form.

The www.fnal.gov and www-oss.fnal.gov nodes use a different mechanism,
which you are free to copy.  In the default html source directory, there
is a link to the "current" upc www directory:

	cd [your-html-dir]
	ln -s /usr/local/products/upc/current/www ./upc

The index.html file in that directory then becomes the "default" web page for

	http://www.fnal.gov/upc/
or
	http://www-oss.fnal.gov/upc/

(subject to configuration of the web server on those nodes, which allows
for index.html to be the default if no file is specified in the URL).

You will need to make sure that $UPC_DIR/www/index.html contains the
"correct" front page.  As distributed, this file is a symbolic link to a
dummy.html file; feel free to edit the file as you need.

You will also need to run

	ups makelinks upc

whenever you upgrade upc if you wish to use this configuration.