DLXS Installation

Installation methods

On the CD-ROM you will find a number of tarfiles, a Perl program called Installer.pl and a configuration file called main.cfg.

There are two methods to do the install:

If you do a selective install you must install at least one Class, Collmgr and Lib tarfiles to have a working system.

The install process

There are 3 parts to installing DLXS. The install step (among other things) sets the values of a number of Perl variables found in the following.cfg files. These variables may be changed manually at a later time. The goal of the install is to create an initial working system that can function using the sample collection data. There are a number of other Perl variables in the .cfg files which affect functionality but are not critical to establish a working system which you can change at a later time.

.cfg files affected by Install

Pre-install steps

Decide where to install.

The Installer will ask for a path to a directory which initially should not exist, e.g. /usr/local/dlxstest. The installer will create 'dlxs' under /usr/local and populate it. This path will be referred to as DLXSROOT and is accessed by the middleware as an environment variable. You should set DLXSROOT in your unix shell and for the Apache web server. Web server configuration info below. Setting DLXS in the shell is necessary when running some DLXS command line scripts.

We recommend you install as a normal user with a umask of 022 which creates files permitted as 664 or 775.

Extracting/Installing XPat / tif2web

We are still finalizing the packaging of tif2web which will give more control over the resulting images and support PNG in affition to GIF. It will replace tif2gif. For the workshop we are using tif2gif. The installation of tif2web will follow closely the steps for installing XPat.

Uncompress and untar the XPat tarfile where you would like to store the XPat executables. For example, at many sites, this is /usr/local/. You would typically use one of the following commands/methods, replacing all items in curly braces (i.e., { }) with appropriate values:

Local CD, local destination

    cd {path-to-xpatinstall}

    zcat {cdrom-mount-point}/{path-to-tarfile}/xpat-{version}.tar.gz | 
tar xf -Local CD, remote destination zcat {cdrom-mount-point}/xpat-{version}.tar.gz |
rsh {HOSTNAME} "cd {path-to-xpatinstall}; tar xBf -"

Remote CD, local destination

    cd {path-to-xpatinstall}

    rsh {HOSTNAME} "zcat {cdrom-mount-point}/xpat-{version}.tar.gz" | tar xBf -

Unlink any previous symlink from a version-specific directory of XPAT to an xpat directory (i.e., one without a specific version name. For example:

    cd {path-to-xpatinstall}

    rm xpat

Create a symlink from the new version-specific directory of XPAT to an xpat directory (i.e., without version name). For example:

    cd {path-to-xpatinstall}

    ln -s xpat-{version} {path-to-xpatinstall}/xpat

Other Binaries

There are 3 other binaries which you may need.

In addition you'll need standard unix utilities installed and present in $PATH: make, mkdir, ln, cat, chmod.

XPAT and tif2web are (or will be) part of the DLXS distribution. Obtain the others as follows:

Install these on your system as required for the Classes you plan to install and include them in $PATH. Adding them to $PATH is not required but if you add them, the installer will be able to offer you their actual locations when it prompts.

Required Perl modules

We currently recommend you use the standard Perl 5.6.1 release. In addition you'll need to install these additional modules which can be obtained from CPAN. These modules are checked for existence as a sanity check but many are part of the standard distribution. The Installer will list those not found when it runs. Only those not in the standard distribution need to be fetched from CPAN. NOTE: Socket and Net ::hostent are used directly by the Install script and must be available in order to run the Install program. With these 2 exceptions you may run the Installer without obtaining the additional modules so long as you fetch and install them before running the DLXS middleware.

Install steps

Install problems. 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 the Installer again.

Regardless of whether you install directly form the CD or from a directory:

% cd {tarfile-dir}

% perl Installer.pl

The install program will run and prompt you to answer a number of questions. 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 the Install program. 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].


Welcome to DLXS Installer.  Press 'q' at any time to quit

                Compatible with DLXS CD-ROM No. 8.


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

This is a check to make sure the platform is supported.

Where is Perl installed? [/l/local/bin/perl]

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

Checking for Perl installation for required modules...


All Perl required modules are present

        NOTE: If you choose to use the MySQL database and/or session option(s)

        you'll also need to install DBD::mysql.pm

All required Perl modules were found. If some were missing the Installer would have asked whether to continue. It's ok to continue and install the missing modules after the install but we recommend installing them beforehand.

The next series of questions concerns where certain

required binaries are installed in your system.


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


Do you want to use tif2gif (required for TextClass page viewer)? [Y] 

        Where is tif2gif installed? [/l/local/bin/tif2gif] 


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] 

Enter full paths to the binaries you chose to install based on which middleware classes you chose to install as directed. tif2gif will become tif2web in the next release.


                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

/do/not/use, the installer will


        (1) create an install directory named /do/not/use

        (2) mark it with a timestamp

        (3) extract the tarfiles into that directory.


This install directory is also inserted as a string into a number 
of working and configuration example files.   The middleware uses the DLXSROOT environment variable to locate
its pieces in the install tree. The DLXSROOT environment variable
should be set to /do/not/use for your Unix shell.   For the web server, this variable and 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 a RECONFIGURATION, you will be asked for the install directory. The directory must be one containing a completed installation
of CD-ROM No. 8.   Is this an I)nitial install or a R)econfiguration? (I/R) [I] Where would you like to install DLXS? [/do/not/use] /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 repeatedly.

Creating DLXSROOT...


Unpacking tarball...

Untarring all in /l1/INSTALL_CDROM into /l1/dlxstest...

