Dspace 1.6.x on Red Hat Enterprise Linux 5 (RHEL5)

Assumptions

• Standard RHEL5 (32-bit) server - This build/document assumes you are running RHEL5_, but it could possibly be adapted to a CentOS5 system._
  •  RHEL Supplementary channel (v. 5 for 32-bit x86) - This is what provides a source for Sun Java updates. It is assumed you have a valid Red Hat Network account that you can manage your systems.
• Package Management - All required software for DSpace is provided and managed using package management, in our case RPM's. It is assumed software from external repositories used get regular updates, are trusted as secure, and all packages are maintained regularly.

Install

• Requirement - Perl (no version listed.) – RHEL5 currently provides perl 5.8.8. and was Installed by our default RHEL5 build.
• Requirement - Sun Java 1.5 or better, we will install Sun Java 1.6 -
  (RHEL5 currently provides Sun Java 1.5 & 1.6 through the RHEL Supplementary (v. 5 for 32-bit x86) channel)
  1. Requires RHEL Supplementary (v. 5 for 32-bit x86) channel to get access to the Sun Java.
     This is done through the web interface @ https://rhn.redhat.com
  2. Install Sun Java 6:

     yum install java-1.6.0-sun java-1.6.0-sun-devel -y

     Output for Sun Java 6 install:

     Dependencies Resolved
     
     ================================================================================
      Package        Arch   Version           Repository                        Size
     ================================================================================
     Installing:
      java-1.6.0-sun i586   1:1.6.0.20-1jpp.1.el5
                                              rhel-i386-server-supplementary-5  37 M
      java-1.6.0-sun-devel
                     i586   1:1.6.0.20-1jpp.1.el5
                                              rhel-i386-server-supplementary-5  20 M
     Installing for dependencies:
      jpackage-utils noarch 1.7.3-1jpp.2.el5  rhel-i386-server-5                61 k
     
     Transaction Summary
     ================================================================================
     Install       3 Package(s)
     Upgrade       0 Package(s)
     
     Total download size: 57 M
     

     Notice here

     Installing Java the jpackage-utils 1.7 is also installed which is maintained by Red Hat. Later on it will be replaced by the JPackage maintained version and can/will cause some problems after we install and start using the JPackage repo.

• Requirement - Relational Database, PostgreSQL 7.4 or later - (RHEL5 currently provides postgres 8.1.18(default) and 8.4 is available too.)
  1. Install Postgresql:

     yum install postgresql-server -y

     This will install the postgresql dependency.
     Output for Postgresql Server install:

     Dependencies Resolved
     
     ================================================================================
     Package              Arch    Version               Repository             Size
     ================================================================================
     Installing:
     postgresql-server    i386    8.1.21-1.el5_5.1      rhel-i386-server-5    3.8 M
     Installing for dependencies:
     postgresql           i386    8.1.21-1.el5_5.1      rhel-i386-server-5    2.9 M
     
     Transaction Summary
     ================================================================================
     Install       2 Package(s)
     Upgrade       0 Package(s)
     
     Total download size: 6.7 M
     

Install and Configure the JPackage repository

