Home Contact
Validate the HTML of this page

ShelfLister

Installation Instructions

ShelfLister 2.0

Copyright 2003-2009, The University of Texas at Arlington 

Written by Michael Doran, doran@uta.edu
UT Arlington Library, Box 19497, Arlington, TX 76019, USA

See also:  http://rocky.uta.edu/doran/shelflister/

"Voyager" and "WebVoyage" are trademarks of Ex Libris 


|-----------------------------------------------------------|
|  Unix Installation Instructions                           |
|-----------------------------------------------------------|


Prerequisites
-------------
  
  ShelfLister should run on any Unix server that has:
    -- a webserver (e.g. Apache) configured to run CGI scripts
    -- an Oracle database *or* an Oracle client
    -- Perl 5.8 or later
    -- the Perl DBI and DBD::Oracle modules

  For Voyager ILS customers, your Voyager database server should
  meet all the above requirements.  If you have a split server
  arrangement, your Voyager application server (e.g. a WebVoyage
  server) *might* work, provided an Oracle client and the
  Perl DBD::Oracle module has been installed.  

  Note that the Voyager 7 Apache webserver, as setup for Tomcat 
  WebVoyage, probably isn't configured to run CGI scripts. 

  In these installation instructions, replace {xxxdb} in the path
  names with your database name.


Installation steps 
------------------

  Download shelflister-2.0.tar.gz to your server (FTP in binary mode). 

  Unzip and untar the tarball:

	gzip -d -c shelflister-2.0.tar.gz | tar xvf -

  Note: Using an unzip application *other* than gzip (e.g. WinZip) may
	corrupt the Perl executable CGI script.

  The shelflister-2.0.tar.gz tarball should contain the following files:

	./shelflister-2.0/dope.sh
	./shelflister-2.0/INSTALL
	./shelflister-2.0/LICENSE
	./shelflister-2.0/prereqs.pl
	./shelflister-2.0/shelflister.cgi
	./shelflister-2.0/shelflister.English
	./shelflister-2.0/shelflister.ini

  	The dope.sh and prereqs.pl scripts are for doing diagnostics
	and are not a part of the ShelfLister application.

  File ownerships and permissions

	If the files don't untar with the correct ownerships 
	and permissions, please make them look like this: 

	-rwxr--r--   1 voyager  endeavor   ...	dope.sh
	-rwxr--r--   1 voyager  endeavor   ...	prereqs.pl
	-rwxr-xr-x   1 voyager  endeavor   ...	shelflister.cgi
	-rw-r--r--   1 voyager  endeavor   ...	shelflister.ini
	-rw-r--r--   1 voyager  endeavor   ...	shelflister.English

  Installation locations

        The shelflister.cgi script can be placed in whatever directory is
	appropriate for CGI scripts according to how *your* webserver is 
	configured.  The suggestions below are just that -- suggestions. 
	
	For instance, if you are running Apache for the *classic* 
	WebVoyage all of the ShelfLister files would go here:

	/m1/voyager/{xxxdb}/webvoyage/cgi-bin/shelflister.cgi
	                                    ./shelflister.ini
	                                    ./shelflister.English

	If you are running Apache for *Tomcat* WebVoyage, then
        it does not come configured to run CGI scripts, at least
        not under the Tomcat filesystem.  You may have to do the
	Apache CGI configuration yourself (see instructions below).

        Under Tomcat, one recommendation is to place the main 
	shelflister script here:

/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/htdocs/vwebv/shelflister.cgi

	...and the ShelfLister config files here:
/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/shelflister/shelflister.ini
/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/shelflister/shelflister.English

	These directories may have to be created.

	*RECHECK* file permissions and ownerships AFTER the
	files are copied/moved to their installation directories.


