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
The installation of DLXS software can be broken into three parts:
There are two main pieces of software that need to be installed: XPAT and other binaries and the middleware.
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
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.
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.
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.
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.
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.
Click here to see step-by-step instructions on running the installation program.
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 DLXSROOT/web/cache directory 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 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).
The $DLXSROOT/web/cache 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.
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
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.
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.
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.
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.