DLXS Step by Step Installation

Install steps

Note: Before starting, know that if for any reason the install is unsuccessful, you may repeat the process. Simply delete the $DLXSROOT directory (if it has been created) and run Installer again. In order to do a reconfiguration of a successful install simply rerun Installer again and answer R when prompted to do an initial install versus a reconfiguration.

You can choose to install

If installing from the CD-ROM, enter the following:

      % cd /cdrom
        % perl Installer.pl
    

If installing from a directory on the hard drive into which you have copied the necessary files, enter the following:

      % cd tarfile-dir
        % perl Installer.pl
    

If installing from a directory (somedir) where you have mounted the ISO image file, enter the following (assuming release 11 files and Linux syntax):

      % mount -o loop dlxs_open_11.iso somedir
        % cd somedir
        % perl Installer.pl
        % umount somedir
    

The install program will run and prompt you to answer a number of questions. Note: Installer.pl does not hard-code a Perl hash bang so be sure to run it as an argument to the Perl command line as shown above.

What follows is an annotated version of the screen dialogue from an actual run of Installer. Because this installation was performed on a machine having all the necessary binaries and Perl modules supplied, most of the answers can be supplied by just hitting [RETURN]. Installer interactions look like

   this

while annotations for the purposes of this documentation look like this.


Beginning of annotated screen dialogue:

   Welcome to DLXS Installer.  Press 'q' at any time to quit
       Compatible with DLXS Release 11.

   Which platform are you using? (SunOS/Linux) [SunOS]
  

The preceding is a check to make sure the platform is supported.

Where is Perl installed? [/usr/bin/perl]

Enter the full path to perl. The default is from the 'which' command..

   Checking for Perl installation for required modules...
   All required modules were found.
    

All required Perl modules were found. If any were missing or if any differed from the recommended versions, the Installer would have listed them. We recommend installing them beforehand. You may abort the install at this point (Ctrl-C) and restart it later.

   The next series of questions concerns where certain
   required binaries are installed in your system.
    

