Installation

From DLXS Documentation

Revision as of 07:15, 16 July 2008

Red Hat 5.1 and DLXS 13 Installation

Disclaimer: These instructions were compiled from notes taken from installing DLXS 13 on a Red Hat 5.1 server. They are intended to be used as a loose reference and are not, by any stretch of the imagination, the only way to do this or even perhaps the best or most correct way to do this. Although these instructions did work for us, they are a 'work in progress' and will change as we continue to grow in our knowledge of DLXS 13 and RHEL 5.X. Use at your own risk and may the force be with you...

Materials list:

1. RHEL 5.1
2. DLXS 13 and XPAT CD’s
3. Patch(es) from DLXS
4. Server
5. Root access

Required Information concerning RHEL 5.1 installation

1. Your IP address
2. Your subnet mask
3. Your DNS server IP addresses
4. Your gateway IP address
5. If you have a service subscription you will also be asked for your activation code.
6. Security information (firewall settings, etc.)

Step 1 - Operating system installation.

I do not put a lot of instructions concerning the RHEL 5.1 install here. It is pretty much gui driven and I tend to be minimalistic in choosing the packages I want to be installed when I have choices to make. You will probably not be able to install a server on campus without help from your IT people. They will be able to give you answers to the questions that you will be asked during the installation. The questions will deal with things like IP address, subnet mask, DNS Server IP addresses and Gateway IP. Those are the easy questions. You will need more indepth information about setting it properly for firewall settings, etc and so that is why I cannot give you better instructions on how to set the server up. It is a good bet that your IT department will have standards for your Linux install and will take care of it for you. One thing I will mention is that during the RHEL 5.1 install make sure you choose to install Apache, PERL and MySQL and when you get done your Apache, PERL and MySQL should be fine.

NOTE: Our campus has a subscription for service from Red Hat. That means that Red Hat will automatically notify me when there is a suggested update on my server. Think of it like the Microsoft auto update feature, (or is that a bug?) Who knows, but regardless, because of our subscription as soon as I complete the RHEL 5.1 install I get a pop up saying that I need to run the updates. There will be lots of updates that will want to install. I held off doing the operating system updates until I had installed DLXS and it worked well for me. I did this because I was trying to minimize any problems that updating might introduce concerning perl mods and such.

NOTE: (This paragraph explains why I did not use the latest RHEL release) I tried to use the latest RHEL 5 software. However, I began to have problems after I had installed RHEL 5, and tried to install the perl mods. I was able to install most of them without issue except for XML::LibXSLT. The problem is that the perl mods XML::LibXSLT and XML::LibXML are closely related to libxml2. When I tried to install XML::LibXSLT (from cpan) I got an error message saying that libxml2 needed to be a newer version. That is when the real fun began. I used rpm (rpm -e libxml and rpm -e libxslt) to remove libxml and libxslt. It complained of dependencies and would not uninstall so I used the --nodeps switch to force the issue. I then downloaded the newer libxml2 (libxml2-2.6.27.tar.gz) file and libxslt (libxslt-1.1.18.tar.gz). I renamed the /usr/include/libxml2 directory and the /usr/include/libxslt directory (so that the install would create the folders it needed without any name conflict). I made a directory named libxml2 and installed libxml2-2.6.27.tar.gz in that directory. I installed the libxslt file. I used cpan and installed the 2 mods (XML::LibXML and XML::LibXSLT). The mods installed fine BUT I lost other functionality using this method. For instance yum quit working. This meant I had to start from scratch. I checked our test server and found out that we were running Red Hat 5.1. I checked the server I had just tried the install on and apparently Red Hat had upgraded their software and the download is now at Red Hat 5.2. I was able to locate some older RHEL 5 installation CD's and this time I had no problem installing the mods after reinstalling the operating system.

So… That said I suggest you use Red Hat 5.1 to begin with.

Step 2 - Installing the perl mods.

As of the date of this writing: 6/12/08 it is important to note that DLXS has an error on the wiki version of the required perl mods. The error is that you need to install Text::CSV_XS instead of Text::CSV. If you do not install Text::CSV_XS your sample collections will still work fine when you finish installing DLXS the problem will not become manifest until you try to build a collection. You will have lots of errors. (At least we did when we tried to build an image collection right after the DLXS install.)