Untarring /l1/INSTALL_CDROM/CDROM_8_lib.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_collmgr.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_text.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_bib.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_findaid.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_image.tar.gz...

Untarring /l1/INSTALL_CDROM/CDROM_8_broker.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

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/Makefile

   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/Makefile

   Processing replacements in /l1/dlxstest/idx/w/workshopic/image.inp


Processing ImageClass Perl hashbangs...


   Processing replacements in 
/l1/dlxstest/bin/i/image/clean.newlines.inplace.pl Processing replacements in /l1/dlxstest/bin/i/image/getoneline.pl Processing replacements in /l1/dlxstest/bin/i/image/htmltotab.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/makefieldbrowse.pl Processing replacements in /l1/dlxstest/bin/i/image/tabtohtml.pl   Processing TextClass index replacements... Processing replacements in /l1/dlxstest/idx/s/sampletc/sampletc.dd   Processing BibClass index replacements... Processing replacements in /l1/dlxstest/idx/s/samplebc/samplebc.dd

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

Making /l1/dlxstest/web/t/text/gifcvtdir for TextClass image cache

If you chose to install TextClass the image cache directory is created. It's permissions may to be changed post-install. See below.

Opening permissions to u+w g+w o+w on CSV database tables 
in /l1/dlxstest/misc/db Processing replacements in

The CSV database tables need world write permission since we are installing as a normal user and the web server needs to read and write them.


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 (CSV/MySQL) [MySQL] CSV

To run "out of the box" choose CSV to use the sample database tables and collections. If you have already set up MySQL and used the database conversion utility dbconv to populate it, choose MySQL. Database conversion is discussed in the DLXS online documentation.

development MySQL server same as production

This status message simply says that you have a single machine that serves as your production and development MySQL server. Configuring the middleware for a separate development and production environments is not addressed here.

Enter your Help email HTML href  

Enter your Help email text string [

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] 

development session host same as production host

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

Configuring BookBag.cfg


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

The mail host to use when mailing BookBag contents.

Enter the email address from which the BookBag mail will be sent 
["UMDL Mailer" <>]   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


not using a development host

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. http://imageserver.umdl.umich.edu/   [/] 

not using a development host

Imageclass may be configured to use a different machine to serve image data than the machine running the middleware.

disabling Portfolios

This status message indicated that ImageClass portfolio functionality is installed disabled by default. Setting up portfolios is discussed in the ImageClass documentation.

no ID resolver present

At DLPS we have a CGI which maps image IDs to URLs so ImageClass can serve images maintained outside the usual ImageClass img directories.

Configuring imageprep.cfg


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 broker.cfg

broker is the CGI program that responds to URLs that implement the OAI protocol.

Configuring the Identify Verb for broker


Enter OAI Repository ID [dlpscoll] 

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/broker/broker] Enter the broker email address [dlps-broker@umich.edu] Enter a sample OAI ID [oai:dlpscoll:YEATS-YC023]

Now follow the post install notes treated more fully in the next section.

Post-install steps

Create session directories (Required for CSV sessions)

If your session database type is CSV, create the session and session lock subdirectories in the locations you specified when configuring DlpsSession.cfg and change the permissions on them to give write access for the UID of the web server.

Change directory and file permissions

The DLXSROOT/web/t/text/gifcvtdir is created by the Install program with 777 permissions. Optionally, you may want to change permissions on this directory to make it writeable only to the UID of the web server.

The files (sample database tables) in DLXSROOT/misc/db are installed with 666 permissions. Optionally, you may want to change permissions on these files to make them accessible only to the UID of the web server.

Apache config sample files

Examine DLXSROOT/bin/installer/config-examples/httpd.conf.dlxs. You may integrate this segment into your Apache configuration file, adapting as necessary. It assumes you want to run your DLXS installation on a virtual host called dlxs.<?dlxs-install var="hostname"?> (where the part between the braces will be replaced with the hostname of the machine you installed on) and that you have created the proper DNS record, typically dlxs.<?dlxs-install var="hostname"?> IN CNAME <?dlxs-install var="hostname"?>

If you would like to run your DLXS installation on a different virtual host, please consult your Apache documentation.

You can comment-out the basic auth section in httpd.conf.dlxs basic authentication for the collmgr. If you disable this be aware that the collmgr requires some form of authentication which sets the REMOTE_USER variable for proper operation. So, to run "out of the box", the easiest thing to do is to use the "Basic Auth" sample configuration.

The file DLXSROOT/bin/installer/config-examples/htpasswd.dlxs codes the administrative password dlxsadm for the collmgr with the password collmgr. You will probably also want to change the password to a different value using the Apache program:

% htpasswd passwordfile username

where passwordfile is APACHE/conf/htpasswd.dlxs and username is dlxsadm. Note htpasswd.dlxs will then need to be place in the "conf" subdirectory of you Apache installation.

Rebuild ImageClass indexes

If you installed ImageClass the sample indexes need to be rebuilt.

  1. rebuild xpat indexes
    • cd DLXSROOT/idx/w/workshopic
    • make all
    • cd DLXSROOT/idx/s/sampleic
    • make all
  2. run imageprep
    • cd DLXSROOT/bin/i/image
    • ./imageprep workshopic
    • ./imageprep sampleic

Database conversion

If you have a DLXS installation that predates CD-ROM #8 a conversion utility , new in version 8, called dbconv in DLXSROOT/bin/db can be used to capture the data in your existing colldb files and merged into the CSV tables located in DlXSROOT/misc/db See documentation on database functionality for complete instructions.