DSpace 1.6.x

This document describes installing DSpace-1.6.2 with Redhat distribution packages which reduce much of the complexity of installation and maintenance for the System Administrator. The products Apache Maven and DSpace are exceptions and are downloaded and installed seperately.

It assumes a basic understanding of

1. [bash() shell and environment variables|http://www.ibm.com/developerworks/linux/library/l-bash.html]# [Redhat package and service management|Redhat package and service management]It assumes the RHEL 5 Supplementary package channel is available, which provides Sun's Java and which requires registration with RHN, the following packages are expected to be available
2. sun java
3. apache tomcat5
4. postgresql-server
5. and ant() (a build tool)

It assumes these terms for location of source code and final destination directories

1. DS_SRC = /home/dspace/src ; DS expands to DSpace
2. DS_DST = /usr/local/dspace
3. OI_SRC = /usr/local/src – for example has apache-maven-X.Y.Z
4. OI_DST = /usr/local – OI expands to Other Installations, for example has softlink for maven
5. TMP = /var/tmp

The convention is to download to TMP, unpack to one of XX_SRC, and finally install to one of XX_DST.

While this document references Redhat, yum(8), and rpm(8) for platform and package management, as far as [GNU/Linux|http://en.wikipedia.org/wiki/GNU/Linux_naming_controversy] [distributions|http://lwn.net/Distributions/] go, [Debian|http://www.debian.org] or [Arch Linux|http://www.archlinux.org] are worth mentioning. Whereas Debian and derivatives such as [Ubuntu|http://www.ubuntu.com] and the idealistic [GNS|http://www.gnewsense.org] have apt-get(8) for package management, Arch Linux has pacman(8). For the competent system administrator, Arch Linux is a strong choice.

The install procedure involves

1. installing and configuring the pre-requisite packages available from Redhat
2. creating & setting the dspace user and environment
3. installing Maven and DSpace & setting dspace.cfg [TO_BE_DONE: package this for distribution|TO_BE_DONE: package this for distribution]# and finally, ensuring the ongoing behind the scenes services run & continue to run

To experiment after an initial installation, the likely procedure is to

1. stop tomcat5
2. change dspace.cfg and update by ant()
3. start tomcat5

or

1. stop tomcat5
2. remove all of DS_DST/*
3. drop the database and database user
4. create the database user and database
5. make changes to dspace.cfg and build DSpace by mvn() and ant()
6. create the DSpace administrator
7. start tomcat5

Install the pre-requisite packages available from Redhat

To install use

Details of Sun Java

To find the files with jvm/jre in the pathname, use

To show the file executed when java is called and the version number, use

type java
  java is /usr/bin/java
readlink /usr/bin/java
  /etc/alternatives/java
readlink /etc/alternatives/java
  /usr/lib/jvm/jre-1.6.0-sun/bin/java

/usr/lib/jvm/jre-1.6.0-sun/bin/java -version
  java version "1.6.0_21"

  Java(TM) SE Runtime Environment (build 1.6.0_21-b06)
  Java HotSpot(TM) Server VM (build 17.0-b16, mixed mode)

Note: set the environment variables for JAVA_HOME and JRE_HOME as described in the environment section.

 # to cut to the chase.. you may try this in your .bash_profile

 x='/etc/java/java.conf'
 [ -a "$x" ] && source "$x"

 x='/etc/tomcat5/tomcat5.conf'
 [ -a "$x" ] && source "$x"

 export JAVA_HOME

 # then in the shell try
 printenv |fgrep -i java

 # to obtain
 JAVA_HOME=/usr/lib/jvm/java

Details of Apache Tomcat

In /etc/tomcat5/tomcat5.conf, add JAVA_OPTS for UTF support and improving memory management

In /etc/tomcat5/server.xml, insert URIEncoding="UTF-8"

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

In /etc/tomcat5/server.xml, insert in the HOST element the following

<!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface  -->
<Context path="/jspui" docBase="/usr/local/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="/usr/local/dspace/webapps/xmlui" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>

<!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface  -->
<Context path="/oai" docBase="/usr/local/dspace/webapps/oai" debug="0" reloadable="true" cachingAllowed="false" allowLinking="true"/>

To have tomcat5 start as a service

To have tomcat5 start as an ongoing boot-time system service

## The default Tomcat homepage is located at
## $CATALINA_HOME/webapps/ROOT/index.jsp

## To find it use the following commands

# updatedb
# locate index.jsp
/var/lib/tomcat5/webapps/ROOT/index.jsp
/var/lib/tomcat5/webapps/jsp-examples/security/protected/index.jsp

## CATALINA_HOME is at /var/lib/tomcat5
## where it is defined is /etc/tomcat5/tomcat5.conf

# grep -iF catalina_home /etc/tomcat5/tomcat5.conf
CATALINA_HOME="/usr/share/tomcat5"
JAVA_OPTS="$JAVA_OPTS -Dcatalina.ext.dirs=$CATALINA_HOME/shared/lib:$CATALINA_HOME/common/lib"

Details of Postgresql

To locate postgresql.conf

Copy and save the sample configuration file

Edit the file by uncommenting the listen_addresses line, to be sure

listen_addresses = 'localhost'          # what IP address(es) to listen on;
                                        # comma-separated list of addresses;
                                        # defaults to 'localhost', '*' = all

Edit pg_hba.conf to specify method of authentication other than ident

1. make this the first setting

   Panel
   host dspace dspace 127.0.0.1/32 md5

To check the status of the postgresql service

To stop the postgresql service

To start the postgresql service

To have the service start at init boot time

Add dspace user and set environment variables

Add dspace user account

With root user privilege, at the shell prompt, type

 # this locates the adduser(8) command, if it is not already on your PATH
 updatedb
 locate adduser

 # this creates the account
 adduser --create-home dspace

Setting environment variables

Add the following in /home/dspace/.bash_profile..

x='/etc/java/java.conf'
[ -a "$x" ] && source "$x"

x='/etc/tomcat5/tomcat5.conf'
[ -a "$x" ] && source "$x"

export JAVA_HOME

# This value is decided after installing apache maven
export PATH=/usr/local/maven/bin:$PATH

# UNDER CONSTRUCTION
export CLASSPATH=/usr/local/dspace/lib:$CLASSPATH

Add dspace user to postgresql and add database

Login as user postgres, connect to psql as postgres, and create psql role for dspace

Note

1. The username:dspace and password:xxx are used in dspace.cfg below.

Login as user dspace, connect to psql as dspace, and create the dspace database

To reverse the steps and start again

Install packages from source

Install Maven

Download [apache maven|http://maven.apache.org] to /var/tmp, unpack and install to /usr/local

See listing above for dspace user's PATH environment setting.

Create this directory

Put your local proxy settings in the file /home/dspace/.m2/settings.xml, the content is structured as follows

<settings>
<proxies>
<proxy>
<active>true</active>
<protocol>http</protocol>
<!--
<host>put.your.proxy.address.here</host>
<port>put.your.port.number.here</port>
-->
</proxy>
</proxies>
</settings>

Change directory to

From [http://repo1.maven.org/maven2/org/apache/maven/plugins/maven-site-plugin|http://repo1.maven.org/maven2/org/apache/maven/plugins/maven-site-plugin]get [2.0-beta-6/maven-site-plugin-2.0-beta-6.jar|http://repo1.maven.org/maven2/org/apache/maven/plugins/maven-site-plugin/2.0-beta-6/maven-site-plugin-2.0-beta-6.jar]and get [maven-metadata.xml|http://repo1.maven.org/maven2/org/apache/maven/plugins/maven-site-plugin/metadata.xml]but rename maven-metadata.xml as maven-metadata-central.xml and choose the site-plugin version that works best.

Set user dspace as owner

Install DSpace

Create the final target installation directory

From [sourceforge|http://sourceforge.net/projects/dspace/] get dspace-1.5.1-src-release.tar.bz2 or newer. Put download at /var/tmp and unpack to /home/dspace/src

Note

1. get the bz2 or gz package for unix-like platforms to avoid problems associated with line ending conventions and permissions lost in translation for other platforms

   Panel
   cd /var/tmp ls you should have something like dspace-1.5.1-src-release.tar.bz2 mkdir -p /home/dspace/src tar xjf dspace-1.5.1-src-release.tar.bz2 -C /home/dspace/src chown --recursive dspace:dspace /home/dspace/src

   Change to user dspace at /home/dspace/src/ and create LATEST link

   Panel
   su --login dspace cd /home/dspace/src ln -s dspace-MAJOR.MINOR.PATCH-src-release LATEST set your own dspace version number here

Configure dspace.cfg

Change to config directory and make local changes to dspace.cfg

 cd /home/dspace/src/LATEST/dspace/config
 cp dspace.cfg dspace.cfg.original
 vi dspace.cfg

Note

1. see 5.1.1. of 1.6.2 DSpace Manual for description of elements in dspace.cfg
2. compare the default values in ./dspace.cfg with mappings defined in ../pom.xml
3. dspace.dir = /usr/local/dspace
4. dspace.url = [set|set]# dspace.hostname = [set as `hostname --fqdn`|set as `hostname --fqdn`]# dspace.name = Training DSpace at Library of Nineveh
   # db.name = postgres
   # db.username = [set to postgresql createdb credentials|set to postgresql createdb credentials]# db.password = [as above|as above]# mail.server = localhost
   # mail.from.address = [set|set]# feedback.recipient = [set|set]# mail.admin = [set|set]# alert.recipient = [set|set]# registration.notify = [set|set]# default.locale = [set|set]# default.language = [set|set]

   Code Block

   cd /home/dspace/src/LATEST/dspace mvn clean package > /var/tmp/mvn_clean_package_log 2>&1 # to view progress, at another terminal window, use tail /var/tmp/mvn_clean_package_log # at this stage, if there are warnings about missing environment variables # you should refer to the section on setting environment variables above # on completion, you should see [INFO] ------------------------------------------------------------------------ [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 7 minutes 48 seconds [INFO] Finished at: Mon Jan 12 12:35:07 EST 2009 [INFO] Final Memory: 23M/51M [INFO] ------------------------------------------------------------------------ # if the target directory does not exist # go through the mvn_clean_package_log and look for # any lines with the word 'missing' # a network resource could have been unreachable cd /home/dspace/src/LATEST/dspace/target/dspace-1.5.1-build.dir # to initialise and install the database and DSpace ant fresh_install # to create the administrator account cd /usr/local/dspace/bin ls -l create-administrator -rwxrw-r-- 1 dspace dspace 2121 Jan 13 15:45 create-administrator ./create-administrator # you then see ... Creating an initial administrator account E-mail address: [change] First name: [set] Last name: [set] WARNING: Password will appear on-screen. Password: Again to confirm: Is the above data correct? (y or n): y Administrator account created

   Later, after making new changes to dspace.cfg, apply its settings across applications
   by the ant init_configs or install_configs methods, described below, and you
   may need to restart services such as tomcat5 for the settings to really apply

Note

1. See 5.1.1. of 1.6.2. Dspace Manual

   Code Block

   ## in the build target directory, to expose the ant switches $ ant -p Buildfile: build.xml ====================== DSpace platform build file ====================== Common usage: Fresh install, including database setup and registry loading: % ant fresh_install Update existing installation, leaving data and configuration intact: % ant -Dconfig=/installdir/config/dspace.cfg update ======================================================================== Main targets: build_webapps_wars Compress Web Applications into .war files clean_database Removes DSpace database tables, destroying data fresh_install Do a fresh install of the system, overwriting any data load_registries Load initial contents of registries setup_database Create database tables update Update installed code and web applications (without clobber ing data/config) update_code Update installed code (without clobbering data/config) update_webapps Update Web Applications (without clobbering data/config) Default target: help

   Code Block
   when you change DS_SRC/LATEST/dspace/config/dspace.cfg go to DS_SRC/LATEST/dspace/target/dspace-X.Y.Z-build.dir and run '''ant init_configs''' for settings to apply when you change DS_DST/config/dspace.cfg run DS_DST/bin/install_configs for settings to apply for settings to apply across applications you may need to restart processes such as tomcat5

   After you have installed DSpace, one RHEL-provided jar needs to be manually swapped to the one provided by DSpace. If you do not, you will see "javax.mail.NoSuchProviderException" error messages whenever you attempt to send mail from DSpace:

   Code Block
   cd /var/lib/tomcat5/common/lib/ && sudo rm \[javamail\].jar sudo alternatives --install /usr/share/java/javamail.jar javamail /dspace/webapps/xmlui/WEB-INF/lib/mail-1.4.jar 4289 sudo alternatives --config javamail

Connect Tomcat5 and DSpace then TEST

To restart tomcat5

Point your web browser to the setting for dspace.url in dspace.cfg

Redirecting web-server port 80 requests to tomcat servlet

By convention, web-servers listen on port 80 to deliver content such as static html files. So that web browsers can

 ## use the more familiar url
 http://www.dspace-instance.org

 ## instead of....
 http://www.dspace-instance.org:8080/jspui
 http://www.dspace-instance.org:8080/xmlui

• Set Tomcat to serve up DSpace by default

  Code Block
  cd /usr/local/tomcat/webapps ln -s /dspace/webapps/jspui ROOT ## for the Manakin interface replace jspui with xmlui

• Configure /etc/httpd/conf.d/proxy_ajp.conf

  Code Block
  ProxyPass /do_not_touch ! ProxyPass / ajp://localhost:8009/ ProxyPassReverse / ajp://localhost:8009/

  Note:

1. The "!" <bang> sets Apache web-server to NOT REDIRECT everything under /do_not_touch

To be revised

Media Filter for TIFF Files

In order for the filter-media script to generate thumbnails for TIFF images, the Java Advanced Imaging toolkit needs to be installed (Imaging libraries and Image I/O library - jai_codec.jar, jai_core.jar, jai_imageio.jar)

To install the JAI components, download the Java Advanced Imaging API (jre version) and the Java Advanced Imaging - Image I/O Tools from [http://java.sun.com/products/java-media/jai/current.html|http://java.sun.com/products/java-media/jai/current.html].

JAI Imaging API

To install the JRE version for Linux:

cd $JRE ($JRE is the path into your java runtime environment eg: /etc/alternatives/java_sdk_1.5.0/jre)
chmod u+x $downloaddir/jai-1_1_3-lib-linux-$ARCH-jre.bin
$downloaddir/jai-1_1_3-lib-linux-$ARCH-jre.bin

use the space bar to scroll through the licence and answer "yes" (ONLY if you agree of course...).

JAI Image I/O Tools

To install the JRE version for Linux:

• download the zip file eg: I used a stable daily build such as:[http://download.java.net/media/jai-imageio/builds/daily/2008-09-02/jai-imageio-1_2-pre-dr-b04-lib-linux-i586-02_Sep_2008.zip|http://download.java.net/media/jai-imageio/builds/daily/2008-09-02/jai-imageio-1_2-pre-dr-b04-lib-linux-i586-02_Sep_2008.zip]* unzip the I/O tools zip archive
  * copy both of the extracted files (clibwrapper_jiio.jar and jai_imageio.jar) from lib/ext to your $JRE_HOME/lib/ext directory

Cron Jobs

I set up the following scheduled jobs under the dspace crontab:

# send out the subscription e-mails at 01:00 every day
0 1 * * * /dspace/bin/dspace sub-daily >/dev/null 2>&1

# run the media filter at 02:00 every day
0 2 * * * /dspace/bin/dspace filter-media >/dev/null 2>&1

# clean up the DSpace storage tables, 15 minutes prior to running the checksum checker
45 2 * * * /dspace/bin/dspace cleanup >/dev/null 2>&1

# run the checksum checker at 03:00 every day
0 3 * * * /dspace/bin/dspace checker -d2h -p >/dev/null 2>&1

# mail the results to the sysadmin at 06:00 every day
0 6 * * * /dspace/bin/dspace checker-emailer -c >/dev/null 2>&1

# rebuild the index at 01:15 every day
15 1 * * * (cd /dspace && /dspace/bin/dspace index-init && /dspace/bin/dspace index-update) >/dev/null 2>&1

# run the item counter every hour
05 * * * * /dspace/bin/dspace itemcounter >/dev/null 2>&1

# rebuild the sitemap every day
0 6 * * * /dspace/bin/dspace generate-sitemaps >/dev/null 2>&1

# run the embargo lifter every day
15 6 * * * /dspace/bin/dspace embargo-lifter >/dev/null 2>&1

# statistics #

# build general stats every day at 1:30
30 1 * * * /dspace/bin/dspace stat-general >/dev/null 2>&1

# build monthly stats the first day of every month
40 1 1 * * /dspace/bin/dpace stat-monthly >/dev/null 2>&1

# run general stat reports every morning
05 7 * * * /dspace/bin/dspace stat-report-general >/dev/null 2>&1

# run monthly stat reports the first day of every month
10 7 1 * * /dspace/bin/dspace stat-report-monthly >/dev/null 2>

and the following under the root crontab:

#################################################################
#                                                               #
# DSpace cron jobs (the rest are in dspace user's crontab       #
#                                                               #
#################################################################

# Clean up the database nightly at 4.20am
20 4 * * * vacuumdb --analyze dspace > /dev/null 2>&1

# Carry out dspace snapshot at the lowest traffic period of the day
05 5 * * * /root/scripts/dspace_backup.sh

DSpace 1.5.x

This document describes installing DSpace-1.5.1. with Redhat distribution packages which reduce much of the complexity of installation and maintenance for the System Administrator. The products Apache Maven and DSpace are exceptions and are downloaded and installed seperately.

...

1. installing and configuring the pre-requisite packages available from Redhat
2. creating & setting the dspace user and environment
3. installing Maven and DSpace & setting dspace.cfg TO_BE_DONE: package this for distribution
4. and finally, ensuring the ongoing behind the scenes services run & continue to run

...

1. stop tomcat5
2. remove all of DS_DST/*
3. drop the database and database user
4. create the database user and database
5. make changes to dspace.cfg and build DSpace by mvn() and ant()
6. create the DSpace administrator
7. start tomcat5

Install the pre-requisite packages available from Redhat

To install use

Details of Sun Java

To find the files with jvm/jre in the pathname, use

...

 # to cut to the chase.. you may try this in your .bash_profile

 x='/etc/java/java.conf'
 [ -a "$x" ] && source "$x"

 x='/etc/tomcat5/tomcat5.conf'
 [ -a "$x" ] && source "$x"

 export JAVA_HOME

 # then in the shell try
 printenv |fgrep -i java

 # to obtain
 JAVA_HOME=/usr/lib/jvm/java

Details of Apache Tomcat

In /etc/tomcat5/tomcat5.conf, add JAVA_OPTS for UTF support and improving memory management

...

## The default Tomcat homepage is located at
## $CATALINA_HOME/webapps/ROOT/index.jsp

## To find it use the following commands

# updatedb
# locate index.jsp
/var/lib/tomcat5/webapps/ROOT/index.jsp
/var/lib/tomcat5/webapps/jsp-examples/security/protected/index.jsp

## CATALINA_HOME is at /var/lib/tomcat5
## where it is defined is /etc/tomcat5/tomcat5.conf

# grep -iF catalina_home /etc/tomcat5/tomcat5.conf
CATALINA_HOME="/usr/share/tomcat5"
JAVA_OPTS="$JAVA_OPTS -Dcatalina.ext.dirs=$CATALINA_HOME/shared/lib:$CATALINA_HOME/common/lib"

Details of Postgresql

To locate postgresql.conf

...

Add dspace user and set environment variables

Add dspace user account

With root user privilege, at the shell prompt, type

 # this locates the adduser(8) command, if it is not already on your PATH
 updatedb
 locate adduser

 # this creates the account
 adduser --create-home dspace

Setting environment variables

Add the following in /home/dspace/.bash_profile..

x='/etc/java/java.conf'
[ -a "$x" ] && source "$x"

x='/etc/tomcat5/tomcat5.conf'
[ -a "$x" ] && source "$x"

export JAVA_HOME

# This value is decided after installing apache maven
export PATH=/usr/local/maven/bin:$PATH

# UNDER CONSTRUCTION
export CLASSPATH=/usr/local/dspace/lib:$CLASSPATH

Add dspace user to postgresql and add database

Login as user postgres, connect to psql as postgres, and create psql role for dspace

...

Install packages from source

Install Maven

Download apache maven to /var/tmp, unpack and install to /usr/local

...

Install DSpace

Create the final target installation directory

...

Configure dspace.cfg

Change to config directory and make local changes to dspace.cfg

...

 when you change DS_SRC/LATEST/dspace/config/dspace.cfg
 go to DS_SRC/LATEST/dspace/target/dspace-X.Y.Z-build.dir and
 run '''ant init_configs''' for settings to apply

 when you change DS_DST/config/dspace.cfg
 run DS_DST/bin/install_configs for settings to apply

 for settings to apply across applications you may need
 to restart processes such as tomcat5

Connect Tomcat5 and DSpace then TEST

To restart tomcat5

...

Redirecting web-server port 80 requests to tomcat servlet

By convention, web-servers listen on port 80 to deliver content such as static html files. So that web browsers can

...

1. The "!" <bang> sets Apache web-server to NOT REDIRECT everything under /do_not_touch

To be revised

Media Filter for TIFF Files

In order for the filter-media script to generate thumbnails for TIFF images, the Java Advanced Imaging toolkit needs to be installed (Imaging libraries and Image I/O library - jai_codec.jar, jai_core.jar, jai_imageio.jar)

To install the JAI components, download the Java Advanced Imaging API (jre version) and the Java Advanced Imaging - Image I/O Tools from http://java.sun.com/products/java-media/jai/current.html.

JAI Imaging API

To install the JRE version for Linux:

...

use the space bar to scroll through the licence and answer "yes" (ONLY if you agree of course...).

JAI Image I/O Tools

To install the JRE version for Linux:

• download the zip file eg: I used a stable daily build such as:http://download.java.net/media/jai-imageio/builds/daily/2008-09-02/jai-imageio-1_2-pre-dr-b04-lib-linux-i586-02_Sep_2008.zip
• unzip the I/O tools zip archive
• copy both of the extracted files (clibwrapper_jiio.jar and jai_imageio.jar) from lib/ext to your $JRE_HOME/lib/ext directory

Cron Jobs

I set up the following scheduled jobs under the dspace crontab:

...