Contents

• Overview of the DLXS Installation Process
• Pre-install Steps
• MySQL configuration
• Installation Script: Outline
• Step-by-step instructions for installation
• First Time Installation vs Update
• Post-install Steps

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.

• XPAT, and a few related binary files, are to be installed by a sysadmin (or someone with root access to the machine). The sysadmin will decide where the XPAT binaries should go and install them there.
• The Middleware files will be installed under one directory (whose name should be set up as the DLXSROOT environment variable). The installation script does not require root access, just write access to the $DLXSROOT directory which it will create during the installation process.

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.

• c42pdf (required for TextClass pageviewer)
• tif2web (required for TextClass pageviewer)
• mrsid_retrieve (required for ImageClass)
• kdu_expand (required for ImageClass)
• cjpeg (required for ImageClass)

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:

• c42pdf at http://c42pdf.ffii.org/. We are currently using version 0.12.

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:

• in your unix shell (setting DLXSROOT in the shell is necessary when running some DLXS command line scripts)
• in the Apache web server (web server configuration info below).

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:

• if the middleware requires database format changes, instructions will be given to run the programs required to convert the collection database.
  • If moving from any previous version to that found on CDROM #8, click here for instructions on running dbconv. This will convert the data from the previous tab delimited flat file to a database (to be used by the middleware through Perl's DBI mechanism) in either a CSV or MySQL form.
  • Note: if you want to move from one database format to another (e.g., CSV to MySQL, CSV to Oracle, MySQL to Oracle, etc.), click here for instructions on running dbmove.
• If Image Class Portfolios have been in use, the MySQL tables used to store users' Portfolio data must be upgraded by running $DLXSROOT/bin/i/image/convertBookBag.pl. It is important to read the instructions at the head of the script. Note that the Portfolio functionality will work (in DLXS 11, but not 11a) even if you do not do this upgrade. This does not indicate that the upgrade is not necessary. This upgrade step only ever needs to be done once. So, if it was done when upgrading to DLXS 11, it is not necessary to do it again when upgrading to DLXS 11a or later.
• Although changes to the middleware are made to be backward-compatible, you should check any program files you have changed to see whether they will work with the new version. A simple UNIX diff can be helpful. A version control system (at DLPS, we use CVS) can help with comparing and merging code.

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:

• Permissions on session related directory: the directory identified during the installation as that which holds the session files needs to be owned by the same user that runs the web server processes. This is usually "nobody". So, if the directory was /tmp/sessions, the Sysadmin, as root, will need to run chown nobody /tmp
• Permissions on $DLXSROOT/t/text/gifcvtdir: this directory too will need to be owned by the runner of the web server processes, again, often "nobody".

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.