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