The tough part is to install the required perl mods. It can be a slow, frustrating process and so if you need to cut back on the caffeine now is the time because we are moving on to actually installing the perl mods.

You need to know what perl mods got installed automagically during the RHEL 5.1 install. I used a utility called pmdesc3.pl to see what mods were already on board. (./pmdesc3.pl | grep modname). You can download this utility from http://lug.fh-swf.de/perl/
These required mods were onboard after the RHEL 5.1 install (NOTE: You may have different ones listed and that is fine. Just use the methods described below to get the ones you are missing.)

a. DBD::mysql 3.0007
b. DBI 1.52
c. Attribute_Handlers 0.78_02

From cpan I installed these (cpan install modname)

a. Apache::Session 1.86
b. Text::CSV 1.05 (NOTE: This was installed due to an error on the DLXS installation pages from the wiki. I just left it after I found the mistake)
c. Text::CSV_XS 0.5 (NOTE: This one has a ton of dependencies that it will ask you if you want it to append it to the queue to be installed. I just chose ‘yes’ until it finished. The install took a while but it worked.
d. Mail::Mailer 2.03
e. Data::Page 2.0
f. Test::WWW::Mechanize 1.20
g. How to install XML::LibXML and XML::LibXSLT

DOWNLOAD from cpan - Note that there were newer versions that I just did not want to worry with. These were known good (from installing on my test server) and so I used the 1.58 versions.

XML-LibXML-1.58.tar.gz
XML-LibXSLT-1.58.tar.gz

I put them in a folder I created named /xx/mods and used gunzip to unzip them. (gunzip *)
I untarred them tar (tar -xvf filename)
I tried to install XML-LibXML first but it bombed and told me I needed to install:

XML::LibXML::Common
XML::NamespaceSupport
XML::SAX

I used cpan to install these (cpan install modname).
I installed XML-LibXML-1.58 by going into the XML-LibXML directory and running the following:

perl Makefile.PL
make
make test
make install

I then installed XML::LibXSLT by going into the XML-LibXSLT folder and running the following perl Makefile.PL
make
make test
make install

h. In order to install Image::Magick I had to use yum. You might already have ImageMagick installed but the perl mod isn't listing when you run ./pmdesc.pl | grep -i ImageMagick. If that is the case you might want to try updating by using yum update ImageMagick. I don't believe ImageMagick was installed when I finished the RHEL 5.1 install (I don't remember) but anyway I just used yum install ImageMagick AND yum install ImageMagick-perl to get the required Image::Magick perl mod installed.

i. To install Geo::IP
go to http://www.maxmind.com/download/geoip/api/perl and download Geo-IP-1.30.tar.gz
go to http://www.maxmind.com/download/geoip/api/c and download GeoIP.tar.gz
install GeoIP.tar.gz by using gunzip GeoIP.tar.gz and then using tar -xvf GeoIP.tar and run these commands:

./configure
make
make check
make install

install Geo-IP-1.30.tar.gz by using gunzip Geo-IP-1.30.tar.gz and then using tar -xvf Geo-IP-1.30.tar.gz and run these commands:

perl Makefile.PL
make
make test
make install

Step 3 - Installing OpenSP 1.5

Go to http://www.linuxfromscratch.org/blfs/view/stable/pst/opensp.html and download OpenSP-1.5.2
a. Run gunzip OpenSP-1.5.2.tar.gz and then untar the file (tar -xvf OpenSP-1.5.2.tar.gz).
b. Run the following commands to install OpenSP. NOTE: I just copy and paste them into the command line one at a time. It saves me typing my fingers off.

sed -i 's:32,:253,:' lib/Syntax.cxx &&
sed -i 's:LITLEN 240 :LITLEN 8092:' \
unicode/{gensyntax.pl,unicode.syn} &&
./configure --prefix=/usr --disable-static --disable-doc-build \
--enable-default-catalog=/etc/sgml/catalog --enable-http \
--enable-default-search-path=/usr/share/sgml &&
make pkgdatadir=/usr/share/sgml/OpenSP-1.5.2

To test,
Run the command: make check
NOTE: As many as 8 or 9 of the 22 tests may fail. Don’t worry about it. Just smile and move on.

As root user run the following commands:

make pkgdatadir=/usr/share/sgml/OpenSP-1.5.2 install &&
ln -v -sf onsgmls /usr/bin/nsgmls &&
ln -v -sf osgmlnorm /usr/bin/sgmlnorm &&
ln -v -sf ospam /usr/bin/spam &&
ln -v -sf ospcat /usr/bin/spcat &&
ln -v -sf ospent /usr/bin/spent &&
ln -v -sf osx /usr/bin/sx &&
ln -v -sf osx /usr/bin/sgml2xml &&
ln -v -sf libosp.so /usr/lib/libsp.so

NOTE: It is important to note that sgml-common-0.6.3 is listed as a dependency of OpenSP 1.5. During a previous install I had serious issues with installing sgml-common-0.6.3. I emailed Tom Burton-West at DLXS tech support and he told me that as of version 1.5 there were no dependencies on SGML-Common. So I said "cool" and just didn't install sgml-common-0.6.3. As far as I can tell it has not been an issue.

Step 4 - Installing the binaries!

A. Copy XPAT and the DLXS CD to the server
XPAT: cp xpat_linux-5.3.2.tar to /usr/local/
DLXS: cp –r * /usr/local/dlxs

B. cd /usr/local and run tar –xvf xpat_linux-5.3.2.tar
go to /usr/local/bin and create a symbolic link to the xpat directory using: ln -s /usr/local/xpat-5.3.2/bin/xpat xpat

C: cd /usr/local/dlxs and install the following binaries. (Note that I copied the binary AND created the symlink in /usr/local/bin. Just my preference. You could actually have just created the symlink to where ever you unzipped each of the binaries and placed only the symlinks in /usr/local/bin. For purposes of this documentation, let's just do it my way and decide the best way later...)

- tif2web –

cd /usr/local/dlxs/tif2web-1.0.4
gunzip tif2web-linux-x86.gz
chmod 755 tif2web-linux-x86
cp tif2web-linux-x86 to /usr/local/bin
cd /usr/local/bin
ln -s /usr/local/bin/tif2web-linux-x86 tif2web

- mrsid_retrieve –

cd /usr/local/dlxs/iso/mrsid_retrieve-1.3.1
gunzip mrsid_retrieve-linux-x86.gz
chmod 755 mrsid_retrieve-linux-x86
cp mrsid_retrieve-linux-x86 to /usr/local/bin
cd /usr/local/bin
ln -s /usr/local/bin/mrsid_retrieve-linux-x86 mrsid_retrieve

- kdu_expand –

cd /usr/local/dlxs/iso/kakadu-4.0.2
gunzip kdu_expand-linux-x86.gz
chmod 755 kdu_expand-linux-x86
cp kdu_expand-linux-x86 to /usr/local/bin
cd /usr/local/bin
ln-s kdu_expand-linux-x86 kdu_expand

- kdu_compress –

cd /usr/local/dlxs/iso/kakadu-4.0.2
gunzip kdu_compress-linux-x86.gz
chmod 755 kdu_compress-linux-x86
cp kdu_compress-linux-x86 to /usr/local/bin
cd /usr/local/bin
ln -s kdu_compress-linux-x8 kdu_compress

- cjpeg –

cd /usr/local/dlxs/iso/cjpeg-6b
gunzip cjpeg-linux-x86.gz
chmod 755 cjpeg-linux-x86
cp cjpeg-linux-x86 to /usr/local/bin
cd /usr/local/bin
ln -s /usr/local/bin/cjpeg-linux-x86 cjpeg

- c42pdf –

Download this from http://c42pdf.ffii.org
if the file says you cannot unzip it because it is not zipped, change the name to drop the .gz in this case I named it c42pdf
chmod 755 c42pdf
copy c42pdf to /usr/local/bin (Note: I did not need a symlink because I changed the name and copied it here. In retrospect it would probably have been better if I had simply created symlinks here to the directory that I used when I copied the DLXS CD to the server.

Step 5 - Installing DLXS

cd into the directory that you copied the DLXS installation cd to.
perl Installer.pl

The installation will begin and you will be asked a lot of questions. It is important that you keep track of the answers you provide as you will need to enter the information again later when you configure MySQL. Also you will be offered default answers during the install. Some of the default answers reference paths to the binaries. If you put created the symlinks in the /usr/local/bin directory as instructed in item 4 then the installer should be offering you the correct location. If not, you will get a 'can't be found' type of error. All you have to do is go find what it is asking for and type that path in as the answer to the installer question. I have installed 3 different versions of DLXS and the documention is a little off from what I saw each time I installed but, from memory, this is pretty much what you will be asked:

- Which platform are you using? (SunOS/Linux) [SunOS] (You need to choose your platform - in my case Linux - so I did not accept the default. I had to type in Linux.
- Where is Perl installed? [/usr/bin/perl] (Another issue here - For some reason the .pl files that get installed will need to be changed to reflect your actual perl path. We have found some of the scripts use #!/usr/bin/perl at the top of the scripts and some of the scripts have #!/usr/bin/local/perl at the top. You need to go change those scripts to point to your perl install. In our case it is /usr/bin/perl.

- Where is XPAT installed? [/l/local/bin/xpat]
- Do you want to use tif2web (required for TextClass page viewer)? [Y]
- Where is tif2web installed? [/l/local/bin/tif2web]
- 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]

At this point you get the idea. It is just asking for all the binary locations.

OKAY... The installer now moves on to variable configuration and the actually file installation.

- Is this an I)nitial install or a R)econfiguration? (I/R) [I] For initial install
- Where would you like to install DLXS? [//] /somedir/dlxs
- What is the fully-qualified name of this server? [servername.domain.extension - example: servername.richmond.edu]
- What is the IP address of this server? [000.000.000.000 - example: You will need to know your actual IP address for your server here]
- Enter MySQL database name [dlxs_vwhateverversionyouhave example: dlxs_13]
- Enter MySQL database user name (middleware will connect as this user) [dlxs]
- Enter password for MySQL database user name [somepassword - example: just pick a password for the MySQL database user above]
- Enter MySQL database password for the "dlxsadm" ADMINISTRATIVE user [somepassword - example: just pick a password for dlxsadm]
- Enter MySQL database server name. [servername.domain.extension - example: servername.richmond.edu]
- Enter the virtual host of the idresolver cgi. [images.umdl.umich.edu] - Enter a blank here
- Select sendmail or smtp to deliver mail. (sendmail/smtp) [sendmail]
- Enter the email address from which the generated (e.g. BookBag) mail will be sent ["UMDL Mailer" <umdl-help@umich.edu>] NOTE: This is the email address of the lucky person who will be in charge of replying to BookBag questions.
- Enter your Help email HTML href [1] NOTE: This is the email address of the lucky person who will be in charge of replying to help questions.
- Enter your Help email text string [umdl-help@umich.edu] I 'think' this is the text someone will see when they want some sort of help.

Okay, here is where it gets confusing (stop laughing, I meant more confusing...)

At this point you are still in the install. U.R. does not have an OAI Repository set up, so we pretty much just took the defaults. One suggestion for the DLXS developers is to have the installer ask first - "Do you have an OAI Repository set up?" and if you answer "no" then it just skips this section entirely by entering some defaults automatically. But that is future stuff and we must now get back to our install...

- Enter OAI Repository ID [lib.umich.edu] We have no repository so we just took the default.
- Enter OAI repostiory name [UMDL. DLPS] We took the default
- Enter the broker base URL [2] We, you guessed it... took the default.
- Enter the broker email address [dlps-broker@umich.edu] We took the default.
- Enter a UTCdatetime... [2000-08-17] Just take the default.
- Enter the manner... [no] Take the default
- Enter a sample OAI ID [oai:lib.umich.edu:YC023] Take the default, you know you want to!
- Enter part 1 of your repository description [ lots of stuff here] OK this is something you don't need the default for! YAY! This basically just describes your collections.
- Enter part 2 of your repository description [lots of stuff here] I guess the description just continues here.
- Enter part 3 of your repository description [lots of stuff here] Just keep describing your collections.
- Enter the metadata formats... [oai_dc,mods] I took the default
- Enter the sru default collection [oaister] Took the default
- Enter the sru host [quod.lib.umich.edu] Took the default
- Enter the sru port [620] Took the default
- Enter the sru title [University of Michigan Gateway] Took the default
- Enter the sru description [SRU Gateway... ] Took the default
- Enter your Collmgr Help...HTML href [collmrg info] mailto:help@yourschool.edu
- Enter you Collmgr Help text string [collmgr info] help@yourschool.edu
- Enable filtering of DAOs.. (1/0)[1] Take default
- Enter the image file server host name... [/] I took default
- Enter your name resolver... [http... umich.edu] Enter an empty string if you do not have a name resolver URL
- Create web optimized pdfs? [Y] Take default

This is the end of the install but now you need to do some post install things.

Step 6 - Change ownership

The DLXS documentation says "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." We changed ownership to apache on $DLXSROOT/web/cache.

cd /$DLXSR
chown -R apache cache
chgrp -R apache cache

Step 7 - Set up crontab to take care of system maintenance.

READ this whole paragraph before you go forward. If you edit your crontab incorrectly you will regret it. NOTE: Your server will more than likely be much different from mine and you may have an existing crontab file with other cron jobs running already. If that is the case don’t follow this instruction. See your sys admin on how to add this to your existing cron job list. If you still want to set up this cron job:

crontab -e
copy and paste the text below into crontab. This is taken directly from the DLXS documentation and is actually a listing of the crontab on the server I just set up. NOTE: /xx denotes our path in the paths that I list below. Make sure /xx is changed to your correct path.

#
# purge DLXS web cache
21 3 * * * /xx/dlxs/bin/managecache.sh
#
# purge DLXS CSV sessions (This is commented out because we don't need it.)
#11 * * * * (DLXSROOT=/xx/dlxs; export DLXSROOT; $DLXSROOT/bin/managesessions.pl -m clean -a 120 -s CSV )
> /tmp/managesessions.log 2>&1
#
# purge DLXS MySQL sessions
11 * * * * (DLXSROOT=/xx/dlxs; export DLXSROOT; $DLXSROOT/bin/managesessions.pl -m clean -a 120 -s MySQL) > /tmp/managesessions.log 2>&1
#
# purge Image Class temporary Portfolios at least 3 days old
# only necessary if Portfolios are enabled in Image Class
# Image Class must be properly installed under same DLXSROOT
30 2 * * * (DLXSROOT=/xx/dlxs /xx/dlxs/bin/manageportfolios.pl) 2> /dev/null

Step 8 - Apache configuration.

This is going to sound a lot more complicated than it actually is. All you have to do is copy one file to /etc/httpd/conf/ , make a back up copy of your /etc/httpd/conf/httpd.conf file and then edit it to paste something at the bottom, and change a password (See? This is a total piece of cake!) Let’s do it!

- cp /$DLXSROOT/bin/installer/config-examples/ htpasswd.dlxs /etc/httpd/conf/ (This is a default authentication file that contains the encrypted password for 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:

- /usr/bin/htpasswd /etc/httpd/conf/htpasswd.dlxs dlxsadm

Again, make a backup copy of your /etc/httpd/conf/httpd.conf file before you do anything to modify it.
- cp /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.bak
Now let’s modify the httpd.conf file.

- vi $DLXSROOT/bin/installer/config-examples/httpd.conf.dlxs
Select all the text and copy it and exit vi. (You will need this text to paste into your httpd.conf file.)

- vi /etc/httpd/conf/httpd.conf (This opens httpd.conf for editing. You can really mess things up if you are not careful here.)
- After the file opens go to the bottom and paste the contents of httpd.conf.dlxs. Save the file and exit vi.

Step 9 - MySQL configuration.

- Start the SQL monitor with the command mysql -u root -p mysql (you will be prompted for the MySQL system password. At this point you do not have one).
- create database dlxs_versionnumber; (At this time you could use dlxs_13)
- grant all privileges on dlxs_versionnumber to dlxsadm identified by 'dlxsadm password'; ex: grant all privileges on dlxs_13 to dlxsadm identified by 'bluebird';
- grant file on *.* to dlxsadm;
- grant select,insert,update,delete,references on dlxs_versionnumber to dlxs identified by 'password'; NOTE this is the dlxs password chosen during the install for the MySQL database user name. ex: grant select,insert,update,delete,references on dlxs_13 to dlxs identified by 'dlxsguyspassword';
- flush privileges;.
- quit.

Okay it's time to take a moment to discuss the problems we had with MySQL. For some reason there was an anonymous login for localhost user listed in the user table for mysql. It interferes with being able to login as dlxsadm. Check with your sys admins because they may actually have a reason for the account but I do not and so I removed it using:

mysql -u root -p (Hit enter when prompted for the password)
use mysql;
drop user “”@“localhost”;
- quit

It's time now to populate the sample collection database. This will allow you to test your installation of DLXS shortly.
mysql -u dlxsadm -p dlxs_v13 < $DLXSROOT/misc/db/db-dump-v6.0-release.sql (note that you might have to change the dlxs_13 to the name of your dlxs database.)

Step 10 – File updates and DLXS 13 patches.

You need to edit $DLXSROOT/web/i/image/js/imageclass.js
- vi $DLXSROOT/web/i/image/js/imageclass.js
- At the top you will see: document.domain = 'umdl.umich.edu'; Change the umdl.umich.edu to your server.domain.edu. ex: servername.richmond.edu.
- save the file and exit vi.

- apply DLXS 13 patches –

- go to http://www.dlxs.org/products/archive-by-CDROM/13/Patches/ and download all the patches.
- follow the instructions on how to install each of the patches.

Step 11 - Do you feel lucky? Well, do you? Let’s see…

If you do feel lucky then you can now test your installation by going to the URL's below to log into the various classes and collmgr. Note: If you get some kind of error just make sure that mysql and apache are running on the server. Do that by:

cd //etc/rc.d/init.d
./httpd start (or ./httpd restart if it is already running. You ALWAYS have to restart apache when you change the httpd.conf file.
./mysqld start

In the URL's below just substitute your server in for YOURVIRTUALHOST as in this example:
http://servername.yourschool.edu/cgi/c/collmgr

- Collmgr: http://YOURVIRTUALHOST/cgi/c/collmgr/collmgr
- BibClass: http://YOURVIRTUALHOST/cgi/b/bib/bib-idx?c=samplebc
- FindaidClass: http://YOURVIRTUALHOST/cgi/f/findaid/findaid-idx?c=samplefa
- ImageClass: http://YOURVIRTUALHOST/cgi/i/image/image-idx?c=sampleic
- TextClass: http://YOURVIRTUALHOST/cgi/t/text/text-idx?c=sampletc_utf8

Did it work? If so, buy a lottery ticket on the way home from work. Also, run the RHEL 5.1 updates. There will probably be like 200 or more updates needed so you will need to update in smaller groups by using yum check-update. You will get a list that you can use to update in groups, an example being: yum update in* ip* ir* is* would run updates on items beginning with ip, ir, or is.

If it did not work (Repeat after me: “@#$**@$#!! )

Step 12 - Troubleshooting.

Again! Make sure Apache and MySQL are running (see step 11 above for instructions).

For troubleshooting you will have to run some debug commands and maybe check some Apache server logs. I am listing the logs files below but for the more advanced troubleshooting you will need to check out the URL below.

tail -20 /etc/httpd/logs/error_log
tail -20 /etc/httpd/logs/access_log

These files will give you clues as to incorrect directory permissions or perhaps path issues.

DLXS has more intense troubleshooting advice here:

http://webapps.itcs.umich.edu/dlxsdocs/index.php/Installation_Troubleshooting

Rick Neal
University of Richmond
rneal@richmond.edu