Last updated 2003-08-07 14:01:12 EDT
Doc Title DLXS Installation
Author 1 Farber, Phillip
Author 2 Pagliere, Alan
CVS Revision $Revision: 1.7 $
DLXS Installation


This document explains how to install the DLXS middleware and XPAT software. After reading and following instructions here, there may be class specific installation issues, in which case there will be a link to those specific instructions

Overview of the DLXS Installation Process

The installation of DLXS software can be broken into three parts:

Pre-install steps
Deciding where to install, extracting XPAT, binaries, and getting Perl modules.
Running the Installation Script
Create an initial working system that can function using the sample collection data.
Post-install steps
Change permissions of a few directories, create session directories, configure Apache web server.

There are two main pieces of software that need to be installed: XPAT and other binaries and the middleware.

Pre-install Steps

Extracting/Installing XPAT / tif2web / mrsid_retrieve / kdu_expand / cjpeg

NOTE: tif2web is a program used by the middleware (Pageviewer) to convert TIFF files to GIF and PNG formats. It replaces the previously used tif2gif. The installation of tif2web will closely follow the steps for installing XPAT.

NOTE: mrsid_retrieve is a program used by the ImageClass middleware to decompress MrSID files generating JPEG output for delivery to browsers. As with tif2web, the installation of mrsid_retrieve will closely follow the steps for installing XPAT.

NOTE: kdu_expand is a program used by the ImageClass middleware to decompress jpeg2000 files generating JPEG output for delivery to browsers. As with tif2web, the installation of kdu_expand will closely follow the steps for installing XPAT.

NOTE: cjpeg used in conjunction with kdu_expand for JPEG2000 web delivery. As with tif2web, the installation of kdu_expand will closely follow 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 three (3) other binaries that you may need.

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

xpat, mrsid_retrieve, kdu_expand, cjpeg and tif2web are part of the DLXS distribution as of Release 11. Obtain:

Install these on your system as required for the Classes you plan to install (note the list above for which binaries are required for which classes) 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 recommend you use the version of Perl mentioned in our Systems Requirements page.

In addition you will need to install additional Perl modules. The list of these additional Perl modules can be found in our Systems Requirements page. These modules are checked for existence by the Installer, but to simplify DLXS installation, ensure the required modules are installed before beginning.

During DLXS middleware installation, you may see Installer complain about an already installed Perl module due to dependencies it has on other not yet installed Perl modules. These will go away when all reported Perl modules are installed in your Perl distribution.

NOTE: Socket and Net::hostent are used directly by the install script and must be available in order to run the Installer.

MySQL configuration

For initial DLXS installations, if you plan to use MySQL as your data store, you should execute the following commands to create the database, user accounts, and access permissions required for use with DLXS middleware. If you choose the CSV database option initially you can skip this step. Later you can reconfigure the middleware to use MySQL if need be.

  1. Start the SQL monitor with the command mysql -u root -p mysql (you will be prompted for the MySQL system password).
  2. Create the DLXS database with the command create database dlxs;.
  3. Create the dlxsadm (administrative) account and grant full privileges to it with the command grant all privileges on dlxs.* to dlxsadm identified by 'password';, where password is the password to be used for DLXS database administration.
  4. Grant FILE privilege to the dlxsadm account with the command grant file on *.* to dlxsadm;.
  5. Create the dlxs account and grant basic privileges to it with the command grant select,insert,update,delete,references on dlxs.* to dlxs identified by 'password';, where password is the password to be used for general DLXS database usage (such as from within the DLXS middleware).
  6. Activate the changes with the command flush privileges;.
  7. Exit the SQL monitor with the command quit.

Decide where to install DLXS Middleware

You may want to give some consideration to how you will manage the installation of a subsequent DLXS release. The main consideration is where you want a later release to reside in your file system, i.e. what its DLXSROOT should be. A detailed discussion of installing multiple releases can be found in Multiple DLXS Releases

The Installer will ask for a path to a directory that initially should not yet exist, e.g. /usr/local/dlxs. 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 the DLXSROOT environment variable:

We recommend you install as a normal user with a umask of 002, which creates files that are group-writable.

Installation Script: Outline

