Instructions for installing JGOFS V2.2 "fresh" (i.e., not upgrading from V2.00)
-------------------------------------------------------------------------------
Dennis Schmidt
October 10, 2009


This file is  README_jgofs-V2.2_INSTALL_NEW.  Distributed in file  
jgofs-V2.2.tar, it provides instructions for installing a new JGOFS V2.2 
data server.

IMPORTANT:
If what you want to do is upgrade an existing JGOFS data server from V2.00 
to V2.2, DON'T use these instructions; instead, use the instructions 
in file  README_jgofs-V2.2_INSTALL_UPGRADE, also distributed in file  
jgofs-V2.2.tar.


A note about the "readme.*" files in this directory and in the  src  tree:  
Those files contain detailed documentation about the sub-modules assembled 
into this release.  For the installation procedure detailed in the present 
file, you will not need to consult them.  They are available in case you 
ever do need detailed information about the sub-modules.



============================================================================
Preliminary step:  Unpack file  jgofs-V2.2.tar  in a new directory to be 
================   the root directory of the new JGOFS V2.2 data server

To create a new JGOFS V2.2 data server, if you haven't already done the 
following you will need to:
	- create a new directory;
	- set permissions for other users to be able to read and execute 
	   files under the directory;
	- make it the current working directory;
	- put the  jgofs-V2.2.tar  file into the directory;
	- unpack the  jgofs-V2.2.tar  file there.

These commands accomplish those tasks:
	mkdir  <JGOFS server root directory>
	chmod  o+rx  <JGOFS server root directory>
	cd  <JGOFS server root directory>
	cp  -p  <wherever jgofs-V2.2.tar file is>  .
	tar  xfv  jgofs-V2.2.tar

In these commands, replace "<JGOFS server root directory>" with the path 
to your JGOFS server root directory, and replace 
"<wherever jgofs-V2.2.tar file is>" with the appropriate path.

The "tar" command will unpack five files, including this one.

Don't remove the  jgofs-V2.2.tar  file from the directory.



============================================================================
Step (1):  Use  jgofs-V2.2_1install_script.pl  
========   to unpack the new V2.2 distribution


Run the initial script to unpack the new V2.2 distribution:

	./jgofs-V2.2_1install_script.pl


Note that this is the only action you will take in this step, except for 
checking the results.  The following paragraphs explain the results and 
how to check them.


Running the  jgofs-V2.2_1install_script.pl  script will:

	- create file  log_jgofs-V2.2_1install_<timestamp>, in the 
    current working (server root) directory, where 

	    "<timestamp>" is replaced by a 14-digit string 
	     identifying the date and time of running the script

	    (we will use this notation throughout these instructions); 

    this file is a log of the running of the script;

	- populate the current working directory, making it the root of 
    an un-customized JGOFS V2.2 data server.


The script will terminate early if there is a problem at any point.  If 
the script finds that the directory it's running in isn't empty except for 
the  jgofs-V2.2.tar  file and its contents, the script will report the 
problem on-screen and stop.  If the directory looks OK, the script will 
start the log file (log_jgofs-V2.2_1install_<timestamp>) and record the 
progress of the subsequent steps there.  You will need to check the log 
file when the script is finished, to assure that each step finished without 
errors.

This is the sequence of steps recorded in the  
log_jgofs-V2.2_1install_<timestamp>  file:

	- Unpack the gzipped tar file containing the actual V2.2 
	   distribution; this will produce a long list of files in the 
	   log file.

	- Install the un-customized V2.2  src/lib/makefile.jgofs  file.

	- Remove unneeded and no-longer-needed files unpacked from  
	   jgofs-V2.2.tar; this will produce, in the log file, a list 
	   of the files removed.



============================================================================
Step (2):  Customize and build your new V2.2 distribution
========

-----
(2.1)  Customize file  build-env.pl  for this data server.  The following 
-----  are likely to be all the lines that you will or might need to edit.  
These summaries show the lines as they appear in the distributed file, and 
they briefly explain the options.

