Home Contact
Validate the HTML of this page

New Books List

Installation Instructions : Tomcat version for UNIX

New Books List

Copyright 2000-2017, The University of Texas at Arlington 
All rights reserved.  See included LICENSE for particulars.

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

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

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

|------------------------------------------------------------|
|  Version 7.3 for Tomcat WebVoyage                          |
|------------------------------------------------------------|
|  UNIX Installation Instructions                            |
|------------------------------------------------------------|


Prerequisites
-------------

  Perl (recommended minimum version is Perl 5.8)
  Perl modules
     newBooks.pl requires:
         DBI
         DBD::Oracle
     newBooks.cgi requires:
         Encode
         LWP::UserAgent
         Unicode::Normalize
         Socket

  You can run the included "prereqs.pl" script to test for the 
  required prerequisites. 

Installation scenarios
----------------------

There are at least three installation scenarios:
  1) Both the extraction program (newBooks.pl) and the
     CGI program (newBooks.cgi) will reside on the same
     server.  This will be the case if your Voyager
     database server and WebVoyage server are one and
     the same. 
  2) The extraction program (newBooks.pl) will reside on
     the Voyager database server, and the CGI program
     (newBooks.cgi) will reside on a separate WebVoyage
     server.  This case is typical for many Voyager sites.
  3) Both the extraction program (newBooks.pl) and the
     CGI program (newBooks.cgi) will reside on a WebVoyage
     server that is _not_ also the Voyager database server.
     This requires installation of the Perl DBI/DBD modules
     on the WebVoyage server (which in turn, requires that
     an Oracle client be installed).  It also requires
     modifications to the DBI connection code in newBooks.pl
     so that it can connect to a remote Oracle database
     listener.

In these installation instructions:
  {xxxdb} => replace this with your database name
  {skin}  => replace this with the appropriate skin name (e.g. en_US)


====================
Installing the files
====================

  The New Books List package is available at:
        http://rocky.uta.edu/doran/newbooks/download.html

  Download newBooks-7.3.zip to your server. 

  Unzip:

        unzip newBooks-7.3.zip

  Note: The newBooks-7.3.zip file should be unzipped on the
        Voyager server, not on your PC with WinZip. 

  The newBooks-7.3.zip package should contain the following files:

        ./newBooks-7.3/CHANGES
        ./newBooks-7.3/gbsv-jquery.js
        ./newBooks-7.3/INSTALL
        ./newBooks-7.3/jquery-1.2.3.min.js
        ./newBooks-7.3/LICENSE
        ./newBooks-7.3/newBooks.cgi
        ./newBooks-7.3/newBooks.css
        ./newBooks-7.3/newBooks.Chinese
        ./newBooks-7.3/newBooks.English
        ./newBooks-7.3/newBooks.Finnish
        ./newBooks-7.3/newBooks.ini
        ./newBooks-7.3/newBooks.Language
        ./newBooks-7.3/newBooks.pl
        ./newBooks-7.3/newBooks.Swedish
        ./newBooks-7.3/newBooks.txt
        ./newBooks-7.3/newBooks.Welsh
        ./newBooks-7.3/one-transparent.gif
        ./newBooks-7.3/prereqs.pl
        ./newBooks-7.3/README.filenames
        ./newBooks-7.3/README.unicode
        ./newBooks-7.3/searchNewBooks.html

  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 newbooks

  Installation locations

    Place the files in the following locations on the 
    appropriate server(s).

    WebVoyage server:
    =================

      Copy/move these files:

        newBooks.cgi
        gbsv-jquery.js
        jquery-1.2.3.min.js
        one-transparent.gif
        README.filenames

      ...to this directory:

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

      Copy/move these files:

        newBooks.ini
        newBooks.Chinese
        newBooks.English
        newBooks.Finnish
        newBooks.Swedish
        newBooks.Welsh
        newBooks.Language
        newBooks.txt
        README.unicode

      ...to this directory:

        /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/newbooks/ 

      Copy/move these files:

        newBooks.css

      ...to this directory:

        /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/ui/{skin}/css/

      Copy/move this file:

        searchNewBooks.html

      ...to this directory:

        /m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/ui/{skin}/htdocs/help/

    Voyager database server:
    ========================

      Copy/move these files:

        newBooks.pl

      ...to this directory:

        /m1/voyager/{xxxdb}/sbin/

  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  !!!!!  IMPORTANT - File ownerships and permissions  !!!!!
  !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

    After you copy/move the files into the appropriate directory,
    make sure they have these ownerships and permissions.

      Executables scripts (.cgi, .pl, .sh) should have these:
        -rwxr-xr-x   1 voyager  exlibris   ...  {filename}

      All other files should have these:
        -rw-r--r--   1 voyager  exlibris   ...  {filename}


