Installation Instructions

From DLXS Documentation

Revision as of 13:35, 9 August 2007

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

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 you can choose from 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,

The installer only installs the middleware, not the open source binaries or the XPAT binaries.

You can break the DLXS software installation into three parts:

• Pre-install Steps

Deciding where to install, extracting XPAT, binaries, and getting Perl modules.

• Running the Installation Script

Creates an initial working system that can function using the sample collection data.

• Post-install steps

Operations not handled by the Installer: change permissions of a few directories, configure Apache web server, install database sample data.

There are two main pieces of software that need to be installed: XPAT and other binaries and the middleware. You will need to install MySQL unless you plan to run a CSV database. We do not recommend the CSV database option and will deliver the sample database as a MySQL dump in release 13. Further, the database upgrade program will no longer offer the option of CSV.

• 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 <a href="../intro/dirstruct.html#dlxsrootenv">DLXSROOT environment variable</a>). 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

Installer will ask for a path to a directory that initially should not exist: /l1/workshop/text02/dlxs. Installer will create dlxs under /l1/workshop/text02/dlxs and populate it.

We refer to this path as DLXSROOT and the middleware accesses it via the DLXSROOT environment variable set by the web server. You should set DLXSROOT in your shell and Apache virtual host configuration. For more information on virtual host configuration, see the #Apache config sample files section. Set DLXSROOT in the shell when running some DLXS command line scripts or debugging the middleware at the command line.

Super-user privileges are not required; you only need user-write access to the directory containing DLXSROOT. Set your unmask to 022 so files/directories will be created 664/775.

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

NOTE: tif2web is a program used by the middleware (<a href="../class/text/pageviewer.html">Pageviewer</a>) to convert TIFF files to GIF and PNG formats. 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 the following command, replacing all items in curly braces (i.e., { }) with appropriate values:

Local CD, local destination

    cd {path-to-XPATinstall}
    tar xf {cdrom-mount-point}/{path-to-tarfile}/XPAT-{version}.tar 

You should include this directory in your shell PATH environment variable. This enables Installer to offer you their actual locations when it prompts.

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

Installing Other Binaries

There are several other binaries that you may need. Install these on your system as required for the DLXS classes you plan to use, 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. xpat, mrsid_retrieve, kdu_expand, cjpeg and tif2web are part of the DLXS distribution.

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

The installation steps for these binaries are identical to the XPAT installation steps.

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

• c42pdf is not part of the DLXS distribution. You can get it at http://c42pdf.ffii.org/. We are currently using version 0.12 for Linux.

Required Perl modules

We recommend you use the version of Perl specified in the System Requirements page.

In addition you will need to install additional Perl modules. You can find the list of these additional Perl modules in the System Requirements page. The Installer checks for the existence of these modules. You may install them after you install DLXS.

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.

MySQL configuration

For DLXS installations you will use MySQL as your data store. You should execute the following commands to create an empty database, user accounts, and access permissions required for use with DLXS middleware.

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;. Note that you should use the database name you chose when prompted for the name of the database during DLXS middleware installation rather than simply dlxs. We suggest you should choose a name that reflects the version number of the database delivered with the middleware release or perhaps the release number of the middleware.
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. You can find a detailed discussion of installing multiple releases in Multiple 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 <a href="../intro/dirstruct.html#dlxsrootenv">DLXSROOT environment variable</a>:

• 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.

Running the Installation Script

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.

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.

As the Installer runs, it prompts you to answer a number of questions. Installer.pl doesnot hardcode a Perl path, so be dure to run it as an argument to the Perl command line. For example:

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

The Installer runs through the following steps:

1. create needed subdirectories under $DLXSROOT
2. checks Perl dependencies
3. records the installation locationsof the requires and optional binaries as symlinks
4. extracts and installs the middleware, including sample collection templates and data
5. modifies configuration files using your choices for:
   1. database server name,collectioon database name, database username and password
   2. email addresses
   3. various global variables to configure the class DLXS middleware
6. replaces Perl "hash bang" strings (e.g. /l/local/bin/perl) in utility programs (mainly in $DLXSROOT/bin/*) with local Perl path.
7. substitutes local value of DLXSROOT environment variable in sample data dictionary (.dd).
8. generates localized example files. The sysadmin may add their content to several non-DLXS configuration files. For example:
   1. Apache host directives
   2. Unix cron job commands to manage session expiration and cache size

Step-by-Step Installation Instructions

Click here for a step-by-step walk-through via the screen printout of 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 by the installation script outline (for example, insert configuration snippets into the Apache server conf file, create and make "nobody" the owner of the DLXSROOT/web/cache directory, install sample database data, 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. This includes the possibility that you are running a CSV database for DLXS.

• 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

After these post-installation steps are complete you can test you installation by visiting the URLs below in your browser. Substitute your actual virtual host for the string "YOURVIRTUALHOST" below.

Change cache directory permissions

The Installer creates $DLXSROOT/web/cache 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.

Coonfigure 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-example/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. 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 hostnameof 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 an example Apache virtual host configuration. <p>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 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 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, see the Apache Web Site. ===Database conversion and migration following installation</h2> <p>If you have a DLXS installation that is Release 9 or later, you will need to run the upgrade_N_N+1 utilities (one or more) that are delivered with the DLXS software. This should be done following a successful installation. These will migrate your data from one version of the database to another. For example, if you are currently running Release 12 of the software, which uses version 5 of the database, and are installing Release 13, which uses database version 6, you should run upgrade_5_6 to move your current data into the new format. See the <a href="../collmeta/upgrade.html">upgrade documentation</a> for more information

For first-time installations, your database will be MySQL. You will have created an empty database as described <a href="#mysqlconfig">above</a>. The next step is to install the sample database data contained in $DLXSROOT/misc/db/db-dump-v6.0-release.sql as follows. Let dlxs_v6 be the database name you chose for this installtion. Load the dump via the mysql command line client like this:

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, <a href="../intro/cronjobs.html">crontab</a>.

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 $DLXSROOT/web/cache: this directory too will need to be owned by the runner of the web server processes, again, often "nobody".

• 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.

If you are running the web server on one machine and the data resides on another you will have to <a href="../intro/daemoninstall.html">install the daemons</a> 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 <a href="../collmeta/collmgr.html#remoteuserenv">REMOTE_USER</a>. Also see <a href="../auth/index.html">DLXS Authentication and Authorization</a> for more information.