(Note:  Be sure it's file  build-env.pl  that you customize, not the 
unused file  _build-env_.pl.)

	line 183:
		$opsys = "linux";
		(The standard values are "linux", "Solaris", "Irix")
	line 196:
		$perl_location = "/usr/bin/perl";
		(You can find Perl's location by typing the command, 
		 "which perl")
	line 202:
		$server_name = "gb9.whoi.edu";
		(Substitue your server's name)
	line 203:
		$port = 80;
		(This will be correct for most servers)
	line 212:
		$button_images_server = "globec.whoi.edu";
		(You can serve button images from this URL, or you can serve 
		 local copies, already installed on your server or downloaded 
		 via anonymous FTP from the  /pub/images  directory on  
		 globec.whoi.edu ; the file is  jgofs_buttons.tar )
	line 214:
		$button_images_dir = "images";
		(This is correct for the globec button images server)
	line 221:
		$display_data_url=TRUE;
		(Set to FALSE if you don't want to see the data 
		 object specifier as a header line on data page displays)
	line 226:
		$background_color="ffffff";
		(This is white; the successive pairs of characters are the 
		 hexadecimal codes for the intensities of red, green, and 
		 blue components, each ranging from 0 ("00") to 255 ("ff"))
	line 233:
		#$dmoname = "Data Server";
		(Either leave this line commented out (which will set $dmoname 
		 to "$server_name -- " (where $server_name is the string set in 
		 line 202)), or uncomment the line and change the string as 
		 desired)
	line 241:
		#  $program = "";
		(Leave this line commented out)
	line 462:
		$objdir = "/";
		(Leave unedited if objects are to go directly into the 
		 objects  directory, or name a subdirectory (following 
		 the '/'))


-----
(2.2)  Build the V2.2 data server, saving the output in a log file; 
-----  you might create a new log file for the rest of the installation, 
as illustrated here, or extend the log file created in step (1), whose 
name has the form  log_jgofs-V2.2_1install_<timestamp>.

The syntax for sending the output to the log file varies according to which 
command interpreter ("shell") you are using; the command  "printenv SHELL"  
will tell you which it is, if you're not sure.  Then use the syntax 
appropriate for your shell:

For bash or sh:
	./build.pl  >>log_jgofs-V2.2_2build_and_test  2>&1

or, for tcsh or csh:
	./build.pl  >>&! log_jgofs-V2.2_2build_and_test


-----
(2.3)  Check the output in the  log_jgofs-V2.2_2build_and_test  file.
-----  Note that it's normal (i.e., it's not a problem) to see several 
instances of a pair of lines of this form (with various text for the 
various *s in the string, "*/src/*/makefile.*"):

 *** make file */src/*/makefile.* does not contain appropriate
 *** macro name (CONFIG_FILE) to force makes



This completes the installation and customization of your V2.2 data server.



============================================================================
Step (3):  Test operation from the command line
========

If your shell is bash or sh:
	bin/listvar  /test  >>log_jgofs-V2.2_2build_and_test  2>&1

or, if your shell is tcsh or csh:
	bin/listvar  /test  >>&! log_jgofs-V2.2_2build_and_test

should produce, at the end of the  log_jgofs-V2.2_2build_and_test  file, 
a hierarchical list of variables.


Then, if your shell is bash or sh:
	bin/list  -f  -n  /test  >>log_jgofs-V2.2_2build_and_test  2>&1

or, if your shell is tcsh or csh:
	bin/list  -f  -n  /test  >>&! log_jgofs-V2.2_2build_and_test

should produce, at the end of the  log_jgofs-V2.2_2build_and_test  file, 
a "flattened" table of data using those variables.



============================================================================
Step (4):  Set up and test Web access
========

-----
(4.1)  The  httpd.conf  file for the data server you are setting up needs 
-----  to contain an entry of this form:

	ScriptAlias /jg/ <JGOFS root directory>/htmlbin/

where "<JGOFS root directory>" is the full path to the JGOFS root directory.
(You may need the assistance of a system administrator to create the basic 
server setup, to direct you to the relevant  httpd.conf  file, and to restart 
the server after any editing you do in the  httpd.conf  file.)


-----
(4.2)  When the server is set up, test Web access to the JGOFS system 
-----  by using your browser to go to this address:

	http://<server name>/jg/serv/test.html0

where "<server name>" is your server's name (one of ours, for example, is 
globec.whoi.edu).

This should produce the "/test ---- Level 0" display, including links and 
buttons that should allow you to examine the test data and metadata in various 
ways.


-----
(4.3)  A simple way to provide a page from which the user can link to 
-----  the JGOFS system (and on which you may provide whatever other 
information you wish) is the following:

- You will need to create the directory that is specified as the server's  
  DocumentRoot  in the  httpd.conf file -- e.g.,  
  <JGOFS root directory>/htdocs; the JGOFS installation won't have created it.

- In that directory, create file  index.html -- it is the page the user will 
  see upon entering this URL:

	http://<server name>

  where "<server name>" is replaced by the value you provided for  
  $server_name  on line 202 of  build-env.pl  (above, step (2.1)).

- On the  index.html  page, include a link like this one:

	<a href="/jg/dir">Access data objects in main objects directory</a>

  where you should replace "Access data objects in main objects directory" 
  with the text you want to use to label the link.

  Clicking on this link will invoke the "dir" script in the 
  <JGOFS root directory>/htmlbin/  directory ( /jg/  is that directory's 
  alias).  The "dir" script will give access to the objects specified in the  
  .remoteobjects  file in the  <JGOFS root directory>/objects  directory, and 
  to objects in subdirectories of that directory.

  To provide direct access to objects in a subdirectory of the main  objects  
  directory -- for example, objects in directory 
  <JGOFS root directory>/objects/b_objs -- specify the subdirectory in the 
  link, like this:

	<a href="/jg/dir/b_objs/">Access data objects in b_objs subdirectory</a>

  where you should replace "Access data objects in b_objs subdirectory" with 
  the text you want to use to label the link.
