On the CD-ROM you will find a number of tarfiles, a Perl program called Installer.pl and a configuration file called main.cfg.
There are two methods to do the install:
If you do a selective install you must install at least one Class, Collmgr and Lib tarfiles to have a working system.
There are 3 parts to installing DLXS. The install step (among other things) sets the values of a number of Perl variables found in the following.cfg files. These variables may be changed manually at a later time. The goal of the install is to create an initial working system that can function using the sample collection data. There are a number of other Perl variables in the .cfg files which affect functionality but are not critical to establish a working system which you can change at a later time.
The Installer will ask for a path to a directory which initially should not exist, e.g. /usr/local/dlxstest. 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 DLXSROOT in your unix shell and for the Apache web server. Web server configuration info below. Setting DLXS in the shell is necessary when running some DLXS command line scripts.
We recommend you install as a normal user with a umask of 022 which creates files permitted as 664 or 775.
We are still finalizing the packaging of tif2web which will give more control over the resulting images and support PNG in affition to GIF. It will replace tif2gif. For the workshop we are using tif2gif. The installation of tif2web will follow closely 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 xpatCreate 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 3 other binaries which you may need.
In addition you'll need standard unix utilities installed and present in $PATH: make, mkdir, ln, cat, chmod.
XPAT and tif2web are (or will be) part of the DLXS distribution. Obtain the others as follows:
Install these on your system as required for the Classes you plan to install 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 currently recommend you use the standard Perl 5.6.1 release. In addition you'll need to install these additional modules which can be obtained from CPAN. These modules are checked for existence as a sanity check but many are part of the standard distribution. The Installer will list those not found when it runs. Only those not in the standard distribution need to be fetched from CPAN. NOTE: Socket and Net ::hostent are used directly by the Install script and must be available in order to run the Install program. With these 2 exceptions you may run the Installer without obtaining the additional modules so long as you fetch and install them before running the DLXS middleware.
Install problems. If for any reason the install is unsuccessful you may repeat the process. Simply delete the DLXSROOT directory (if it has been created) and run the Installer again.
Regardless of whether you install directly form the CD or from a directory:
% cd {tarfile-dir}
% perl Installer.pl
The install program will run and prompt you to answer a number of questions. Installer.pl does not hard-code a Perl hash bang so be sure to run it as an argument to the Perl command line as shown above.
What follows is an annotated version of the screen dialogue from an actual run of the Install program. Because this installation was performed on a machine having all the necessary binaries and Perl modules supplied most of the answers can be supplied by just hitting [RETURN].
Welcome to DLXS Installer. Press 'q' at any time to quit Compatible with DLXS CD-ROM No. 8. Which platform are you using? (SunOS/Linux) [SunOS]This is a check to make sure the platform is supported.
Where is Perl installed? [/l/local/bin/perl]Enter the full path to perl. The default is from the 'which' command..
Checking for Perl installation for required modules... All Perl required modules are present NOTE: If you choose to use the MySQL database and/or session option(s) you'll also need to install DBD::mysql.pmAll required Perl modules were found. If some were missing the Installer would have asked whether to continue. It's ok to continue and install the missing modules after the install but we recommend installing them beforehand.
The next series of questions concerns where certain required binaries are installed in your system. Where is XPAT installed? [/l/local/bin/xpat] Do you want to use tif2gif (required for TextClass page viewer)? [Y] Where is tif2gif installed? [/l/local/bin/tif2gif] Do you want to use c42pdf (required for TextClass page viewer)? [Y] Where is c42pdf installed? [/l/local/bin/c42pdf] Do you want to use MrSid (required for ImageClass)? [Y] Where is mrsid_retrieve installed? [/l/local/bin/mrsid_retrieve]Enter full paths to the binaries you chose to install based on which middleware classes you chose to install as directed. tif2gif will become tif2web in the next release.
********************************** I m p o r t a n t ! ********************************** The next question allows you to pick between performing a first-time installation or reconfiguring an existing installation. For a FIRST-TIME INSTALLATION you will be asked where to install DLXS. You should supply a full path. For example, if you choose /do/not/use, the installer will (1) create an install directory named /do/not/use (2) mark it with a timestamp (3) extract the tarfiles into that directory. This install directory is also inserted as a string into a number
of working and configuration example files. The middleware uses the DLXSROOT environment variable to locate
its pieces in the install tree. The DLXSROOT environment variable
should be set to /do/not/use for your Unix shell. For the web server, this variable and value are written to an
example file called DLXSROOT/bin/installer/config-examples/httpd.conf.dlxs. You may use that example configuration file to configure your
Apache server environment. Or you may define DLXSROOT for your server using your own configuration. For a RECONFIGURATION, you will be asked for the install directory. The directory must be one containing a completed installation
of CD-ROM No. 8. Is this an I)nitial install or a R)econfiguration? (I/R) [I] Where would you like to install DLXS? [/do/not/use] /l1/dlxstestThis is where you specify DLXSROOT as explained above. Note the option to "re-configure". If you choose it, you will be prompted for the location of a completed installation. The installer will then make another pass over the installed middleware .cfg files allowing you to change values you entered during the initial installation or subsequent reconfigurations. You can do this repeatedly.
Creating DLXSROOT... Unpacking tarball... Untarring all in /l1/INSTALL_CDROM into /l1/dlxstest... Untarring /l1/INSTALL_CDROM/CDROM_8_lib.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_collmgr.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_text.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_bib.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_findaid.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_image.tar.gz... Untarring /l1/INSTALL_CDROM/CDROM_8_broker.tar.gz... Making symlinks...Symlinks to the installed binaries are saved in DLXSROOT/bin/symlinks so the middleware can find them easily and we can avoid many inline replacements at install-time.
Processing config-examples... Processing replacements in
/l1/dlxstest/bin/installer/config-examples/crontab.dlxs Processing replacements in
/l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs Processing replacements in
/l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxs Processing replacements in
/l1/dlxstest/bin/installer/config-examples/httpd.conf.dlxsExample files for the Apache server virtual host configuration and setting up cron jobs are automatically customized with your local settings and reside in DLXSROOT/bin/installer/config-examples.
Processing ImageClass index replacements... Processing replacements in /l1/dlxstest/idx/s/sampleic/image.blank.dd Processing replacements in /l1/dlxstest/idx/s/sampleic/image.dd Processing replacements in /l1/dlxstest/idx/s/sampleic/image.cfg Processing replacements in /l1/dlxstest/idx/s/sampleic/Makefile Processing replacements in /l1/dlxstest/idx/s/sampleic/image.inp Processing replacements in /l1/dlxstest/idx/w/workshopic/image.blank.dd Processing replacements in /l1/dlxstest/idx/w/workshopic/image.dd Processing replacements in /l1/dlxstest/idx/w/workshopic/image.cfg Processing replacements in /l1/dlxstest/idx/w/workshopic/Makefile Processing replacements in /l1/dlxstest/idx/w/workshopic/image.inp Processing ImageClass Perl hashbangs... Processing replacements in
/l1/dlxstest/bin/i/image/clean.newlines.inplace.pl Processing replacements in /l1/dlxstest/bin/i/image/getoneline.pl Processing replacements in /l1/dlxstest/bin/i/image/htmltotab.pl Processing replacements in /l1/dlxstest/bin/i/image/idb Processing replacements in /l1/dlxstest/bin/i/image/imageprep Processing replacements in /l1/dlxstest/bin/i/image/makefieldbrowse.pl Processing replacements in /l1/dlxstest/bin/i/image/tabtohtml.pl Processing TextClass index replacements... Processing replacements in /l1/dlxstest/idx/s/sampletc/sampletc.dd Processing BibClass index replacements... Processing replacements in /l1/dlxstest/idx/s/samplebc/samplebc.ddThis section on replacements details string replacements in files that have hard-coded paths to Perl and to DLXSROOT.
Making /l1/dlxstest/web/t/text/gifcvtdir for TextClass image cacheIf you chose to install TextClass the image cache directory is created. It's permissions may to be changed post-install. See below.
Opening permissions to u+w g+w o+w on CSV database tables
in /l1/dlxstest/misc/db Processing replacements in
/l1/dlxstest/bin/installer/README-postinstallThe CSV database tables need world write permission since we are installing as a normal user and the web server needs to read and write them.
NEXT THE MIDDLEWARE .cfg FILES PROCESSING BEGINS ...
Configuring LibGlobals.cfg no authentication URL available: using Basic AuthBy default, we assume you do not have a URL to an authentication system at your site that is able to set the REMOTE_USER environment variable. We deliver an HTTP "Basic Auth" configuration in the virtual host example file DLXSROOT/bin/installer/config-examples/ httpd.conf.dlxs file.
Select the Collection database type (CSV/MySQL) [MySQL] CSVTo run "out of the box" choose CSV to use the sample database tables and collections. If you have already set up MySQL and used the database conversion utility dbconv to populate it, choose MySQL. Database conversion is discussed in the DLXS online documentation.
development MySQL server same as productionThis status message simply says that you have a single machine that serves as your production and development MySQL server. Configuring the middleware for a separate development and production environments is not addressed here.
Enter your Help email HTML href Enter your Help email text string [Your local email addresses that will appear in several of the HTML templates.
Configuring DlpsSession.cfg Select the session datastore type (CSV/MySQL) [CSV] Enter CSV session directory [/tmp/sessions] Enter CSV session lock directory [/tmp/sessionslock] development session host same as production hostSessions can be maintained in CSV files or in a MySQL database. If in CVS, enter the directory and lock directory where session files live. These directories must exist and be write permitted to the UID of the web server and should be created post-install.
Configuring BookBag.cfg Enter your SMTP host [mail.umdl.umich.edu]The mail host to use when mailing BookBag contents.
Enter the email address from which the BookBag mail will be sent
["UMDL Mailer" <>] Configuring collmgr.cfg (Collection Database Manager) no logout URL: using Basic AuthAs explained above, the collmgr needs to have REMOTE_USER set by some mechanism. By default we supply HTTP "Basic Auth".
Configuring dbconv.cfg Configuring dbmove.cfg Configuring textclass.cfg not using a development hostConfiguring PageView.cfg Select the *Pageviewer* datastore type. If you don't have page images but want to try sample data,
choose CSV (CSV/MySQL) [MySQL]A sample Pageview database table is supplied for the sampleic collection. For any significant application, CSV will not scale. If you just want to try the sampletc collection choose CSV. If you have a large scale collection of page images, choose MySQL.
Configuring bibclass.cfg Configuring imageclass.cfg Enter the image file server host name. If it is the same as the host serving image-idx, enter '/', otherwise enter e.g. http://imageserver.umdl.umich.edu/ [/] not using a development hostImageclass may be configured to use a different machine to serve image data than the machine running the middleware.
disabling PortfoliosThis status message indicated that ImageClass portfolio functionality is installed disabled by default. Setting up portfolios is discussed in the ImageClass documentation.
no ID resolver presentAt DLPS we have a CGI which maps image IDs to URLs so ImageClass can serve images maintained outside the usual ImageClass img directories.
Configuring imageprep.cfg Enter the path to mrsid_retrieve for imageprep [/l/local/bin/mrsid_retrieve]For technical reasons related to how the Installer works the MrSid path needs to be supplied again here.
Configuring broker.cfgbroker is the CGI program that responds to URLs that implement the OAI protocol.
Configuring the Identify Verb for broker Enter OAI Repository ID [dlpscoll] Enter OAI repository name [The University of Michigan.
University Library. Digital Library Production Service.] Enter the broker base URL [http://www.hti.umich.edu/cgi/b/broker/broker] Enter the broker email address [dlps-broker@umich.edu] Enter a sample OAI ID [oai:dlpscoll:YEATS-YC023]Now follow the post install notes treated more fully in the next section.
If your session database type is CSV, create the session and session lock 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.
The DLXSROOT/web/t/text/gifcvtdir is created by the Install program 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.
The files (sample database tables) in DLXSROOT/misc/db are installed with 666 permissions. Optionally, 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.<?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"?>
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 auth section in httpd.conf.dlxs basic authentication for the collmgr. If you disable this be aware that the collmgr requires some form of authentication which sets the REMOTE_USER variable for proper operation. So, to run "out of the box", the easiest thing to do is to use the "Basic Auth" sample configuration.
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 place in the "conf" subdirectory of you Apache installation.
If you installed ImageClass the sample indexes need to be rebuilt.
If you have a DLXS installation that predates CD-ROM #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 merged into the CSV tables located in DlXSROOT/misc/db See documentation on database functionality for complete instructions.