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. :-)