A general outline of the interactive installation script follows. This installation script will first confirm the location of various resources, install the middleware and some sample data, and then configure the middleware.

  1. create needed subdirectories under $DLXSROOT
  2. check dependencies
    1. Perl
    2. installation locations of required and optional binaries
  3. install middleware
  4. install sample HTML and HTML template files
  5. install sample data
  6. modify configuration files, including:
    1. the database store (e.g., mySQL, CSV, Oracle, etc.) for the collection and group related data
    2. a number of global variables used in the main Perl scripts that make up the DLXS middleware
  7. replace Perl "hash bang" strings in certain utility programs with local Perl path.
  8. substitute local value of DLXSROOT environment variable in sample data indexes.
  9. run processing scripts on installed sample data.
  10. generate snippets of text that should be added, by the Sysadmin, to several non-DLXS configuration files, e.g.,
    1. Apache virtual host directives
    2. Unix cron job commands to manage session expiration

Step-by-Step Installation Instructions

Click here to see step-by-step instructions on running the installation program.

First Time Installation vs. Update

If this is a first time installation of the DLXS middleware at your site, little will be required beyond following the installation script and having your Sysadmin do the tasks requested bythe installation script outline (for example, insert configuration snippets into the Apache server conf file, create and make "nobody" the owner of the gifcvtdir and session tracking directories, etc.).

However, if this is not your first time installing DLXS middleware, some or all of the following additional steps may be necesary:

Post-Installation Steps

Create session directories (Required for CSV sessions)

If your session database type is CSV, create the sessions and sessionslock 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 (usually nobody or apache).

Change directory and file permissions

The $DLXSROOT/web/t/text/gifcvtdir is created by the Install program with 777 permissions. Alternatively, 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. Alternatively, 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.

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

You may comment out the section in httpd.conf.dlxs which implements basic authentication for the collmgr. If you disable this be aware that the collmgr requires some form of authentication that sets the REMOTE_USER environment variable for proper operation. So, to run "out of the box," the easiest thing to do is to use the "Basic Auth" sample configuration. See DLXS Authentication and Authorization for more information.

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 placed in the conf subdirectory of your Apache installation. For more information, seethe Apache Web Site

Database conversion and migration

If you have a DLXS installation that predates Release #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 merge the data into the CSV tables located in DlXSROOT/misc/db. See documentation on database functionality and database migration for complete instructions.

If you have a DLXS installation that is Release #9 or later, you will need to run the upgrade utilities (one or more) that are delivered with the DLXS software. These will migrate your data from one version of the database to another. For example, if you are currently running Release #8 of the software, which uses version 1 of the database, and are installing Release #9, which uses database version 2, you should run upgrade_1_2 to move your current data into the new format. As future versions of the DLXS software are delivered, when there are changes in the database format which require updates, we will deliver appropriate (and appropriately named) upgrade programs to make that change possible. See upgrade for more information

For initial installations, if you chose to use MySQL for your database, you will then want to use dbmove to move the sample CSV database into your MySQL database before you try to run the sample data.

Configuration Example Files

The configuration example files generated by the installation script will be found in the $DLXSROOT/bin/installer/config-examples directory. The Sysadmin should be notified of these and s/he should use them to make the changes necessary, e.g., the web server configuration file, crontab.

Sysadmin tasks

The $DLXSROOT/bin/installer/config-examples directory will also contain a file called README-postinstall that will contain a set of instructions that someone with sysadmin rights will need to follow. These include setting specific permissions on special directories:

If you are running the web server on one machine and the data resides on another you will have to install the daemons that allow for the two hosts to communicate. This requires root access.

Collection Manager Authorization

The DLXS collection manager requires user authentication (i.e., access by username and password) to be able to check in, check out, and release changes. If you do not wish to use these functions, then at a bare minimum, it requires access by username and password as the administrator user, dlxsadm.

For your convenience, DLXS is installed with this minimum configuration using standard HTTP Basic Authentication. When you access the collection manager, you will be prompted for a username and password; enter "dlxsadm" with the password "collmgr", and you will be given access.

DLXS recommends that you change the default password after installation with the following command, which will prompt you for a new password:

<apache>/bin/htpasswd <apache>/conf/htpasswd.dlxs dlxsadm

where <apache> is the directory in which Apache is installed on your system.

You may permit other users to the collection manager, collmgr, using this mechanism; see your Apache documentation for more information on configuring Basic Authentication. You may also replace the authentication method entirely, so long as it provides the name of the authenticated user in the environment variable REMOTE_USER. Also see DLXS Authentication and Authorization for more information.