Testing and configuration steps
-------------------------------

  1) If needed, configure Apache for CGI
	If your webserver (e.g. Apache) is not already configured 
	to run CGI scripts, do that first.
  2) Configure ShelfLister Oracle database connection parameters 
	Read the configuration comments in the shelflister.ini script
	and edit the "REQUIRED CONFIGURATION" parameters so that the
        application can communicate with your Voyager Oracle database. 
  3) Test
	Point a browser to the ShelfLister script:
	http://yourserver.univ.edu/cgi-bin/shelflister.cgi
          -- or --
	http://yourserver.univ.edu/vwebv/shelflister.cgi

	You should see the ShelfLister barcode entry form.  

	If you see the shelflister.cgi Perl code, then the
	Apache CGI configuration (step 1) was not successful.

        ShelfLister 2.0 is designed to provide informational
	error messages via the browser.  If you get an error
	message, it should indicate what the problem is.
 
	For general troubleshooting, CHECK:
	- FILE OWNERSHIPS AND PERMISSIONS
	- that the top line of shelflister.cgi points to a valid 
	  Perl executable, that has the DBI and DBD::Oracle modules,
	  i.e.:
		#!/m1/shared/bin/perl
  4) Optional configuration
	Go back and make any other desired configuration changes in 
	the shelflister.ini and/or shelflister.English files  
  5) Use 


================================
Voyager 7.0 Apache configuration
================================

  The Apache instance that runs the Tomcat-architected version of
  WebVoyage that is new to Voyager 7.0 probably will NOT come pre-
  configured to run CGI programs (WebVoyage is run by Tomcat).

  Since ShelfLister *is* a CGI program, it won't run until Apache
  is properly configured.  This is not my fault... I'm just the
  messenger here.

  Bonus: This same configuration will enable you to run the New 
  Books List and external patron authentication CGI scripts. ;-)

  The following steps will require root access.

  Determine which is the appropriate Apache configuration file
  (e.g.  {xxxdb}_vwebv_httpd.conf) and make a backup copy.

  Add the following within the vwebv <VirtualHost *:{port}> section:

        # Allow for execution of CGI scripts, such as:
        #  - ShelfLister, etc.
        #  - New Books List
        #  - external patron authentication adaptor
        AddHandler cgi-script .cgi
        <Directory "/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/htdocs">
                Options MultiViews
                AllowOverride None
                Options ExecCGI
                Order allow,deny
                Allow from all
        </Directory>

  Check the syntax of your edited file by running:
	/m1/shared/apache2/bin/apachectl -t

  If the syntax checks out OK, restart Apache in order for the
  configuration change to take effect.

  Note: A "ScriptAlias" directive is not a viable alternative for
  the "AddHandler cgi-script .cgi" directive; the newBooks.cgi script
  needs to run in the same 'virtual' URL path as the other vwebv
  WebVoyage executables.

  Create the following directories (these directories shouldn't already
  exist unless there was a previous installation of New Books List 7.0):

    cd /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/htdocs/
    mkdir vwebv

    cd /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/
    mkdir shelflister

  Place the shelflister.cgi script in this directory:
    /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/htdocs/vwebv/

  Place the shelflister.ini and shelflister.English files in this directory:
    cd /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/shelflister/

  If you think you shouldn't have to mess with Apache configuration
  in order to enable ShelfLister (or the New Books List, or external
  patron authentication), please feel free to let Ex Libris know.


=============
Miscellaneous
=============

Free advice
-----------

	As you edit the shelflister.ini and/or the shelflister.English
	configuration files/scripts, make sure you make backup copies.  
	That way if some configuration change renders Shelf Lister 
	unexecutable and you can't figure out how to fix it, you can 
	always backtrack to a previous working copy.


Bug Reports
-----------

	Please report bugs or installation problems to:

	Michael Doran
	email: doran@uta.edu
	telephone: 1.817.272.5326
	telephone: 1.888.565.9023 x25326 (toll-free in U.S.)


Support
-------

	I am a Systems Librarian with a full time job quite apart from 
	creating, enhancing, documenting, distributing, and supporting 
	ShelfLister.  Please keep that in mind and thoroughly read
	these installation instructions and the program comments 
	before contacting me for help.  Considerable effort has gone
	into the documentation, and chances are good that the answer
	to your question is contained there.  

	This is not meant to discourage you from contacting me,
	particularly in regard to bugs or issues that may impact other 
	users of the software.  I am also very interested in hearing 
	how the installation instructions and other documentation can
	be made more clear or otherwise improved.


That's all folks!
-----------------

	Good luck and thanks for choosing ShelfLister.  :-)