(Ok, this is somewhat dirty and I don't know if this work work in a sustainable way, but here goes the experiment.)

1. Install a custom repo file to use Jpackage repository v5.0:

   wget -P/etc/yum.repos.d http://librhn.unm.edu/pub/jpackage50-ant17-maven2-mod.repo

   The contents of the config is listed at the end of this document: #Config Files
2. Install the GPG key from JPackage:

   rpm --import http://www.jpackage.org/jpackage.asc

3. Update the system to use the new jpackage-utils 5.0 package:

   yum update -y

   Notice

   Unfortunately this has a bad side effect of removing /usr/bin/rebuild-security-providers, which was maintained in the RHEL 5 jpackage-utils 1.7, but not in the new one provided by Jpackage. This is also a known RHEL5 + JPackage bug: https://bugzilla.redhat.com/show_bug.cgi?id=497213

4. Now we need to install a workaround, to address the missing /usr/bin/rebuild-security-providers dependency((I used directions I found for CentOS 5: http://plone.lucidsolutions.co.nz/linux/centos/jpackage-jpackage-utils-compatibility-for-centos-5.x))((This link is also useful, and somewhat related to getting the repo config file we used to work: http://plone.lucidsolutions.co.nz/linux/centos/jpackage-rpm-repository-for-centos-rhel-5.x)).

   rpm -ivh http://plone.lucidsolutions.co.nz/linux/centos/images/jpackage-utils-compat-el5-0.0.1-1.noarch.rpm

   What a mess... but it's working.

Install Tomcat5, Ant 1.7 and Maven 2 with jpackage filters

(We continue installing prerequisite software for Dspace 1.6 on RHEL5...)

• Requirement Jakarta Tomcat 4.x or later - RHEL5 currently provides Tomcat 5.5.23.
  1. Install Tomcat5 and postgres-jdbc connector:

     yum install tomcat5 tomcat5-webapps postgresql-jdbc geronimo-javamail-1.4-api -x classpathx-mail -y

     This will be a large list of dependencies to be installed, BUT the majority of the packages will be installed from official RHEL 5 channels. This is a good thing. Also removed/excluded the default java mail package classpathx-mail (gnu) as it wasn't working with Dspace, replaced with geronimo java mail. You may get an error here when tomcat5-common-lib is installed, but I don't think it is a game-stopper.
  2. Since we changed the java mailer, we need to update alternatives to use the Geronimo version, which doesn't configure itself upon install:

     alternatives --install /usr/share/java/javamail.jar javamail /usr/share/java/geronimo-javamail-1.4-api-1.1.jar 666

     This step is necessary, otherwise Tomcat reports errors every time it starts up.
• Requirement Apache Ant 1.7 or later (Java build tool) – RHEL5 currently provides ant-1.6.5. – Ant 1.7 was installed as a dependency for Tomcat5 via the jpackage repo, per the work we did in the jpackage repo config file.(previous step)Let's install a missed Ant related package which is required for a Dspace 1.6 build:

  yum install ant-apache-regexp -y

• Requirement Apache Maven 2.0.8 or later (Java build tool) – The Maven2 install turns out to be the most complicated package to install on this system because the HUGE number of dependent packages. From the work done when creating the custom jpackage repo file(previous steps), we can install:

  yum install maven2 -y

Java Advanced Imaging (JAI) package install

( This package was created in a previous build, and was declared required for out install, so all we need to do is install it. I'm assuming it works. This is apparently what rescales TIFF images into jpg thumbnails. )

1. Install the Java Advanced Imaging (JAI) rpm:

   rpm -ivh http://librhn.unm.edu/pub/jai-1.1.2.01-1jpp.i586.rpm

Configure the RHEL5 Environment for Dspace 1.6

(At this point, we should have all the pre-requisite software installed. Now we need to make a few tweaks to make the System a good and sustainable environment for Dspace 1.6.)

Configure the Web Services

1. Update /etc/tomcat5/tomcat5.conf to turn on UTF-8 and some Java memory settings in Tomcat5:

   vi /etc/tomcat5/tomcat5.conf

   #JAVA_OPTS="-Xminf0.1 -Xmaxf0.3"
   JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

2. Edit Tomcat server config to use the appBase dspace webapps directory and use UTF-8 file encoding:

   vi /etc/tomcat5/server.xml

   Add URIEncoding="UTF-8", when finished it looks like the following:

   <Connector port="8080" URIEncoding="UTF-8" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" redirectPort="8443" acceptCount="100"
   connectionTimeout="20000" disableUploadTimeout="true" />

   Also URIEncoding="UTF-8" for port 8443 & the AJP 1.3 Connector:

   <!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
   <!--
   <Connector port="8443" URIEncoding="UTF-8" maxHttpHeaderSize="8192"
   maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
   enableLookups="false" disableUploadTimeout="true"
   acceptCount="100" scheme="https" secure="true"
   clientAuth="false" sslProtocol="TLS" />
   -->
   
   <!-- Define an AJP 1.3 Connector on port 8009 -->
   <Connector port="8009" URIEncoding="UTF-8"
   enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

   Change the default appBase to use the dspace/webapps directory and add some new Context path's:

   <Host name="localhost" appBase="/opt/dspace/webapps"
   unpackWARs="true" autoDeploy="true"
   xmlValidation="false" xmlNamespaceAware="false">
   
   <!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface  -->
   <Context path="/jspui" docBase="/opt/dspace/webapps/jspui" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>
   
   <!-- DEFINE A CONTEXT PATH FOR DSpace XML User Interface (Manakin) -->
   <Context path="/xmlui" docBase="/opt/dspace/webapps/xmlui" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>
   
   <!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface  -->
   <Context path="/oai" docBase="/opt/dspace/webapps/oai" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>

3. Configure mod_proxy_ajp connector, /etc/httpd/conf.d/proxy_ajp.conf:

   vi /etc/httpd/conf.d/proxy_ajp.conf

   _Append this to the end of the file:\_ (file:_)

   # Always keep the host header
   ProxyPreserveHost On
   
   # Dspace related rules
   #ProxyPass /do_not_touch         \!
   ProxyPass /                     ajp://localhost:8009/
   ProxyPassReverse /              ajp://localhost:8009/
   ProxyPassReverseCookiePath /    /

   *Note:*If you want to block the ajp connector from connecting to something, the "!" <bang> sets Apache web-server to NOT REDIRECT everything under /do_not_touch

4. Configure the default vhost:

   vi /etc/httpd/conf.d/dspace.conf

   # Dspace vhost
   <VirtualHost _default_:80>
   ServerName repository.unm.edu
   DocumentRoot "/opt/dspace/webapps"
   ErrorLog logs/repository-error_log
   CustomLog logs/repository-access_log common
   
   RewriteEngine On
   RewriteRule \^/dspace/(.*) /$1 [R=permanent]
   </VirtualHost>

Configure the Postgresql DB Service

1. Create a override config for Dspace to relocate the DB to /opt/dspace/database:

   vi /etc/sysconfig/pgsql/postgresql

   Contents are as follows:

   # New Location for the Dspace install of the database
   PGDATA=/opt/dspace/database

2. Start the PostgreSQL Service to generate the initial config files:

   service postgresql start

3. Edit /opt/dspace/database/postgresql.conf:

   vi /opt/dspace/database/postgresql.conf

   uncomment the line #listen_address = 'localhost'

   listen_addresses = 'localhost'

4. Edit /opt/dspace/database/pg_hba.conf:

   vi /opt/dspace/database/pg_hba.conf

   and modify the "local" connections like the following:

   local   all         all                               trust
   host    all         all         127.0.0.1/32          trust

   Warning: Setting these connections to "trust" is less than ideal from a security perspective. This works for us as we do not allow any external connections to the database. If you want to allow external connections, this setting should be at least md5. The "trust" setting is still relatively safe as long as you only allow local connections.

5. Then restart PostgreSQL:

   service postgresql restart

6. Create the dspace database user and initial database:

   su -c "createuser -U postgres -d -A -R -P dspace" postgres;
   su -c "createdb -U dspace -E UNICODE dspace" postgres

   You will be prompted for a password for the DSpace database.

   Note: You may get a error if you were still in the /root home directory when you ran the commands. This can be safely ignored.

Setup the user environment

(In this section, I will set up appropriate sudo access for our web admins and configure a few initial users.)

1. Setup sudo access for WEBADMINS:

   visudo

   Append this to the end of the file:

   ## Sudo rules for the Postgresql service
   User_Alias DBADMINS = <insert your users or groups>
   Cmnd_Alias PSQL_CTRL = /sbin/service postgresql *
   Cmnd_Alias POSTGRES_USR = /bin/su - postgres
   DBADMINS   ALL= PSQL_CTRL, POSTGRES_USR
   
   ## Sudo rules for people who are Web Admins:
   ## They can influence Apache, Tomcat5, and the Dspace Handle Service.
   User_Alias WEBADMINS = <insert your users or groups>
   Cmnd_Alias WEB_EDIT_CFGS = /usr/bin/rvim /etc/php.*, /usr/bin/rvim /etc/httpd/*, /usr/bin/rvim /etc/tomcat5/\*
   Cmnd_Alias APACHE_CTRL = /sbin/service httpd *
   Cmnd_Alias TOMCAT5_CTRL = /sbin/service tomcat5 *
   Cmnd_Alias HANDLE_CTRL = /sbin/service dspace-handle *
   WEBADMINS  ALL= APACHE_CTRL, TOMCAT5_CTRL, HANDLE_CTRL, WEB_EDIT_CFGS
   
   ## Some Dspace specific rules, required since we don't have a "dspace" user.
   User_Alias DS_ADMINS = <insert your Dspace developer(s)>
   Cmnd_Alias DS_BUILD = /usr/bin/ant *
   Cmnd_Alias DS_CMDS = /opt/dspace/bin/\*
   Cmnd_Alias DS_HANDLE_CFG = /usr/bin/rvim /opt/dspace/handle-server/config.dct
   DS_ADMINS ALL=(tomcat) DS_BUILD, DS_CMDS, DS_HANDLE_CFG
   DS_ADMINS ALL= /opt/dspace/sbin/make_xmlui_active

2. Add a helper script when DSpace updates occur:

   su -c "mkdir /opt/dspace/sbin" tomcat; vi /opt/dspace/sbin/make_xmlui_active

   The contents are simply:

   # Make the xmlui the default ROOT, since any DSpace updates clobber the old one.
   su -c "cd /opt/dspace/webapps; ln -s ./xmlui ROOT" tomcat

3. Make sure we flag the execute bit:

   chmod +x /opt/dspace/sbin/make_xmlui_active

   *Note:* There is a matching sudo rule for this above, which ends up running as root to force ownership as tomcat. This file is owned by root and can not be modified by anyone else on the system, other than root. It's purpose is to put the ROOT link back to xmlui in /opt/dspace/webapps after every update. Unfortunately it couldn't be placed in dspace/bin, since DSpace nukes that directory regularly.