DLXS Installation

Note: additional installation information is available in these companion documents:

• Introduction
  • The install process
• Pre-install steps
  • Decide where to install
  • Extracting/Installing XPAT
  • Other Binaries
  • Get Required Perl Modules
• Install steps
• Post-install steps
  • Create session directories (Optional)
  • Change directory and file permissions
  • Configure crontab
  • Apache config sample files
  • Database Installation and Upgrading

Introduction

The goal of the install process is to create an initial working system that can function using the sample collection data.

On the open source CD you'll find:

• gzipped tarfiles for middleware and open source binaries
• Installer.pl
• an installation configuration file: main.cfg.

XPAT is on the second CD.

There are several methods to do the open source install:

• Run the installation directly from the mounted CD.
• Copy the files from the CD to a directory and install from there.
• Download the .iso image from www.dlxs.org. Mount it and install from the mount point.

Installer only installs the middleware not the open source binaries or XPAT binaries

The install process

1. Pre-install. Preparation for middleware installation.
2. Running Installer
3. Post-install steps. Operations not handled by Installer

Pre-install steps

Decide where to install

Installer will ask for a path to a directory which initially should not exist, e.g. /l1/workshop/text02/dlxs. Installer will create dlxs under /l1/workshop/text02 and populate it.

This path will be referred to as DLXSROOT and is accessed by the middleware via the DLXSROOT environment variable set by the web server. You should set DLXSROOT in your shell and Apache DLXS virtual host configuration. Virtual host configuration info follows below. Set DLXSROOT in the shell when running some DLXS command line scripts or the debugging the middleware at the command line.

Super-user privileges are not required. Only user write access to the directory containing DLXSROOT. Set your umask to 022 so files/directories will be created 664/775.

Extracting/Installing XPAT

Untar the XPAT tarfile where you would like to store the XPAT executables. For example, /usr/local/

This directory should be included in your shell PATH environment variable. This enables Installer to offer you their actual locations when it prompts. We'll illustrate the case where the CD and destination are local to one machine. We'll assume /usr/local, xpat-5.3.2, Linux and a cdrom mount point of /cdrom:

    % cd /l/local
            % tar xvf /cdrom/xpat_linux-5.3.2.tar
        

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 /l/local
            % 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 /l/local
            % ln -s xpat-5.3.2 /l/local/xpat

Other Binaries

There are several other binaries which you may need. Install these on your system as required for the Classes you plan to use.

• c42pdf (required for TextClass page viewer)
• tif2web (required for TextClass page viewer)
• mrsid_retrieve (required if you use ImageClass .sid files)
• cjpeg (required if you use ImageClass .jp2 files)
• kdu_compress, kdu_expand (required if you use ImageClass .jp2 files)
• dlxsd (required if you access data remotely)
• utf8conditioner (required if you use OAITransform)
• xpatutf8check (optional utf-8 validity checking program)

Installation steps for these binaries are identical to those for XPAT.

c42pdf is not part of the DLXS distribution. Get it from http://c42pdf.ffii.org/ -- we are currently using version 0.12 for Linux.

Get Required Perl modules

We currently recommend you use the standard Perl 5.8.8 (or higher) release.

In addition, you'll need to install additional Perl modules. Get them from CPAN.

Installer checks existence and version for each of these. Installer will list those not found and those with a version less than the recommended version.

It's OK to install the additional Perl modules after installing the DLXS middleware.

Install steps

Install problems? If, for any reason, the install is unsuccessful you can repeat the process. Simply delete the DLXSROOT directory (if it has been created) and run Installer again.

Using the example paths from the workshop:

  cd /l1/INSTALL_CDROT/cd
  perl ./Installer.pl

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

There are several functions performed by Installer:

• create $DLXSROOT
• check Perl dependencies
• record installation locations of required and optional binaries as symlinks
• extract and install middleware, including sample collection templates and data
• modify configuration files using your choices for:
  • database server name, collection database name, database username and password
  • email addresses
  • various global variables to configure the class DLXS middleware
• replace Perl "hash bang" strings (e.g. /l/local/bin/perl) in utility programs (mainly in $DLXSROOT/bin/*) with local Perl path.
• replace XPAT path strings (e.g. /l/local/bin/xpatu) in certain programs with local XPAT path.
• substitute local value of DLXSROOT environment variable in sample data dictionary (.dd) files.
• generate localized example files. The sysadmin may add their content to several non-DLXS configuration files. For example:
  • Apache virtual host directives
  • Unix cron job commands to manage session expiration and cache size
Installer.pl

Post-install steps

Change cache directory permissions

The Installer creates $DLXSROOT/web/cache 777 permissions. Optionally, you may want to change permissions on this directory to make it writeable only by the UID of the web server.

Configure crontab

The $DLXSROOT/bin/managesessions.pl, $DLXSROOT/bin/manageportfolios.pl and $DLXSROOT/bin/managecache.sh scripts are typically run by a cron job to periodically expire user sessions, remove temporary ImageClass portfolios and maintain $DLXSROOT/web/cache at the desired size. An example crontab can be found in $DLXSROOT/bin/installer/config-examples/crontab.dlxs.

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. The example 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"?>

Here is the Apache virtual host configuration for one of the workshop users.

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 Authentication section in httpd.conf.dlxs for the collmgr. If you disable this be aware that the collmgr requires some form of authentication which 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 Authentication" sample configuration.

The file $DLXSROOT/bin/installer/config-examples/htpasswd.dlxs codes the administrative user ID dlxsadm for the collmgr with the password collmgr. 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: place htpasswd.dlxs in the conf subdirectory of you Apache installation.

Database installation and upgrading

Covered in this workshop page (next)..