====================
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 the New Books List *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 execute an 
  external patron authentication CGI script. ;-) 

  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:
        #  - external patron authentication adaptor
        #  - New Books List
        #  - ShelfLister, etc. 
        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.

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

=========================
Testing and configuration
=========================

  1) Do a pre-configuration test:
        Before you start configuring the programs, test to see
        if newBooks.cgi works by pointing a web browser to:
          http://YOUR_WebVoyage.server.edu{:port}/vwebv/newBooks.cgi
        It should work "out of the box". (Albeit with the "test" 
        new book data rather than your library's new book data.)
        If it doesn't work, CHECK:
        - FILE OWNERSHIPS AND PERMISSIONS
        - that the top line of newBooks.cgi points to a valid 
          Perl executable
        [Note: links back to the catalog will not work unless
         your library also owns the item in the test database.]
        If the program works OK, go to step 2.
  2) Generate your own data:
        Read the configuration comments in newBooks.pl and then edit 
        the configurable parts so it will run on your system and
        so that the desired options are specified.  
        Run newBooks.pl (should take approx. 2 to 15+ minutes).
          ./newBooks.pl
        Debug and repeat as necessary (and re-read the comments!)
        Debug and repeat as necessary.
        Once you have newBooks.pl working, make it a Voyager cron job
        that runs once a day.  See the man pages for cron and crontab 
        and/or consult your favorite Unix sysadmin book for more info.
        (see: http://rocky.uta.edu/doran/scvugm2001/books.html)
        Problems at this stage generally have to do with the transfer
        of the newBooks.txt file rather than with the extraction of
        data from your Voyager database.  If the program produces a
        newBooks.txt file, then you know that that part of the program
        is working.  Configuration of your servers to allow for remote 
        copy is something that I can provide some instructions for, but
        I can't anticipate the many variables in a particular networking 
        environment.  Read the comments in the transfer section of
        newBooks.pl very carefully, and also read the man pages for
        the "rcp" command and the "rhosts" file. 
  3) Customize newBooks.cgi by editing newBooks.ini:
        Read the configuration comments in newBooks.ini and then edit
        the configurable parts to customize for your library.  If you
        chose months instead of weeks in newBooks.pl, you must choose
        the same option in newBooks.ini.
        Use your browser to test newBooks.cgi against your library's 
        new books file (newBooks.txt) that you generated in step 2.
        Debug and repeat as necessary.
  4) CUSTOMIZE THE APPROPRIATE LANGUAGE MODULE(s) (e.g. newBooks.English)
        as needed or desired.  Note that this step applies to English-only 
        sites, too!  You can change/edit any and all text that makes up 
        the user interface.  Please read the README.unicode help file 
        prior to editing language module files.  Multilingual sites may 
        also want to (have to) refine the translations.  It is also 
        possible to add additional languages using the language module 
        template (newBooks.Language).
  5) Add a New Books search tab:
        When you are ready to go live, follow the instructions below for
        adding a "New Books" search tab.


===============================
Adding a "New Books" search tab
===============================

  To add a "New Books" search tab to all WebVoyage search screens
  requires editing three files.  All three files start at this path:
  "/m1/voyager/{xxxdb}/tomcat/vwebv/context/vwebv/ui/{skin}/" 
 
  Replace {skin} with, for example, en_US

  File 1: "webvoyage.properties"

    Add this:

    # The values for these buttons SHOULD match variables in
    # newBooks.English (or equivalent file for this skin)
    # newbooks.button  => $this_service value
    # newbooks.message => $page_title value
    page.search.buttons.newbooks.button=New Books
    page.search.buttons.newbooks.message=New Books Search

  File 2: "internal.properties"

    Add this:

    page.search.buttons.newbooks.action=newBooks.cgi?sk={skin}

    (Don't forget to replace {skin} with the actual skin name.)

  File 3: "./xsl/userTextConfigs/pageProperties.xml"

    Add the following to the "<searchTabDisplayOrder>" section:

    <tab name="page.search.buttons.newbooks.button"/>


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

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

        As you edit the program files, make sure you regularly 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 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 
        the New Books List.  Please keep that in mind and thoroughly
        read these installation instructions, and the program comments, 
        before contacting me for help.

        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.

        Server network configuration to allow for remote copy (rcp)
        of the newBooks.txt file is a separate issue from whether
        the newbooks programs are functioning as designed.  Since 
        rcp configuration occurs in files that have nothing to do
        with the newbooks programs, there are no code changes I can
        make in the newBooks.pl program to magically make rcp work.
        I will only provide assistance for remote copy (rcp) problems
        if you are willing to give me temporary access to your system. 


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

        Good luck and thanks for choosing the New Books List.  :-)