ShelfLister
Installation Instructions
ShelfLister
Copyright 2003-2008, The University of Texas at Arlington
Written by Michael Doran, doran@uta.edu
UTA 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 is designed to be installed on a Voyager database
server. Perl and the Perl DBI and DBD::Oracle modules are
required and should already be installed by Ex Libris.
In these installation instructions:
{xxxdb} => replace this with your database name
Installation steps
------------------
Download shelflister-1.4.tar.gz to your server (FTP in binary mode).
Unzip and untar the tarball:
gzip -d -c shelflister-1.4.tar.gz | tar xvf -
Note: Using an unzip application *other* than gzip (e.g. WinZip) may
corrupt the Perl executable CGI script.
The shelflister-1.4.tar.gz tarball should contain the following files:
./shelflister-1.4/CHANGES
./shelflister-1.4/INSTALL
./shelflister-1.4/shelflister.cgi
CHANGES (text file)
A list of enhancements and bug fixes by version.
INSTALL (text file)
This file.
shelflister.cgi (Perl script)
A CGI/Perl program that queries the Voyager database and returns
a shelf list.
File ownerships and permissions
If the files don't untar with the correct ownerships
and permissions, please make them look like this:
-rwxr-xr-x 1 voyager endeavor ... shelflister.cgi
Installation location
Place the file in the following location (see note below)
on the Voyager database server:
/m1/voyager/{xxxdb}/webvoyage/cgi-bin/shelflister.cgi
#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# Voyager 7.0 "Tomcat" version of WebVoyage
#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
# If you have upgraded to Voyager 7.0 and are running
# the Tomcat version of WebVoyage exclusively, then
# you may have to do some Apache configuration and
# the shelflister.cgi script will likely have to
# be placed in a different directory than the one
# above. If so, refer to the Voyager 7.0 Apache
# Configuration section below.
*RECHECK* file permissions and ownerships AFTER the
files are copied/moved to their installation directories.
Note: This application will *not* run on a separate
WebVoyage server without additional configuration and
software.
If you only have Apache configured to run the Tomcat
version of WebVoyage, then you wil need to configure
a different directory for cgi scripts.
Testing and configuration steps
-------------------------------
1) Configure
Read the configuration comments in the shelflister.cgi script
and edit the "REQUIRED CONFIGURATION" parameters so that the
application can communicate with your Voyager Oracle database.
2) Test
Point a browser to the ShelfLister script:
http://voyager_server.univ.edu/cgi-bin/shelflister.cgi
You should see the ShelfLister home page. If you get an
error message instead of the home page, CHECK:
- FILE OWNERSHIPS AND PERMISSIONS
- that Perl is installed (perl -v)
- that the top line of shelflister.cgi points to a valid
Perl executable, i.e.:
#!/m1/shared/bin/perl
(note: the "-w" switch is optional)
If you get an error when clicking on the Call Number Entry
Form, then your Oracle configuration (e.g. username/password)
may not be correct.
If the program works OK, go to step 3.
3) 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.
Edit the appropriate Apache {xxxdb}_vwebv_httpd.conf file in
/m1/shared/apache2/conf/ActivatedVirtualHosts/
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>
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
Place the shelflister.cgi script in this directory:
/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/htdocs/vwebv/
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 let Ex Libris know.
=============
Miscellaneous
=============
Free advice
-----------
As you edit the shelflister.cgi script, make sure you make
backup copies. That way if some configuration change renders
the program 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. :-)