Enter full paths to the binaries you choose to install based on the middleware classes you chose to install as directed. See Binaries.

   Where is XPAT installed? [/l/local/bin/xpat] 

   Do you want to use tif2web (required for TextClass page viewer)? [Y] 
   Where is tif2web installed? [/l/local/bin/tif2web] 

   Do you want to use c42pdf (required for TextClass page viewer)? [Y] 
   Where is c42pdf installed? [/l/local/bin/c42pdf] 

   Do you want to use MrSid (required for ImageClass)? [Y] 
   Where is mrsid_retrieve installed? [/l/local/bin/mrsid_retrieve] 

   Etc.

        **********************************
                I m p o r t a n t !
        **********************************

  The next question allows you to pick between performing a first-time
  installation or reconfiguring an existing installation.

  For a FIRST-TIME INSTALLATION you will be asked where to install DLXS.
  You should supply a full path.  For example, if you choose
  /l1/dlxs-release-11, the installer will:

        (1) create an install directory named /l1/dlxs-release-11
        (2) mark it with a timestamp
        (3) extract the tarfiles into that directory.

  The directory path you choose will be known as DLXSROOT.

  This install directory is also inserted as a string into a number
  of working and configuration example files.

  For your webserver, the DLXSROOT variable and its value are written to
  an example file called DLXSROOT/bin/installer/config-examples/httpd.conf.dlxs.

  You may use that example configuration file to configure your Apache
  server environment. Or you may define DLXSROOT for your server using
  your own configuration.

  For your Unix shell, you should set the DLXSROOT environment variable
  to the path you choose so you can run various command line utilities
  which depend on it.

  For a RECONFIGURATION, you will be asked for the path you entered for
  the FIRST-TIME INSTALLATION directory.  The directory must be one
  containing a completed installation of DLXS Release 9.

  Is this an I)nitial install or a R)econfiguration? (I/R) [I]

  Where would you like to install DLXS? [//] /l1/dlxstest
    

This is where you specify DLXSROOT as explained above. Note the option to "re-configure". If you choose it, you will be prompted for the location of a completed installation. The installer will then make another pass over the installed middleware .cfg files allowing you to change values you entered during the initial installation or subsequent reconfigurations. You can do this as many times as necessary.

  Creating DLXSROOT...

  Unpacking tarball...
  Untarring all in /l/l1/INSTALL_CDROM into /l1/dlxstest...
  Untarring /l/l1/INSTALL_CDROM/Broker20_v1-1-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/ImageClass_v3-0-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/BibClass_v3-1-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/Collmgr_v3-1-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/TextClass_v3-2-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/FindaidClass_v5-0-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/Lib_v3-2-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/XClass_v2-1-0_rel11.tar.gz...
  Untarring /l/l1/INSTALL_CDROM/Dlxsdocs_v1-2-0_rel11.tar.gz...

  Making symlinks...
    

Symlinks to the installed binaries are saved in $DLXSROOT/bin/symlinks so the middleware can find them easily and we can avoid many inline replacements at install-time.

 
  Processing config-examples...
      Processing replacements in /l1/dlxstest/bin/installer/config-examples/crontab.dlxs
      Processing replacements in /l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs
      Processing replacements in /l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs
      Processing replacements in /l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs
    

Example files for the Apache server virtual host configuration and setting up cron jobs are automatically customized with your local settings and reside in $DLXSROOT/bin/installer/config-examples.

  Processing ImageClass index replacements...
          Processing replacements in /l1/dlxstest/idx/s/sampleic/image.blank.dd
          Processing replacements in /l1/dlxstest/idx/s/sampleic/image.dd
          Processing replacements in /l1/dlxstest/idx/s/sampleic/image.cfg
          Processing replacements in /l1/dlxstest/idx/s/sampleic/image.inp
          Processing replacements in /l1/dlxstest/idx/w/workshopic/image.blank.dd
          Processing replacements in /l1/dlxstest/idx/w/workshopic/image.dd
          Processing replacements in /l1/dlxstest/idx/w/workshopic/image.cfg
          Processing replacements in /l1/dlxstest/idx/w/workshopic/image.inp
          Processing replacements in /l1/dlxstest/idx/i/image-blank/image.blank.dd
          Processing replacements in /l1/dlxstest/idx/i/image-blank/image.cfg
          Processing replacements in /l1/dlxstest/idx/i/image-blank/image.inp
  
  Processing ImageClass perl hashbangs...
          Processing replacements in /l1/dlxstest/bin/i/image/convertBookBag.pl
          Processing replacements in /l1/dlxstest/bin/i/image/getFlds.pl
          Processing replacements in /l1/dlxstest/bin/i/image/getoneline.pl
          Processing replacements in /l1/dlxstest/bin/i/image/html2tab.pl
          Processing replacements in /l1/dlxstest/bin/i/image/icsgml2icmysql.pl
          Processing replacements in /l1/dlxstest/bin/i/image/idb
          Processing replacements in /l1/dlxstest/bin/i/image/imageprep
          Processing replacements in /l1/dlxstest/bin/i/image/imagetobib.pl
          Processing replacements in /l1/dlxstest/bin/i/image/makefieldbrowse.pl
          Processing replacements in /l1/dlxstest/bin/i/image/putFlds.pl
          Processing replacements in /l1/dlxstest/bin/i/image/tab2html.pl
  ImageClass thumb symlinking...
    

The preceding part of the script creates some needed directories and creates symlinks for image files.

Processing TextClass index replacements...
        Processing replacements in /l1/dlxstest/idx/s/sampletc/sampletc.dd

Processing TextClass WW sample index replacements...
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/makeWordWheelFiles.cfg
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/sampletc.ww.dd
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/sampletc.ww.inp
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/sampletc.ww.prepost.dd
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/sampletc.ww.presgml.dd

Processing TextClass sample WW XPAT path and DLXSROOT...
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/makeWordWheelFiles.cfg
        Processing replacements in /l1/dlxstest/idx/s/sampletc/WW/makeWordWheelFiles.cfg

Processing TextClass /l1/dlxstest/bin/WW replacements...
        Processing replacements in /l1/dlxstest/bin/WW/Makefile
        Processing replacements in /l1/dlxstest/bin/WW/sample.ww.blank.dd
        Processing replacements in /l1/dlxstest/bin/WW/sample.ww.inp
        Processing replacements in /l1/dlxstest/bin/WW/makeWordWheelFiles.sample.cfg
        Processing replacements in /l1/dlxstest/bin/WW/makeWordWheelFiles.sample.cfg
        Processing replacements in /l1/dlxstest/bin/WW/makeWordWheelFiles.pl
Processing BibClass index replacements...
        Processing replacements in /l1/dlxstest/idx/s/samplebc/samplebc.dd

Processing FindaidClass index replacements...
        Processing replacements in /l1/dlxstest/idx/s/samplefa/samplefa.dd

Processing FindaidClass Aids perl hashbangs...
        Processing replacements in /l1/dlxstest/bin/f/findaid/catsourcefiles.pl
        Processing replacements in /l1/dlxstest/bin/f/findaid/cleanfiles.pl
        Processing replacements in /l1/dlxstest/bin/f/findaid/inc.extra.dd.pl
        Processing replacements in /l1/dlxstest/bin/f/findaid/isolat128bit.pl
        Processing replacements in /l1/dlxstest/bin/f/findaid/output.dd.frag.pl
        Processing replacements in /l1/dlxstest/bin/f/findaid/validate.pl
        Processing replacements in /l1/dlxstest/bin/s/samplefa/validate.pl

Processing FindaidClass /l1/dlxstest... replacements...
        Processing replacements in /l1/dlxstest/bin/s/samplefa/Makefile

Processing miscellaneous bin utilities perl hashbangs...
        Processing replacements in /l1/dlxstest/bin/managesessions.pl
    

The preceding section on replacements details string replacements in files that have hard-coded paths to Perl and to $DLXSROOT.

Processing database utilities perl hashbangs...
        Processing replacements in /l1/dlxstest/bin/db/dbmove
        Processing replacements in /l1/dlxstest/bin/db/dbconv
        Processing replacements in /l1/dlxstest/bin/db/upgrade_1_2
        Processing replacements in /l1/dlxstest/bin/db/upgrade_2_3
        Processing replacements in /l1/dlxstest/bin/db/upgrade_3_4
Making /l1/dlxstest/web/cache for TextClass image cache
Opening permissions to u+w g+w o+w on /l1/dlxstest/web/cache
Opening permissions to u+w g+w o+w on CSV database tables in /l1/dlxstest/misc/db
        Processing replacements in /l1/dlxstest/bin/installer/README-postinstall
    

The preceding section on replacements details string replacements in files that have hard-coded paths to Perl and to $DLXSROOT. The cache (used to hold derived images and pdf files) is created and permissions on it are set.

Next the Middleware .cfg files Processing Begins ...

Configuring LibGlobals.cfg

no authentication URL available: using Basic Auth
    

By default, we assume you do not have a URL to an authentication system at your site that is able to set the REMOTE_USER environment variable. We deliver an HTTP "Basic Auth" configuration in the virtual host example file $DLXSROOT/bin/installer/config-examples/ httpd.conf.dlxs file.

Select the Collection database type. Choose MySQL if using MySQL for Image Class searching.   (CSV/MySQL) [MySQL] CSV
    

Though the default shown is MySQL, to run "out of the box," choose CSV to use the sample database tables and collections. If you choose CSV, and at some later time you wish to begin running under MySQL, run the dbmove utility to transfer the contents of the supplied CSV database into MySQL. If you have already set up MySQL and used the database conversion utility dbconv to populate it, choose MySQL.

Enter the virtual host of the idresolver cgi.
 [images.umdl.umich.edu]
    

At DLPS we have a CGI that maps image IDs to URLs so ImageClass can serve images maintained outside the usual ImageClass img directories. Here, if you choose to use the DLXS idresolver cgi, enter the virtual host under which it will run. Otherwise enter a blank.

  Enter your SMTP host [mail.umdl.umich.edu]

  Enter the email address from which the generated (e.g. BookBag) mail
      will be sent ["UMDL Mailer" <umdl-help@umich.edu>]

  Enter your Help email HTML href [mailto:umdl-help@umich.edu]

  Enter your Help email text string [umdl-help@umich.edu]
    

Your local email addresses that will appear in several of the HTML templates.

 Configuring DlpsSession.cfg

 Select the session datastore type (CSV/MySQL) [CSV] 

 Enter CSV session directory [/tmp/sessions] 

 Enter CSV session lock directory [/tmp/sessionslock] 
    

Sessions can be maintained in CSV files or in a MySQL database. If in CSV, enter the directory and lock directory where session files live (sessions and sessionslock. These directories must exist and be write permitted to the UID of the web server and should be created post-install.

  Configuring BookBag.cfg
    

The mail host to use when mailing BookBag contents.

  Enter the email address from which the BookBag mail will be sent 
   	["UMDL Mailer" <umdl-help@umich.edu>] 

  Configuring collmgr.cfg (Collection Database Manager)

  no logout URL: using Basic Auth
    

As explained above, the collmgr needs to have REMOTE_USER set by some mechanism. By default we supply HTTP "Basic Auth".

  Configuring dbconv.cfg

  Configuring dbmove.cfg

  Configuring textclass.cfg

  Configuring PageView.cfg

  Select the *Pageviewer* datastore type.

  If you don't have page images but want to try sample data, 
   	choose CSV (CSV/MySQL) [MySQL] 
    

A sample Pageview database table is supplied for the sampleic collection. For any significant application, CSV will not scale. If you just want to try the sampletc collection choose CSV. If you have a large scale collection of page images, choose MySQL.

  Configuring bibclass.cfg

  Configuring imageclass.cfg

Enter the image file server host name.
If it is the same as the host serving image-idx, enter '/',
otherwise enter e.g. imageserver.umdl.umich.edu   [/]

Enter 1 if all MySQL content indexes are built with MySQL version 4.0.2 or newer. If not sure, enter 0 (zero). [1] 0
    

Imageclass may be configured to use a different machine to serve image data (i.e., as opposed to the machine running the middleware). Certain content metadata searches cannot be performed with older versions of MySQL.

  not using a development host

  disabling Portfolios
    

The preceding status message indicated that ImageClass portfolio functionality is installed disabled by default.

  Configuring imageprep.cfg

  disabling icv1.06 backward compatability in imageprep
  Enter the path to mrsid_retrieve for imageprep [/l/local/bin/mrsid_retrieve]
    

For technical reasons related to how the Installer works the MrSID path needs to be supplied again here.

  Configuring broker20.cfg

Enter OAI Repository ID [lib.umich.edu]
Enter OAI repository name [The University of Michigan. University Library.  Digital Library Production Service.]
Enter the broker base URL  [http://www.hti.umich.edu/cgi/b/broker20/broker20]
Enter the broker email address [dlps-broker@umich.edu]
Enter a UTCdatetime that is the guaranteed lower limit of all datestamps recording changes, modifications, or deletions in the repository [2000-08-17]
Enter the manner in which the repository supports the notion of deleted records. Legitimate values are no, transient, or persistent [no]
Enter resolution of the datestamp at for your repository.  The legitimate values are YYYY-MM-DD and YYYY-MM-DDThh:mm:ssZ with meanings as defined in ISO8601. [YYYY-MM-DD]
Enter a sample OAI ID [oai:lib.umich.edu:YEATS-YC023]
    

broker20 is the CGI program that allows collections to be served using the OAI protocol.


  Done.

  Please refer to /l1/dlxstest/bin/installer/README-postinstall
  for post-installation directions.

  Would you like to view the post-installation directions now? [Y]

        ** NOTE: This installation was performed using version
        11 of the DLXS Installer **

       The middleware uses the DLXSROOT environment variable to locate
       its pieces in the install tree.  To run various command line
       utilities, make sure to set DLXSROOT environment variable for
       your Unix shell.

       For initial installations, if you chose MySQL for your
       database, you will want to use /l1/dlxstest/bin/db/dbmove to move
       the sample CSV database in /l1/dlxstest/misc/db into your MySQL
       database before you try to run the sample data.

       If your session database type is CSV, create the 'sessions' and
       'sessionslock' subdirectories in the locations you specified when
       configuring DlpsSession.cfg and permit them to the UID of the
       webserver.

       Database Upgrade:

       For the following, please refer to the instructions at
       http://docs.dlxs.org/collmeta/dlxs-collmetadata-index.xml
       or browse to
       /l1/dlxstest/web/d/dlxsdocs/collmeta/dlxs-collmetadata-index.xml.

       If your current database is version 3 from release 10:
       DLXS Release 11 uses a version 4 collection database.  Run
       /l1/dlxstest/bin/db/upgrade_3_4 to convert your database to
       version 4.

       If your current database is version 2 from release 9:
       Run /l1/dlxstest/bin/db/upgrade_2_3 to convert
       your database to version 3 followed by the above step.

       If your current database is version 1 from release 8:
       Run /l1/dlxstest/bin/db/upgrade_1_2 to convert your database to
       version 2 then follow the steps for subsequent releases above.

       /l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs defines
       Basic Authentication for an Apache server and thereby sets
       REMOTE_USER. If you disable this, IMPORTANT NOTE: the collection
       manager (collmgr) requires some form of authentication which
       sets the REMOTE_USER environment variable for proper operation!

       To use the Basic Authentication sample configuration you will
       need to edit
       /l1/dlxstest/bin/installer/config-examples/htpasswd.dlxs to supply
       the encrypted form of the password you choose for the 'dlxsadm'
       administrative user to run collmgr.  See documentation in
       htpasswd.dlxs for instructions.

       You may remove /tmp/main.cfg to restore the original default
       Installer answers.  It is a copy of
       /l1/dlxstest/bin/installer/main.cfg modified by the install
       program to remember the answers you provide and, if present, is
       favored over the original.

       Optionally, change permissions on
       /l1/dlxstest/web/cache to make it accessible only to
       the UID of the webserver.

       Optionally, change permissions on files in /l1/dlxstest/misc/db
       to make them accessible only to the UID of the webserver. In
       any event, be sure the web server can read and write these
       files, e.g. make sure they are 666, if their UID/GID is not
       that of the web server user and group.

       Set up cron jobs to run managesessions.pl and to clear the
       page image cache.

    

The installation is complete. Please follow the post install notes.