DSpace installation and upgrade on CentOS Linux (RHEL)

DSpace, LAMS, Mahara and OpenSim install on CentOS

2012-01-18T06:31:00.001-08:00

There are five blogs in this series.

Please select the link below as required:-

DSpace Install Blog

LAMS Install Blog

Mahara Install Blog

OpenSim Install Blog

Server Syncronisation Blog

DSpace 1.8.1 Upgrade Procedure

2012-01-18T06:17:00.000-08:00

Upgrade DSpace from version 1.7.1 to version 1.8.1

Notes

1) The tutorial below records the steps used to upgrade our DSpace instance at Bromley College.

2) The upgrade process involves building DSpace from source because we use a custom hierarchical authentication module at Bromley.

This tutorial assumes you are initially logged in as user dspace

Just to be on the safe side take a backup of the database:

cd
pg_dump -U dspace -f /home/dspace/dspace_backup_180112 dspace

Download and unpack the source code:

lynx http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.8.1/
tar -xzvf /home/dspace/dspace-1.8.1-src-release.tar.gz

Stop Tomcat and the handle server:

su - root
service tomcat stop
service handle stop (n/a with standbyvle test server)
exit

Apply the Bromley College customisations to the file LDAPHierarchicalAuthentication.java

Replace the getSpecialGroups code with the customised version (this is specifically for our installation):

nano /home/dspace/dspace-1.8.1-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Copy over the stylesheets and the Bromley College logo from version 1.7.1:

cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

Build DSpace (note can take up to 15 minutes):

cd /home/dspace/dspace-1.8.1-src-release
mvn -U clean package

With the move from DSpace 1.7.x to 1.8.x there have been major changes to the configuration files. Many of the directives that used to be in the dspace.cfg file have now been put into separate configuration files in the /home/dspace/config/modules directory. Note that these new files will not be present until after ant has been run to update DSpace.

The first step is to backup the old dspace.cfg file and obtain a clean copy of the new dspace.cfg file:

cp /home/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg.1.7.1
cp /home/dspace/dspace-1.8.1-src-release/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg.1.8.1

Enter custom settings into dspace.cfg.1.8.1 and then overwrite dspace.cfg. Note that the diff command can be very useful in comparing old and new configuration files:

diff /home/dspace/config/dspace.cfg.1.7.1 /home/dspace/config/dspace.cfg.1.8.1
nano /home/dspace/config/dspace.cfg.1.8.1
cp /home/dspace/config/dspace.cfg.1.8.1 /home/dspace/config/dspace.cfg

Update DSpace:

cd /home/dspace/dspace-1.8.1-src-release/dspace/target/dspace-1.8.1-build
ant -Dconfig=/home/dspace/config/dspace.cfg update

The new configuration files will have now appeared in the /home/dspace/config/modules directory. It is now necessary to compare these new files with the appropriate sections in the old dspace.cfg file and modify the directives in the new files appropriately.

Note: I particularly ran into problems here with the path to the solr statistics server as our installation of DSpace is on a Tomcat server with non standard port allocations and is behind Apache. The path I ended up using in the solr-statistics.cfg and discovery.cfg configuration files in the config/modules directory was http://127.0.0.1/solr/statistics

The database schema has changed slightly between DSpace 1.7.1 and 1.8.1 so it is necessary to run the following upgrade script:

psql -U dspace -f dspace-1.8.1-src-release/dspace/etc/postgres/database_schema_17-18.sql dspace

Run the following scripts to clean up and re-index the site:

cd /home/dspace/bin
dspace cleanup
dspace index-init
dspace filter-media

As the root user, start Tomcat and the handle server. Restart Apache and it works :)

su - root
service tomcat start
service handle start
service httpd restart
exit

Just to make sure view the source code of the DSpace homepage, where the metadata will confirm the new version number:

meta name="Generator" content="DSpace 1.8.1

Running the following script updates any old statistics files to work with DSpace 1.8.x

dspace stats-util -b -r

Making subsequent configuration changes

If any configuration changes to source files or jsp files need to be made it is necessary to use the -Doverwrite=false switch with ant to prevent the existing customised configuration files being overwritten. Typical commands are shown below:

cd /home/dspace/dspace-1.8.1-src-release
mvn -U clean package
cd /home/dspace/dspace-1.8.1-src-release/dspace/target/dspace-1.8.1-build
ant -Dconfig=/home/dspace/config/dspace.cfg -Doverwrite=false update

DSpace 1.7.1 Upgrade Procedure

2011-04-07T01:33:00.000-07:00

Upgrade DSpace to version 1.7.1

Note that this upgrade process involves building DSpace from source because we use a custom hierarchical authentication module at Bromley.

Login as user dspace and download the source code:

cd
lynx http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.7.1/

unpack the source and change to the src directory:
tar -xzvf dspace-1.7.1-src-release.tar.gz
cd dspace-1.7.1-src-release

Stop Tomcat and the handle server:

su - root
service tomcat stop
service handle stop (n/a with standbyvle test server)
exit

Apply the Bromley College customisations to the file LDAPHierarchicalAuthentication.java.

Replace the getSpecialGroups code with the customised version (this is specifically for our installation)

nano /home/dspace/dspace-1.7.1-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Copy over the stylesheets and the Bromley College logo from version 1.7.0:

cp /home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp
/home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp

cp /home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp
/home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp

cp /home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp
/home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp

cp /home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp
/home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp

cp /home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif
/home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

cp /home/dspace/dspace-1.7.0-src-release/dspace/config/dspace.cfg
/home/dspace/dspace-1.7.1-src-release/dspace/config/dspace.cfg

cp /home/dspace/dspace-1.7.1-src-release/dspace/config/dspace.cfg
/home/dspace/config/dspace.cfg

Build DSpace (note can take up to 15 minutes):

cd
cd dspace-1.7.1-src-release/dspace
mvn -U clean package

Update DSpace:

cd /home/dspace/dspace-1.7.1-src-release/dspace/target/dspace-1.7.1-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

Generate the browse and search indexes:

/home/dspace/bin/dspace index-init

As the root user, start Tomcat and the handle server. Restart Apache and it works :)

su - root
service tomcat stop
service tomcat start
service handle start
service httpd restart
exit

Just to make sure I viewed the source code of the DSpace homepage, where the metadata confirmed the new version number:

meta name="Generator" content="DSpace 1.7.1"

DSpace 1.7.0 Upgrade Procedure

2010-12-31T03:34:00.000-08:00

This blog covers the upgrade procedure from DSpace 1.6.2 to DSpace 1.7.0 under CentOS 5.5 Linux

i) Upgrade Apache-Maven

First upgrade apache-maven to the latest version available:

login as root

cd /usr/local/apache-maven/
lynx http://maven.apache.org/download.html
tar -xzvf apache-maven-3.0.1-bin.tar.gz

nano /etc/profile

Change the M2_HOME variable to point to the new installation of maven:
M2_HOME=/usr/local/apache-maven/apache-maven-3.0.1

Logout and log back in again.
Check the version of maven installed:

mvn --version
Apache Maven 3.0.1 (r1038046; 2010-11-23 10:58:32+0000)
Java version: 1.6.0_13
Java home: /usr/java/jdk1.6.0_13/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux" version: "2.6.18-92.el5xen" arch: "i386" Family: "unix"

ii) Upgrade PostgreSQL

It is necessary to upgrade PostgreSQL from the default version of 8.1.22 as provided with CentOS 5.5 to PostgreSQL version 8.4.5. This is because DSpace 1.7.0 will only work with versions of PostgreSQL above 8.2

The process used to successfully upgrade PostgreSQL is given below:

Log in as the root user.

Obtain the compat-postgresql-libs-4-1PGDG.rhel5.i686.rpm package. After quite a bit of searching I found it on the Web and downloaded it to our cd server, to ensure it was available in future.

I downloaded the compat-postgresql-libs-4-1PGDG.rhel5.i686.rpm package from the cd server onto our test server and installed it as follows:

lynx http://cd.bromley.ac.uk/compat-postgresql-libs-4-1PGDG.rhel5.i686.rpm
rpm -iv --replacefiles compat-postgresql-libs-4-1PGDG.rhel5.i686.rpm

If the above step is missed out removing the old version of postgresql will also strip out a lot of vital system packages!

Remove the old version of PostgreSQL and install the new version:

mkdir /pgbak
chown postgres:postgres /pgbak
su - postgres
pg_dumpall > /pgbak/backup.sql
exit
service postgresql stop
cp /var/lib/pgsql/data/pg_hba.conf /pgbak
mv /var/lib/pgsql/data /pgbak
yum remove postgresql*
yum install postgresql84-server
/etc/init.d/postgresql initdb
cp /pgbak/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf
chkconfig --level 35 postgresql on
service postgresql start
su - postgres
psql -f /pgbak/backup.sql postgres
vacuumdb -a -z
exit

And just to make sure:

rpm -qa | grep postgresql
postgresql84-server-8.4.5-1.el5_5.1
postgresql84-libs-8.4.5-1.el5_5.1
compat-postgresql-libs-4-1PGDG.rhel5
postgresql84-8.4.5-1.el5_5.1

iii) Upgrade DSpace to version 1.7.0

Note that this upgrade process involves building DSpace from source because we use a custom hierarchical authentication module at Bromley.

su to user dspace
download the source code:
lynx http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.7.0/

unpack the source and change to the src directory:
tar -xzvf dspace-1.7.0-src-release.tar.gz
cd dspace-1.7.0-src-release

Stop Tomcat and the handle server:

su - root
service tomcat stop
service handle stop (n/a with standbyvle test server)
exit

Apply the Bromley College customisations to the following default files:

Replace the getSpecialGroups code with the customised version (this is
specifically for our installation)

nano /home/dspace/dspace-1.7.0-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Copy over the stylesheets and the Bromley College logo from version 1.6.2:

cp /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp
/home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp

cp /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp
/home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp

cp /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp
/home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp

cp /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp
/home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp

cp /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif
/home/dspace/dspace-1.7.0-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

With reference to dspace.cfg for the 1.6.2 build, apply the Bromley
College customisations to the default dspace.cfg.

nano /home/dspace/dspace-1.7.0-src-release/dspace/config/dspace.cfg
cp /home/dspace/dspace-1.7.0-src-release/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg

Build DSpace (note can take up to 15 minutes):

cd
cd dspace-1.7.0-src-release/dspace
mvn -U clean package

Update DSpace:

cd /home/dspace/dspace-1.7.0-src-release/dspace/target/dspace-1.7.0-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

Apply the database update script:

psql -U dspace -f /home/dspace/dspace-1.7.0-src-release/dspace/etc/postgres/database_schema_16-17.sql dspace

Generate the browse and search indexes:

/home/dspace/bin/dspace index-init

As the root user, start Tomcat and the handle server. Restart Apache and it works :)

su - root
service tomcat stop
service tomcat start
service handle start
service httpd restart
exit

Later I noticed that the thumbnail images weren't being displayed for newly uploaded image files. After a bit of investigation I found I'd omitted updating the dspace crontab with the latest settings. The settings now in use are shown below:

# Send out subscription e-mails at 01:00 every day
0 1 * * * /home/dspace/bin/dspace sub-daily
# Run the media filter at 02:00 every day
0 2 * * * /home/dspace/bin/dspace filter-media
# Run the checksum checker at 03:00
0 3 * * * /home/dspace/bin/dspace checker -lp
# Mail the results to the sysadmin at 04:00
0 4 * * * /home/dspace/bin/dspace dsrun org.dspace.checker.DailyReportEmailer -c
# Run stat analyses
0 1 * * * /home/dspace/bin/dspace stat-general
0 1 * * * /home/dspace/bin/dspace stat-monthly
0 2 * * * /home/dspace/bin/dspace stat-report-general
0 2 * * * /home/dspace/bin/dspace stat-report-monthly
20 4 * * * cd /home/dspace/vacuumdb && ( PGPASSWORD=`cat .pgpass` /usr/bin/vacuumdb --analyze -v -h 127.0.0.1 -U dspace dspace )

DSpace 1.6.2 Upgrade Procedure

2010-08-03T02:29:00.000-07:00

Upgrade to DSpace 1.6.2

This blog covers the upgrade procedure from DSpace 1.5.2 to DSpace 1.6.2 under CentOS 5.3 Linux

Login as user dspace and download and untar the source distribution:

lynx http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.6.2/dspace-1.6.2-src-release.tar.gz/download
tar -xzvf dspace-1.6.2-src-release.tar.gz

Stop Tomcat and the handle server:

su - root
service tomcat stop
service handle stop

In DSpace 1.6.2 the new solr statistics feature is provided. This works in addition to the existing statistics and provides content specific statistics on Communities, Collections and Items. It is worth maintaining both old and new statistics reporting at this stage as the old system provides an repository wide overview, whilst the new system is much more specific.

The solr Webserver is already provided with DSpace 1.6.2. However with our implementation of tomcat running behind Apache using mod_jk two additional steps needed to be taken to enable access to solr.

Statistics Step 1 (as root)

cd /etc/httpd/conf.d
nano jk.conf

Append the following text:

#
JkMount /solr worker2
#
JkMount /solr/* worker2

Save jk.conf
exit

Statistics Step 2 (as dspace)

cd /home/dspace/apache-tomcat-6.0.18/conf
nano server.xml

Add the following text:

[!-- DEFINE A CONTEXT PATH FOR DSpace Solr Statistics Interface --]
[Context path="/solr" docBase="/home/dspace/webapps/solr" debug="0"
reloadable="true" cachingAllowed="false"
allowLinking="true"/]

Note that the HTML braces above have been replaced by [] for display purposes just within this blog.

As of 8th August 2010 there is a patch missing from the DSpace 1.6.2 source code. This results in the issue date being wrongly displayed. The process for correcting this is explained below:

cd
nano DCDate.patch

Cut and paste the patch file text below (derived from http://jira.dspace.org/jira/browse/DS-469) into the text file DCDate.patch:

Index: dspace-api/src/main/java/org/dspace/content/DCDate.java
===================================================================
--- dspace-api/src/main/java/org/dspace/content/DCDate.java (revision 4697)
+++ dspace-api/src/main/java/org/dspace/content/DCDate.java (working copy)
@@ -639,9 +639,9 @@
dd.getHourGMT(), dd.getMinuteGMT(), dd.getSecondGMT());
}
}
- else if (granularity == DateGran.DAY)
+ else if (granularity == DateGran.YEAR)
{
- return String.format("%d-%s-%4d", dd.getDay(), monthName, dd.getYear());
+ return String.format("%4d", dd.getYear());
}
else if (granularity == DateGran.MONTH)
{
@@ -649,7 +649,7 @@
}
else
{
- return String.format("%4d", dd.getYear());
+ return String.format("%d-%s-%4d", dd.getDay(), monthName, dd.getYear());
}
}
}

Save the file DCDate.patch
Use the following command to apply the above patch:

patch /home/dspace/dspace-1.6.2-src-release/dspace-api/src/main/java/org/dspace/content/DCDate.java DCDate.patch

With reference to the source code files in the DSpace 1.5.2 build, apply the Bromley College customisations to the following default files:

Replace the getSpecialGroups code with the customised version (this is specifically for our installation)

nano /home/dspace/dspace-1.6.2-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Customise the stylesheets:

nano /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp

nano /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp

nano /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp

nano /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp

Also copy over the College logo from the 1.5.2 build:

cp /home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif /home/dspace/dspace-1.6.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

With reference to dspace.cfg for the 1.5.2 build, apply the Bromley College customisations to the default dspace.cfg. Also check out the new solr statistics section in dspace.cfg and append the following lines to the solr statistics section of dspace.cfg:

# Added by Clive Gould on 8th August 2010
statistics.items.dc.1=dc.identifier
statistics.items.dc.2=dc.date.accessioned
statistics.items.type.1=dcinput
statistics.items.type.2=date
statistics.default.start.datepick = 01/01/1977

nano /home/dspace/dspace-1.6.2-src-release/dspace/config/dspace.cfg
cp /home/dspace/dspace-1.6.2-src-release/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg

Build DSpace (note this takes about 5 minutes):

cd
cd dspace-1.6.2-src-release/dspace
mvn -U clean package

Update DSpace:

cd /home/dspace/dspace-1.6.2-src-release/dspace/target/dspace-1.6.2-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

Apply the bitstream fix:

/home/dspace/bin/dspace registry-loader -bitstream /home/dspace/etc/upgrades/15-16/new-bitstream-formats.xml

Apply the database update script:

psql -U dspace -f /home/dspace/dspace-1.6.2-src-release/dspace/etc/postgres/database_schema_15-16.sql dspace

The webapps folder is already pathed from tomcat's server.xml so it is not necessary to copy the files over.

Generate the browse and search indexes:

/home/dspace/bin/dspace index-init

Start Tomcat:

su - root
service tomcat start
service handle start
service httpd restart
exit

On testing it appears that DSpace 1.6.2 works fine with both oai and handle requests

The old statistics files can be imported into DSpace and there is an excellent tutorial on this subject on the following site: http://ir.sun.ac.za/wiki/index.php/Asset_Statistics

DSpace 1.5.2 installation procedure on CentOS 5.3

2009-04-08T01:05:00.001-07:00

I have just complete a clean install of DSpace 1.5.2 on a CentOS 5.3 box.

Here is the installation process I followed:

Login as the root user and download dspace to /root:
lynx http://sourceforge.net/project/showfiles.php?group_id=19984%20%20

Create an account for the dspace user:
useradd dspace
passwd dspace

I have already installed the JDK on this server during the LAMS install. For details please select this link

Download and install maven and ant:
cd /root
lynx http://maven.apache.org/download.html
mkdir /usr/local/apache-maven
mv apache-maven-2.1.0-bin.tar.gz /usr/local/apache-maven/
cd /usr/local/apache-maven
tar -xzvf apache-maven-2.1.0-bin.tar.gz
cd /usr/local
lynx http://ant.apache.org/bindownload.cgi
mv /root/apache-ant-1.7.1-bin.tar.gz .
tar -xzvf apache-ant-1.7.1-bin.tar.gz

Add paths to /etc/profile:
nano /etc/profile

Add the following:
M2_HOME=/usr/local/apache-maven/apache-maven-2.1.0
export M2_HOME
MAVEN_OPTS="-Xms256m -Xmx512m"
export MAVEN_OPTS
M2=$M2_HOME/bin
export M2
PATH=${PATH}:${M2}
ANT_HOME=/usr/local/apache-ant-1.7.1
export ANT_HOME
PATH=${PATH}:${ANT_HOME}/bin
export PATH

Logout and log back in again so that the environment variables from /etc/profile are applied.

Check that maven and ant are installed:

mvn --version
Apache Maven 2.1.0 (r755702; 2009-03-18 19:10:27+0000)
Java version: 1.6.0_13
Java home: /usr/java/jdk1.6.0_13/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "linux" version: "2.6.18-92.1.22.el5xen" arch: "i386" Family: "unix"

ant -version
Apache Ant version 1.7.1 compiled on June 27 2008

Install the postgresql database and configure postgresql:

yum install postgresql postgresql-server
chkconfig --level 2345 postgresql on
service postgresql start

nano /var/lib/pgsql/data/postgresql.conf
For 8.0+, in
postgresql.conf uncomment the line starting:
listen_addresses = 'localhost'
#---------------------------------------------------------------------------
# CONNECTIONS AND AUTHENTICATION
#---------------------------------------------------------------------------
# - Connection Settings -
listen_addresses = 'localhost' # what IP address(es) to listen on;
# comma-separated list of addresses;
# defaults to 'localhost', '*' = all

nano /var/lib/pgsql/data/pg_hba.conf

Then don't tighten up security a bit by editing
pg_hba.conf as the default file is already too restrictive to allow creation of the dspace database. Just enter the following contents into the actual configuration section of the file and delete everything else from this section.

# TYPE DATABASE USER CIDR-ADDRESS METHOD
# "local" is for Unix domain socket connections only
local all all trust

Check the databases already present:
su - postgres
-bash-3.2$ psql -l
List of databases
Name | Owner | Encoding
-----------+----------+----------
postgres | postgres | UTF8
template0 | postgres | UTF8
template1 | postgres | UTF8
(3 rows)

Create the user and database:
-bash-3.2$ createuser -U postgres -d -A -P dspace
Enter password for new role: XXXX
Enter it again: XXXX
Shall the new role be allowed to create more new roles? (y/n) n
CREATE ROLE
-bash-3.2$ createdb -U dspace -E UNICODE dspace
CREATE DATABASE

-bash-3.2$ psql -l
List of databases
Name | Owner | Encoding
-----------+----------+----------
dspace | dspace | UTF8
postgres | postgres | UTF8
template0 | postgres | UTF8
template1 | postgres | UTF8

service postgresql stop
Stopping postgresql service: [ OK ]
service postgresql start
Starting postgresql service: [ OK ]

nmap 127.0.0.1
Starting Nmap 4.11 ( http://www.insecure.org/nmap/ ) at 2009-04-10 08:47 BST
Interesting ports on localhost.localdomain (127.0.0.1):
Not shown: 1667 closed ports
PORT STATE SERVICE
25/tcp open smtp
80/tcp open http
443/tcp open https
631/tcp open ipp
3306/tcp open mysql
4444/tcp open krb524
5432/tcp open postgres
5801/tcp open vnc-http-1
5901/tcp open vnc-1
6001/tcp open X11:1
8009/tcp open ajp13
8080/tcp open http-proxy
9090/tcp open zeus-admin
Nmap finished: 1 IP address (1 host up) scanned in 0.120 seconds

As the root user, download and install Tomcat:

cd /root
lynx http://tomcat.apache.org/download-60.cgi
cp apache-tomcat-6.0.18.tar.gz /home/dspace
cd /home/dspace
chown dspace:dspace apache-tomcat-6.0.18.tar.gz
su - dspace
tar -xzvf apache-tomcat-6.0.18.tar.gz
exit

nano /etc/profile
and append the following lines:

JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"
export JAVA_OPTS

Here I tell DSpace/Tomcat to listen on port 8081 and AJP connector port 8010 (I have to do this as JBoss Tomcat used with LAMS is already listening on 8080 and 8009):

su - dspace
rm -rf apache-tomcat-6.0.18.tar.gz
cd apache-tomcat-6.0.18/conf
nano server.xml
In server.xl change any references to port 8080 to port 8081 and any references for port 8009 to port 8010.

cd /home/dspace/apache-tomcat-6.0.18/bin
./startup.sh
Using CATALINA_BASE: /home/dspace/apache-tomcat-6.0.18
Using CATALINA_HOME: /home/dspace/apache-tomcat-6.0.18
Using CATALINA_TMPDIR: /home/dspace/apache-tomcat-6.0.18/temp
Using JRE_HOME: /usr/java/jdk1.6.0_13

Just to confirm that DSpace/Tomcat is listening on port 8081:

nmap 127.0.0.1
Starting Nmap 4.11 ( http://www.insecure.org/nmap/ ) at 2009-04-11 17:08 BST
Interesting ports on localhost.localdomain (127.0.0.1):
Not shown: 1666 closed ports
PORT STATE SERVICE
25/tcp open smtp
80/tcp open http
443/tcp open https
631/tcp open ipp
3306/tcp open mysql
4444/tcp open krb524
5432/tcp open postgres
5801/tcp open vnc-http-1
5901/tcp open vnc-1
6001/tcp open X11:1
8009/tcp open ajp13
8080/tcp open http-proxy
8081/tcp open blackice-icecap
9090/tcp open zeus-admin

./shutdown.sh
Using CATALINA_BASE: /home/dspace/apache-tomcat-6.0.18
Using CATALINA_HOME: /home/dspace/apache-tomcat-6.0.18
Using CATALINA_TMPDIR: /home/dspace/apache-tomcat-6.0.18/temp
Using JRE_HOME: /usr/java/jdk1.6.0_13

Now install DSpace:

su - root
cd /root
cp dspace-1.5.2-release.tar.gz /home/dspace
cd /home/dspace
chown dspace:dspace dspace-1.5.2-release.tar.gz
exit

tar -xzvf dspace-1.5.2-release.tar.gz
cd dspace-1.5.2-release/dspace/config
nano dspace.cfg

The configuration settings shown below in dspace.cfg are just the settings I either changed or uncommented in the default file:

dspace.dir = /home/dspace
dspace.url = http://vleinternal.bromley.ac.uk/jspui
dspace.hostname = vleinternal.bromley.ac.uk
dspace.name = DSpace for eLearning Evaluation at Bromley College
db.name = postgres
db.url = jdbc:postgresql://localhost:5432/dspace
db.driver = org.postgresql.Driver
db.username = dspace
db.password = XXXX
mail.server=vleinternal.bromley.ac.uk
mail.from.address = dspace-noreply@vleinternal.bromley.ac.uk
feedback.recipient = dspace-help@vleinternal.bromley.ac.uk
mail.admin = dspace-help@vleinternal.bromley.ac.uk
default.language = en_GB

cd..
mvn package
A lot of information now appears on the screen. Below are shown the last lines confirming success:
[INFO] Copying 861 files to /home/dspace/dspace-1.5.2-release/dspace/target/dspace-1.5.2-build.dir
[INFO]
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] DSpace Addon Modules .................................. SUCCESS [30.453s]
[INFO] DSpace XML-UI (Manakin) :: Web Application ............ SUCCESS [1:14.611s]
[INFO] DSpace LNI :: Web Application ......................... SUCCESS [10.261s]
[INFO] DSpace OAI :: Web Application ......................... SUCCESS [6.427s]
[INFO] DSpace JSP-UI :: Web Application ...................... SUCCESS [8.017s]
[INFO] DSpace SWORD :: Web Application ....................... SUCCESS [5.869s]
[INFO] DSpace Assembly and Configuration ..................... SUCCESS [43.018s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 minutes 59 seconds
[INFO] Finished at: Sun Apr 12 07:40:07 BST 2009
[INFO] Final Memory: 25M/255M
[INFO] ------------------------------------------------------------------------

exit

Now to set up postgresql to allow access to the dspace database:
nano /var/lib/pgsql/data/pg_hba.conf
Add the following line to end of the file:

host dspace dspace 127.0.0.1 255.255.255.255 md5

service postgresql restart

su - dspace
cd /home/dspace/dspace-1.5.2-release/dspace/target/dspace-1.5.2-build.dir
ant fresh_install
A lot of information now appears on the screen. Below are shown the last lines confirming success:
[echo] ====================================================================
[echo] The DSpace code has been installed, and the database initialized.
[echo]
[echo] To complete installation, you should do the following:
[echo]
[echo] * Setup your Web servlet container (e.g. Tomcat) to look for your
[echo] DSpace web applications in: /home/dspace/webapps/
[echo]
[echo] OR, copy any web applications from /home/dspace/webapps/ to
[echo] the appropriate place for your servlet container.
[echo] (e.g. '$CATALINA_HOME/webapps' for Tomcat)
[echo]
[echo] * Make an initial administrator account (an e-person) in DSpace:
[echo]
[echo] /home/dspace/bin/create-administrator
[echo]
[echo] * Start up your servlet container (Tomcat etc.)
[echo]
[echo] You should then be able to access your DSpace's 'home page':
[echo]
[echo] http://vleinternal.bromley.ac.uk/dspace
[echo]
[echo] You should also be able to access the administrator UI:
[echo]
[echo] http://vleinternal.bromley.ac.uk/dspace/dspace-admin
[echo] ====================================================================
[echo]
BUILD SUCCESSFUL

cd /home/dspace/apache-tomcat-6.0.18/conf
nano server.xml and add the following to the end of the host section:
Note that the standard html opening and closing tag braces have been replaced by {} in this blog purely for display purposes.

{!-- DEFINE A CONTEXT PATH FOR DSpace JSP User Interface --}
{Context path="/jspui" docBase="/home/dspace/webapps/jspui" debug="0"
reloadable="true" cachingAllowed="false"
allowLinking="true"/}
{!-- DEFINE A CONTEXT PATH FOR DSpace OAI User Interface --}
{Context path="/oai" docBase="/home/dspace/webapps/oai" debug="0"
reloadable="true" cachingAllowed="false"
allowLinking="true"/}

cd /home/dspace/bin
./create-administrator

/home/dspace/apache-tomcat-6.0.18/bin
./shutdown.sh
./startup.sh

Now visit http://127.0.0.1:8081/jspui from the browser and it works !!!!!!

Now set up the crontab for dspace:
crontab -e
no crontab for dspace - using an empty one

# Send out subscription e-mails at 01:00 every day
0 1 * * * /home/dspace/bin/sub-daily
# Run the media filter at 02:00 every day
0 2 * * * /home/dspace/bin/filter-media
# Run the checksum checker at 03:00
0 3 * * * /home/dspace/bin/checker -lp
# Mail the results to the sysadmin at 04:00
0 4 * * * /home/dspace/bin/dsrun org.dspace.checker.DailyReportEmailer -c
# Run stat analyses
0 1 * * * /home/dspace/bin/stat-general
0 1 * * * /home/dspace/bin/stat-monthly
0 2 * * * /home/dspace/bin/stat-report-general
0 2 * * * /home/dspace/bin/stat-report-monthly
20 4 * * * cd /home/dspace/vacuumdb && ( PGPASSWORD=`cat .pgpass` /usr/bin/vacuumdb --analyze -v -h 127.0.0.1 -U dspace dspace )

cd /home/dspace
mkdir vacuumdb
cd vacuumdb/
nano .pgpass
chmod 600 .pgpass
exit

Getting DSpace Tomcat to work behind Apache using mod_jk turned out to be relatively straightforward. LAMS was already working behind mod_jk. For more information on installing mod_jk please select this link.

cd /etc/httpd/conf
nano workers.properties
and add/amend the following lines:

# workers.tomcat_home=/usr/lib/apache-tomcat
# workers.java_home=/usr/lib/jdk
ps=/
worker.list=worker1,worker2
worker.worker1.port=8009
worker.worker2.port=8010
worker.default.host=localhost
worker.default.type=ajp13
worker.default.lbfactor=1

cd /etc/httpd/conf.d
nano jk.conf
and add/amend the following lines:

#
# Mod_jk2 allows the Apache Web server to connect to application
# servers using the AJP protocol. This allows web applications to
# be integrated seamlessly into your Apache server's URI space and
# utilize Apache features such as SSL processing.
#
LoadModule jk_module modules/mod_jk.so
#
# mod_jk is configured in /etc/httpd/conf/workers.properties
#
# Where to find workers.properties
JkWorkersFile /etc/httpd/conf/workers.properties
# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel info
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send servlet for context /lams to worker named worker1
JkMount /lams worker1
# Send JSPs for context /lams/* to worker named worker1
JkMount /lams/* worker1
#
JkMount /upload/* worker1
#
JkMount /jmx-console/* worker1
#
JkMount /jspui worker2
#
JkMount /jspui/* worker2
#
JkMount /oai worker2
#
JkMount /oai/* worker2

Restart apache and DSpace is now available on the URL http://vleinternal.bromley.ac.uk/jspui/

Now create a script to antomatically start and stop tomcat.

nano /etc/init.d/tomcat
#!/bin/sh
#
# description: Tomcat
#
# Shell script to to start/stop Tomcat
#
# Set Enviroment Variables and Paths
#
JAVA_HOME=JAVA_HOME=/usr/java/jdk1.6.0_13; export JAVA_HOME
CATALINA_HOME=/home/dspace/apache-tomcat-6.0.18/; export CATALINA_HOME
PATH=${PATH}:${JAVA_HOME}/jre/bin; export PATH
#
case "$1" in
start)
#
# Start Tomcat
#
echo
sudo -u dspace /home/dspace/apache-tomcat-6.0.18/bin/startup.sh
;;
stop)
#
# Stop Tomcat
#
sudo -u dspace /home/dspace/apache-tomcat-6.0.18/bin/shutdown.sh
;;
*)
echo "Usage service tomcat start/stop"
exit 1;;
esac

chmod 755 tomcat
service tomcat stop
service tomcat start

I found with CentOS 5 that Tomcat was failing to start on boot and I was getting the following error in the logs :

sudo: sorry, you must have a tty to run sudo

The solution turned out to be very simple. I used the visudo command to edit sudo's configuration file and juts commented out the line

Defaults requiretty

Getting LDAP access to Active Directory working

Now that DSpace is successfully running the next step is to configure LDAP access to Active Directory.

In order to help with this download and install the JAVA based lDAP browser, JXplorer This will help you test your connection with Active Directory and discover the additional settings you need to include in dspace.cfg

Open the GUI in Linux as a user and within a terminal window enter the following commands:

lynx http://www.jxplorer.org/
unzip JXv3.2rc2deploy.zip
cd Desktop
cd jxplorer/
chmod 755 jxplorer.sh
./jxplorer.sh

JXplorer will now open in a window on your desktop. Click on the "connect" icon and fill in the settings for Active Directory access. You will need to have a bind user already set up in AD, who has permissions to browse the AD tree. The format of the User DN that worked for me was bindusername@bromley.local, but this very much depends on your AD structure. I left the Base DN dialog box empty and was then able to browse and search the entire LDAP tree.

It can also be helpful to use the command line LDAP client ldapsearch to investigate connection options. This can be installed from a root login as follows:

cd /etc/openldap
nano ldap.conf

Add entries for BASE and HOST to the file.

It is then necessary to install openldap as follows:

yum install openldap
yum install openldap-clients

The command using the following syntax allowed me to search our AD structure:

ldapsearch -x -v -D "bindusername@bromley.local" -W -L "cn=Clive Gould"
ldap_initialize( )
Enter LDAP Password:

The LDAP Password required is the one for the binduser in AD and the results of the search were successfully displayed for the AD account Clive Gould.

Once you have used one, or both, of the above techniques to verify AD connection settings and structure DSpace can now be configured.

The configuration settings shown below in dspace.cfg are the settings I changed in the default file in order to get LDAP authentication working for us:

Please note that this was the version of dspace.cfg stored in the /home/dspace/config folder.

#### Stackable Authentication Methods #####

# Stack of authentication methods
# (See org.dspace.authenticate.AuthenticationManager)
# Example:
# plugin.sequence.org.dspace.authenticate.AuthenticationMethod = \
# org.dspace.authenticate.ShibAuthentication, \
# org.dspace.authenticate.PasswordAuthentication

# Next two lines added by Clive Gould on 22/04/09 to allow AD Authentication

plugin.sequence.org.dspace.authenticate.AuthenticationMethod = \
org.dspace.authenticate.LDAPHierarchicalAuthentication

#### LDAP Authentication Configuration Settings ####

ldap.enable = true
ldap.provider_url = ldap://10.100.0.2:3268/
ldap.id_field = sAMAccountName
ldap.object_context = dc=bromley,dc=local
ldap.search_context = dc=bromley,dc=local
ldap.email_field = mail
ldap.surname_field = sn
ldap.givenname_field = givenName
webui.ldap.autoregister = true
ldap.login.specialgroup = Authenticated
ldap.search_scope = 2
ldap.search.user = bindusername@bromley.local
ldap.search.password = YYYYYYYY

Where the ldap.search.password is the password for the binduser in AD. Please note that the syntax of the line containing the ldap.provider_url was critical to getting LDAP authentication working for me, especially the / after the port number!

It was then necessary to rebuild DSpace as follows:

cd dspace-1.5.2-release/dspace/
mvn package
cd /home/dspace/dspace-1.5.2-release/dspace/target/dspace-1.5.2-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

On restarting Tomcat as root I found I could then login to DSpace using my normal AD username and password. My user profile in DSpace was automatically completed by using my details from my AD account.

I found I could not login using my original DSpace administrator account as direct password-login was now disabled. I had to run the create-administrator script again to add my new "AD" indentity to the list of DSpace administrators.

Another problem, which was solved thanks to a reply to a DSpace tech-lists posting was to do with the ldap.login.specialgroup - When logged in as DSpace administrator and visiting the Groups option I expected to see users who logged on added automatically to the Authenticated group. Stuart Lewis and Flavio Botelho kindly replied to my posting and explained that this was a "special" group.

"This means that users are not added to it as such, but are transient members of it during the period that they are logged in. Therefore you will not see anyone listed in that group, however such users should inherit the permissions of belonging to that group." Stuart Lewis

I subsequently noticed that the feedabck form on the DSpace homepage was producing an internal error when a user tried to submit a message. This was because email was undeliverable to dspace-help and dspace-noreply. The solution from a root login was as follows:

nano /etc/aliases

append the following lines to the file:

dspace-help: clive@somewhere.com
dspace-noreply: clive@somewhere.com

and run the newaliases command:

newaliases
/etc/aliases: 79 aliases, longest 16 bytes, 842 bytes total

Differentiating between student and staff login to DSpace

In order to control access to collections we needed to be able to differentiate between authorised staff and student login.

Stuart Lewis very kindly provided a patch that allowed staff logging in to be automatically added to an all-staff special group and students logging in to be automatically added to an all-students special group.

As user dspace, download the src release of dspace 1.5.2 into /home/dspace and extract it.

lynx http://sourceforge.net/project/showfiles.php?group_id=19984%20%20
tar -xzvf dspace-1.5.2-src-release.tar.gz

Edit the file LDAPHierarchicalAuthentication.java, which controls special groups

nano /home/dspace/dspace-1.5.2-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Replace the existing section of the code with the following:

/*
* New code written by Stuart Lewis and added by Clive Gould on 28th April 2009
*/

public int[] getSpecialGroups(Context context, HttpServletRequest request)
{
try
{
if (!context.getCurrentUser().getNetid().equals(""))
{
Group staffGroup = Group.findByName(context, "all-staff");
Group studentsGroup = Group.findByName(context, "all-students");

// Does the username start with a '1'?
if ((studentsGroup != null) && context.getCurrentUser().getNetid().startsWith("1")))
{
// Add them to the students group
return new int[] { studentsGroup.getID() };
}
else if (staffGroup != null)
{
// Add them to the staff group
return new int[] { staffGroup.getID() };
}
}
}
catch (Exception npe) {
// The user is not an LDAP user, so we don't need to worry about them
}
return new int[0];
}

Build and install DSpace

cd /home/dspace/dspace-1.5.2-src-release/dspace
mvn package
cd /home/dspace/dspace-1.5.2-src-release/dspace/target/dspace-1.5.2-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

Restart tomcat and it works :)

su - root
service tomcat stop
service tomcat start

Customising the User Interface

In order to customise the appearance of DSpace 1.5.2 I modified the following files:

/home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp

/home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp

/home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp

/home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp

I also included the college logo by adding the logo.gif file in the following location:

/home/dspace/dspace-1.5.2-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

DSpace was then rebuilt and restarted as follows:

cd /home/dspace/dspace-1.5.2-src-release/dspace
mvn package
cd /home/dspace/dspace-1.5.2-src-release/dspace/target/dspace-1.5.2-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

su - root
service tomcat stop
service tomcat start

Customising the URL

We wanted to have DSpace available on the URL /dspace instead of /jspui and OAI access on /dspace-oai instead of /oai

Stuart Lewis from the University of Auckland kindly provided me with the solution :)

I logged in as user dspace.

First I had to modify tomcat's server.xml file:

nano /home/dspace/apache-tomcat-6.0.18/conf/server.xml

and change the context path as shown below:

from

Context path="/jspui" docBase="/home/dspace/webapps/jspui"

to

Context path="/dspace" docBase="/home/dspace/webapps/jspui"

and from

Context path="/oai" docBase="/home/dspace/webapps/oai" debug="0"

to

Context path="/dspace-oai" docBase="/home/dspace/webapps/oai" debug="0"

Also it was necessary to edit jk.conf:

nano /etc/httpd/conf.d/jk.conf

Then change the JkMount directives to point to the new path as shown below:

JkMount /dspace worker2
#
JkMount /dspace/* worker2
#
JkMount /dspace-oai worker2
#
JkMount /dspace-oai/* worker2

It was then necessary to change the path used by the dspace.url directive in dspace.cfg and rebuild DSpace.

On restarting tomcat DSpace and OAI were available using the required paths :)

Getting the handle server working

This eventually turned out to be relatively easy. It was necessary to edit dspace.cfg and include our existing CNRI handle prefix as follows:

# CNRI Handle prefix
handle.prefix = 2045

It was also necessary to tell DSpace to use the handle server version 6.2 and rebuild DSpace from source. The process I followed is given below. Note that xml tag brackets have been replaced by [] to avoid display problems in this blog.

As user dspace, edit /home/dspace/dspace-1.5.2-src-release/pom.xml and change the handle server version to 6.2. (Thanks go to Stuart Lewis of the The University of Auckland Library for the information on how tell maven to use version 6.2 of the handle jar :)

nano /home/dspace/dspace-1.5.2-src-release/pom.xml

[dependency]
[groupId]org.dspace[/groupId]
[artifactId]handle[/artifactId]

[version]6.2[/version]
[/dependency]

Rebuild DSpace completely from source

cd /home/dspace/dspace-1.5.2-src-release/dspace
mvn package
cd /home/dspace/dspace-1.5.2-src-release/dspace/target/dspace-1.5.2-build.dir
ant -Dconfig=/home/dspace/config/dspace.cfg update

Create the handle server configuration and start the server

cd /home/dspace/bin
./make-handle-config
./start-handle-server

The handle server was tested using the lynx text browser:

lynx vle.bromley.ac.uk:8000

Once the handle ports had been opened at firewall level all was well and handles correctly resolved with handle.net :)))

For more information on testing the handle server and setting up service level scripts to start and stop the server please see the original blog posting below.

Upgrading to DSpace 1.6.0

5th April 2010 : Please note that this is a work in progress and I will log the process once it is complete

Looking at all that is involved this upgrade is starting to look more like a summer holiday job!

Please watch this space...

DSpace installation procedure on Fedora Core 3 and CentOS 4 (RHEL 4)

2005-03-02T00:56:00.000-08:00

Written by Clive Gould. (To contact Clive please use this messages form. Our Linux training website can be reached by clicking here)

Menu

1) DSpace 1.2.1 installation procedure
2) Handle Server installation procedure
3) phpPgAdmin installation and configuration
4) Getting Apache to talk to Tomcat using mod_jk2
5) Starting DSpace Automatically
6) Managing DSpace, Tomcat and Handle Server logs
7) Making DSpace available via Apache and HTTPS
8) Changing the contact telephone number
9) Upgrading to Tomcat 5.5
10) Upgrading to DSpace 1.2.2
11) Customising the Web User Interface
12) Virus scanning and establishing a hot backup server
13) Upgrading to DSpace 1.3.1
14) Getting statistics working
15) Modified handle server configuration
16) Upgrading to DSpace 1.3.2
17) Providing OAI access to DSpace
18) Using a commercial wildcard SSL certificate
19) Installing LAMS on the same server as DSpace
20) Upgrading to DSpace 1.4 (failed)
21) Re-installing DSpace 1.4 (success)
22) Upgrading the handle server to version 6.2
23) Upgrading to DSpace 1.4.1
24) Upgrading to DSpace 1.4.2
25) Enabling RADIUS Authentication in DSpace 1.4.2
26) Using a commercial host specific SSL certificate
27) Upgrading to DSpace 1.5.0

1) DSpace 1.2.1 installation procedure

This blog covers DSpace installation on two separate platforms:

a) 1.2.1 (subsequently upgraded to 1.2.2) on Fedora Core 3, which I first set up in March 2005.

b) 1.2.2 (subsequently upgraded to 1.3.2) on CentOS 4, which I first set up in July 2005.

The machine I used for the Fedora Core 3 installation was an existing, fully Internet accessible server providing services to staff and students 24x7. It was already running apache, vsftpd, sshd, named, dovecot and mysqld.

The machine I used for the CentOS 4 installation was a new high specification server and I installed jdk-1_5_0_04, apache-ant-1.6.5 and jakarta-tomcat-5.5.9 on it following the instructions given for DSpace 1.2.1 and Fedora Core 3 in this blog.

I have added comments in blue where the CentOS installation differed from the earlier Fedora Core 3 installation of DSpace.

Beginning the Fedora Core 3 installation:

The JDK (1.5.0) had already been downloaded from Sun and installed in /usr/java/jdk1.5.0 - I subsequently renamed the directory jdk1.5.0 to jdk in order to simplify paths in the event of a future upgrade of the JDK.

The next step was to download Ant (1.6.2) and install it. I installed it as root in /usr/local as follows:

cd /usr/local
lynx http://ant.apache.org/bindownload.cgi
tar -xzvf apache*.tar.gz
mv apache-ant-1.6.2 ant

As Apache was already running and in use I initially decided to install Tomcat as a totally separate and independent installation.

The next step was to create a user dspace with home directory /home/dspace. As user dspace I then proceded to download and install Tomcat (4.1.31) in /home/dspace as follows:

cd /home/dspace
lynx http://jakarta.apache.org/site/downloads/downloads_tomcat-4.cgi
tar -xzvf jakarta-tomcat-4.1.31.tar.gz
mv jakarta-tomcat-4.1.31 tomcat

The following paths were set up in /etc/profile:

export JAVA_HOME=/usr/java/jdk
export CATALINA_HOME=/home/dspace/tomcat
export ANT_HOME=/usr/local/ant
export PATH=${PATH}:${ANT_HOME}/bin
export PATH=${PATH}:${JAVA_HOME}/jre/bin

As user dspace I started Tomcat from the /home/dspace/tomcat/bin directory using the following command:

[dspace@cd bin]$ ./startup.sh
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk

Running nmap on the IP address of the machine confirmed that Tomcat was running and listening for connections on port 8080:
8080/tcp open http-proxy

Visting the URL http://cd.bromley.ac.uk:8080 allowed me to try out the jsp examples available from the Tomcat homepage :-)

As user dspace I then downloaded DSpace and installed it in the home directory of the dspace user /home/dspace as follows:

cd /home/dspace
lynx http://sourceforge.net/projects/dspace/
gunzip -c dspace-1.2.1-source.tar.gz tar -xf -

The next task as user dspace was to download the pg74.215.jdbc3.jar file which was specific to the version of the JDK (1.5.0) and the version of PostgreSQL (7.4.7-3) I was using:

cd /home/dspace/dspace-1.2.1-source/lib
lynx http://jdbc.postgresql.org/download.html#jars

The next task was getting PostgreSQL working. PostgreSQL was already installed with Fedora Core 3. The first step was to become user postgres from a root login by using the command:

su - postgres

The postgres user has administrative control over PostgreSQL and commands typed by this user can be used to administer the database directly.

The first step was to create a new Postgres database installation using the following command:

initdb -D /var/lib/pgsql/data

The next step was to edit the file /var/lib/pgsql/data/postgresql.conf and change the tcpip parameter to true as shown below:

tcpip_socket = true

The next step was to edit the file /var/lib/pgsql/data/pg_hba.conf and comment out the following line at the end of the file:

# local all all ident sameuser

I then appended the following lines to the end of the file:

host dspace dspace 127.0.0.1 255.255.255.255 md5
local template1 postgres trust
local template1 dspace trust

I then had to become root and start PostgreSQL as follows:

[root@cd data]# /etc/init.d/postgresql start
Starting postgresql service: [ OK ]

It was then necessary to su - postgres and create the user dspace and the database dspace as follows:

-bash-3.00$ createuser -U postgres -d -A -P dspace
Enter password for new user:
Enter it again:
CREATE USER

-bash-3.00$ createdb -U dspace -E UNICODE dspace
CREATE DATABASE

As user dspace it was then necessary to edit the file /home/dspace/dspace-1.2.1-source/config/dspace.cfg and add the appropriate entries, paying particular attention to changing ALL the paths from /dspace/ to /home/dspace/

The following website proved most helpful with this:

http://www.thesesalive.ac.uk/archive/DSpaceInstall.pdf

Before running ant to build dspace it was necessary to remove a number of rpm's that had been installed as part of the default Fedora Core 3 upgrade of everything:

[root@cd ~]# rpm -e --nodeps libgcj gcc-java libgcj-devel gettext ant tomcat

(If this is not done you will get cryptic error messages such as:
BUILD FAILED
file:/home/dspace/dspace-1.2.1-source/build.xml:109: Error running
gcj34 compiler)

Note: With CentOS 4 it was not necessary to remove any of these rpms.

As user dspace the application was now successfully built using the commands:
[dspace@cd dspace-1.2.1-source]$ ant
[dspace@cd dspace-1.2.1-source]$ ant fresh_install

I successfully copied over the .war files to tomcat webapps directory as shown below and DSpace ran.

cd /home/dspace/dspace-1.2.1-source/build/
cp *.war /home/dspace/tomcat/webapps

I ran the following script to set up the administrator account:
/home/dspace/bin/create-administrator

Note: With CentOS 4 this produced a screen full of errors. The solution turned out to be correcting the path to Java. The last line of /home/dspace/bin/dsrun needed to be changed to:

# Now invoke Java
/usr/java/jdk/bin/java -mx2024m -classpath $FULLPATH "$@"

This assumes that the jdk is installed in a directory called /usr/java/jdk

For administrative purposes I tried setting up the posgres crontab to vacuum the database, but this did not work properly with my database access permissions.

As a result the final crontab entry I set for user dsapce was as shown below:

su - dspace
[dspace@cd ~]$ crontab -l
0 1 * * * /home/dspace/bin/sub-daily
# Run the media filter at 02:00 every day
0 2 * * * /home/dspace/bin/filter-media
# Clean up the database nightly at 2.40am
40 2 * * * cd /home/dspace/vacuumdb && ( PGPASSWORD=`cat .pgpass` /usr/bin/vacuumdb --analyze -v -h 127.0.0.1 -U dspace dspace )

(When a user searches DSpace, both the metadata and indexed text are searched for matches, and the results are displayed together. Running the filter-media script regularly facilitates full-text searching for many text objects such as PDF, Word, HTML and text files.)

In order to get database vaccuming to work properly, in addition to the final line in the crontab, I also created a directory /home/dspace/vacuumdb containing the file .pgpass (owned by user dspace and with 600 permissions), which in turn contained the database access password for the dspace database.

I noticed that the text indexing wasn't working properly, unless I ran the script manually. Later on I came across several error messages in user dspace's email as follows:

Subject: Cron dspace@cd /home/dspace/bin/filter-media
Applying Media Filters
/home/dspace/bin/dsrun: line 70: java: command not found

Subject: Cron dspace@cd /home/dspace/bin/sub-daily
/home/dspace/bin/dsrun: line 70: java: command not found

It appeared that Cron could not find the path to java, so as user dspace, I added the following environment definition to the top of both the filter-media and sub-daily scripts:

# Set Environment Variables (Added by Clive Gould on 1st April 2005)

JAVA_HOME=/usr/java/jdk; export JAVA_HOME
CATALINA_HOME=/home/dspace/tomcat; export CATALINA_HOME
ANT_HOME=/usr/local/ant; export ANT_HOME
PATH=${PATH}:${ANT_HOME}/bin
PATH=${PATH}:${JAVA_HOME}/jre/bin; export PATH

Cron subsequently ran the filter-media and sub-daily scripts correctly.

Note: With CentOS 4 this environment variable definition was not necessary as the earlier alteration to the path for java in dsrun solved this problem.

I then came across an error in my root emails containing the following text:

# Send out subscription e-mails at 01:00 every dayException:
java.io.IOException: /dspace/search not a directory
at org.apache.lucene.sto/home/dspace/config/dspace.cfg
re.FSDirectory.FSDirectory.java:154)

It turned out that there were still some paths in dspace.cfg that required amendment. I edited /home/dspace/config/dspace.cfg and changed a few more paths from /dspace/ to /home/dspace

I then ran the /home/dspace/bin/install-configs script to install my changes into the running dspace implementation.

I was then able to run the /home/dspace/bin/index-all script successfully

Had an error when creating my first collection when logged on as administrator to our new dspace website. The error was logged in /home/dspace/log/dspace.log as follows:

java.lang.IllegalArgumentException: Not a directory: /home/dspace/upload

As user dspace I created the directory /home/dspace/upload and from the browser deleted the community/collection I was trying to create.

With CentOS 4 and DSpace 1.2.2 the upload directory was already present.

This time I was able to successfully create a community and a collection.

Return to Menu

2) Handle Server installation procedure

The procedure outlined below is the one I should have followed in order to configure the DSpace handle server on Fedora Core 3. (The process I actually followed was somewhat longer due to mistakes I made along the way!")

This part of the blog covers the handle server configuration with DSpace 1.2.x. If you are configuring a handle server with DSpace 1.3.1 please read the last entry in this blog as well.

The following websites really helped me with handle configuration:

http://sunsite.utk.edu/diglib/dspace/
http://www.thesesalive.ac.uk/archive/ERAInstallation-1.9.html#_Toc82495072

Configuration process:

Log on as user dspace, move to the /home/dspace/bin directory and run the command shown below. Note that default responses provided by the command are shown in square brackets and where I have made replies other than the default they are shown in bold.

The replies shown below are those that eventually proved the correct ones for my server, which is behind a NAT firewall blocking incoming UDP packets. In this case the IP address supplied was the internal IP address of the server on the Intranet side of the NAT box.

[dspace@cd bin]$ dsrun net.handle.server.SimpleSetup /home/dspace/handle-server
We will now configure your new Handle or Caching server.
Please answer the following questions.
Default answers, when available, will be shown in square brackets.

Will this be a caching server or a regular handle server?
(If unsure, choose regular handle server)
1 - Handle server
2 - Caching handle server
Please choose 1 or 2 and press enter: 1

Will this be a "primary" server (ie, not a mirror of another server)? (y/n) [y]

Through what IP address will this server be accessible? (domain names are ok) 172.31.0.3

What port number will this server be listening to? [2641]

What port number will the HTTP interface be listening to? [8000]

Would you like to log all accesses to this server? (y/n) [n] y

Each handle site has a version/serial number assigned to it. This is so that clients can tell if a particular site configuration has changed since the last time it accessed a server in the site. Every time you modify a site (by changing an IP address, port, or adding a server, etc), you should increment the version/serial number for that site
Enter the version/serial number of this site: [1]

Please enter a short description of this server/site: Bromley College Dspace Repository

The Handle System can communicate via UDP and/or TCP sockets.
Since UDP messages are blocked by many network firewalls, you may
want to disable UDP services if you are behind such a firewall.
Would you like to disable UDP services? (y/n) [n] y

Server keys already exist, do you want to create new ones? (y/n) [n]

Administrator keys already exist, do you want to create new ones? (y/n)[n]

Generating site info record...

-------------------------------------------------------
Congratulations, the configuration has been generated.

The sitebndl.zip file contains the answers to the above questions and needs to be submitted to CNRI as the following excerpt from the DSpace install documentation (updated in August 2005) explains:

"Go to to http://hdl.handle.net/4263537/5014 to upload the generated sitebndl.zip file. The upload page will ask you for your contact information. An administrator will then create the naming authority/prefix on the root service (known as the Global Handle Registry), and notify you when this has been completed. You will not be able to continue the handle server installation until you receive further information concerning your naming authority."

(As our machine is behind a NAT firewall, I was additionally asked by CNRI to email them the external IP address of our server on the Internet side of the firewall. This was required to enable the CNRI handle server to talk to our local handle server. I received a reply within 24 hours containing our handle prefix, which was 2045)

Edit /home/dspace/handle-servers/config.dct and change all three naming authority handles. (Note that the IP address within this file was the internal IP address of our server.)

A copy of the final version of this file, which actually worked for me is shown below:

[dspace@cd handle-server]$ cat config.dct

{
"hdl_http_config" = {
"bind_address" = "172.31.0.3"
"num_threads" = "15"
"bind_port" = "8000"
"backlog" = "5"
"log_accesses" = "yes"
}

"hdl_udp_config" = {
"bind_address" = "172.31.0.3"
"num_threads" = "15"
"bind_port" = "2641"
"log_accesses" = "yes"
}

"hdl_tcp_config" = {
"bind_address" = "172.31.0.3"
"num_threads" = "15"
"bind_port" = "2641"
"backlog" = "5"
"log_accesses" = "yes"
}

"server_type" = "server"
"no_udp_resolution" = "n"
"interfaces" = (
"hdl_udp"
"hdl_tcp"
"hdl_http"
)

"server_config" = {
"server_admins" = (
"300:0.NA/2045"
)

"replication_admins" = (
"300:0.NA/2045"
)

"this_server_id" = "1"
"max_session_time" = "86400000"
"max_auth_time" = "60000"
"backup_admins" = (
"300:0.NA/2045"
)

"case_sensitive" = "no"
"storage_type" = "CUSTOM"
"storage_class" = "org.dspace.handle.HandlePlugin"
}

}

With DSpace 1.2.2 and CentOS 4 the default config.dct file did not work properly and the handle server would not correctly resolve. I had to replace the default config.dct with a "cut and paste" of the above file with the IP address updated to reflect the new server. On restarting the handle server all was well :-)

Edit /home/dspace/config/dspace.cfg as follows to tell DSpace to allocate handles beginning with your prefix. A excerpt from our file is shown below:

##### Handle settings ######

# CNRI Handle prefix
handle.prefix = 2045

# Directory for installing Handle server files
handle.dir = /home/dspace/handle-server

Before the new handle prefix settings will take effect in DSpace it is necessary to restart Tomcat using the scripts in the /home/dspace/tomcat/bin directory:

[dspace@cd bin]$ ./shutdown.sh
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk
[dspace@cd bin]$ ./startup.sh
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk

At this point upload a file into your DSpace repository to test the handle allocation and check that DSpace is now allocating the correct handle prefix.

Start the handle server from the /home/dspace/bin directory by running the command:

[dspace@cd bin]$ ./start-handle-server

If necessary, the local handle server can be stopped by killing the appropriate processes. This is illustrated in the excerpt shown below:

[dspace@cd ~]$ ps aux
dspace 29190 0.0 0.0 4332 1004 ? S Mar13 0:00 /bin/sh ./dsrun -Dlog4j.configuration=log4j-handle-plugin.properties net.handle.server.Main /home/dspace/handle-se.......
dspace 29196 0.0 2.3 497476 23828 ? Sl Mar13 0:01 java -Xmx256m -classpath :/home/dspace/lib/activation.jar:/home/dspace/lib/commons-cli.jar:/home/dspace/lib/common......
[dspace@cd ~]$ kill 29190
[dspace@cd ~]$ kill 29196

Useful tests for handle resolution include:

1) Using your browser to visit port 8000 on your handle server's IP address, which produces the homepage for your handle server. Entering a handle prefix (e.g. 0.NA/2045) will prove your handle server is communicating properly.

2) Visiting http://hdl.handle.net/ and entering one of your DSpace handles (e.g. 2045/39) should bring up the chosen resource page in DSpace or at least provide useful debugging information.

Handle records log information in the following files:

/home/dspace/handle-server/access.log
/home/dspace/handle-server/error.log
/home/dspace/log/handle-server.log

(I had some problems because of the mistakes I'd made when providing my initial responses to the dsrun net.handle.server.SimpleSetup /home/dspace/handle-server command. Initially http://hdl.handle.net could not find my handle server as I'd only supplied the internal IP address and not the external one and chosen UDP instead of TCP for communications. The error message was "Error - Cannot Connect to Server The handle you requested cannot be found." Jane Euler of CNRI was really helpful and corrected this for me. I then found that my local handle server was not finding handles created in DSpace. The error message was "Nothing to display No URL value(s) found for the requested handle." This turned out to be due to my having run the above dsrun command line a second time, which of course regenerated config.dct and sitebndl.zip. Subsequently I had missed out on including the storage type and class lines at the end of config.dct the second time around!)

Return to Menu

3) phpPgAdmin installation and configuration

I noticed that the new handles DSpace created once I had modified the handle prefix were correct, but the original handles created by Dspace before I got the handle server up & running and modified the prefix still remained at the original default value of 123456789.

As a result of a newsgroup posting I decided to download and install phpPgAdmin. The idea was to use the web based administration tool for PostgreSQL to edit the dspace database directly and change the values of the default handle prefixes.

I became the root user and used the following commands:

cd /var/www/html
lynx http://phppgadmin.sourceforge.net/?page=download
tar -xzvf phpPgAdmin-3.5.2.tar.gz
rm *.tar.gz
cd phpPgAdmin
cd conf
cp config.inc.php-dist config.inc.php
pico config.inc.php

I modified config.inc.php as shown below in bold:

[root@cd conf]# cat config.inc.php
'127.0.0.1';

// Database port on server (5432 is the PostgreSQL default)
$conf['servers'][0]['port'] = 5432;

// Change the default database only if you cannot connect to template1
$conf['servers'][0]['defaultdb'] = 'dspace';

// Specify the path to the database dump utilities for this server.
// You can set these to '' if no dumper is available.
$conf['servers'][0]['pg_dump_path'] = '';
$conf['servers'][0]['pg_dumpall_path'] = '';

// Example for a second server (PostgreSQL for Windows)
//$conf['servers'][1]['desc'] = 'Test Server';
//$conf['servers'][1]['host'] = '127.0.0.1';
//$conf['servers'][1]['port'] = 5432;
//$conf['servers'][1]['defaultdb'] = 'template1';
//$conf['servers'][1]['pg_dump_path'] = 'C:\\Program Files\\PostgreSQL\8.0\\bin\\pg_dump.exe';
//$conf['servers'][1]['pg_dumpall_path'] = 'C:\\Program Files\\PostgreSQ
L\\8.0\\bin\\pg_dumpall.exe';

// Default language for the login screen if there's no translation
// matching user's browser request. Eg: 'english', 'polish', etc.
$conf['default_lang'] = 'english';

// If extra login security is true, then logins via phpPgAdmin with no
// password or certain usernames (pgsql, postgres, root, administrator)
// will be denied. Only set this false once you have read the FAQ and
// understand how to change PostgreSQL's pg_hba.conf to enable
// passworded local connections.
$conf['extra_login_security'] = true;

// Only show owned databases?
// Note: This will simply hide other databases in the list - this does
// not in any way prevent your users from seeing other database by
// other means. (eg. Run 'SELECT * FROM pg_database' in the SQL area.)
$conf['owned_only'] = false;

// Display comments on objects? Comments are a good way of documenting
// a database, but they do take up space in the interface.
$conf['show_comments'] = true;

// Display "advanced" objects? Setting this to true will show types,
// operators conversions, languages and casts in phpPgAdmin. These
// objects are rarely administered and can clutter the interface.
$conf['show_advanced'] = false;

// Display "system" objects?
$conf['show_system'] = false;

// Display reports feature? For this feature to work, you must
// install the reports database as explained in the INSTALL file.
$conf['show_reports'] = true;

// Only show owned reports?
// Note: This does not prevent people from accessing other reports by
// other means.
$conf['owned_reports_only'] = false;

// Minimum length users can set their password to.
$conf['min_password_length'] = 1;

// Width of the left frame in pixels (object browser)
$conf['left_width'] = 200;

// Which look & feel theme to use
$conf['theme'] = 'default';

// Show OIDs when browsing tables?
$conf['show_oids'] = false;

// Max rows to show on a page when browsing record sets
$conf['max_rows'] = 30;

// Max chars of each field to display by default in browse mode
$conf['max_chars'] = 50;

// Send XHTML headers? Unless debugging, it's best to leave this off
$conf['use_xhtml'] = false;

/*****************************************
* Don't modify anything below this line *
*****************************************/

$conf['version'] = 13;

?>

I can now log on to phpPgAdmin from the browser as user dspace with the password I provided when I created the dspace user in PostgreSQL.

The handle table can be found in phpPgAdmin at the following location:

PostgreSQL?: dspace?: public?: handle?:

It is simply a question of browsing this table and manually changing any pre-existant default handles of 123456789 to the handle prefix allocated by CNRI. DSpace happily picks up the new information and the handles can then be correctly resolved from hdl.handle.net

Return to Menu

4) Getting Apache to talk to Tomcat using mod_jk2

Tomcat and DSpace are now fully up and running on the cd server on port 8080 but we can only access them externally because our staff and student network proxy servers will only allow access via ports 80 and 443 to "external" servers! To get round this I have set up Apache to talk to Tomcat so that a URL in the format:

http://cd.bromley.ac.uk/dspace automatically provides access to http://cd.bromley.ac.uk:8080/dspace

The steps I took are outlined below:

I found that Fedora Core 3 already had mod_jk2 installed as the excerpt below shows:

[root@cd ~]# locate mod_jk2
/usr/lib/httpd/modules/mod_jk2.so

I went to the /etc/httpd/conf.d directory and found that jk2.conf was
already there:

[root@cd conf.d]# cat jk2.conf
#
# Mod_jk2 allows the Apache Web server to connect to application
# servers using the AJP protocol. This allows web applications to
# be integrated seamlessly into your Apache server's URI space and
# utilize Apache features such as SSL processing.
#
LoadModule jk2_module modules/mod_jk2.so
#
# Mod_jk2 is configured in /etc/httpd/conf/workers2.properties
#

I then created the /etc/httpd/conf/workers2.properties file. The final version that worked for me is shown below:

[root@cd conf]# cat workers2.properties
[logger.file:0]
level=WARN
file=${serverRoot}/logs/jk2.log

[shm]
info=Defines the shared memory
file=${serverRoot}/logs/jk2.shm
size=1000000
debug=0
disabled=0

[channel.socket:localhost:8009]
info=Defines the local Tomcat server
tomcatId=jvm1
host=localhost
port=8009

[ajp13:localhost:8009]
info=Defines the default ajp13 worker
channel=channel.socket:localhost:8009

[status:status]
info=Defines the status worker

[uri:/jkstatus/*]
group=status:status

[uri:/scheduler/*]
context=/scheduler

[uri:/dspace/*]
context=/dspace

The only thing I had to look up for this was the tomcatId attribute, which has to have the same as the value of the jvmRoute attribute in the file /home/dspace/tomcat/conf/server.xml as shown below:

[dspace@cd conf]$ grep jvm server.xml
You should set jvmRoute to support load-balancing via JK/JK2 ie : Engine name="Standalone" defaultHost="localhost" debug="0" jvmRoute="jvm1"

I added the dspace URI at the bottom of the workers2.properties file so that Apache would automatically refer any requests for /dspace to Tomcat.

I then stopped Tomcat and added the following line to the default /home/dspace/tomcat/conf/jk2.properties file, which was otherwise just comments:

channelSocket.port=8009

I started Tomcat and also restarted Apache and was delighted to find that when I visited http://cd.bromley.ac.uk/dspace it worked :-) What's more it also worked from our staff and student network behind the proxy servers :-))

With CentOS 4, mod_jk2 was not installed. I copied mod_jk2.so from Fedora Core 3 and then followed the above procedure, copying the jk2.conf and workers2.properties files as given above. I was delighted to find DSpace was then accessible via Apache.

(I found the following book provided me with invaluable help in configuring Tomcat to work with Apache:

Title: Tomcat 5
Author: Lapis Moczar
Publisher: SAMS
ISBN: 0-672-32636-1)

The next task was to sort out the port address of 8080 which DSpace used when generating a self-referential URL for registration purposes. Once again this worked fine from outside college but would not work from either the staff of student networks because of the proxy problem.

I edited the /home/dspace/config/dspace.cfg file and changed the following line to remove the :8080 as shown below:

# DSpace base URL. Include port number etc., but NOT trailing slash
dspace.url = http://cd.bromley.ac.uk/dspace

I then ran the the following command to install the revised configuration:

/home/dspace/bin/install-configs

Next I and stopped and re-started tomcat so that the changes took effect:

[dspace@cd bin]$ ./shutdown.sh
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk
[dspace@cd bin]$ ./startup.sh
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk

I was now able to successfully register a new user from the staff network as Dspace now provided the correct self referential URL without the 8080 included :-)))

Return to Menu

5) Starting DSpace Automatically

With Fedora Core 3 there was already a service script to start and stop PostgreSQL. However, I needed to create two basic scripts in /etc/initd.d to start and stop tomcat and the handle server. This was to make starting DSpace easier after a power cut or kernel upgrade.

As root I used an editor to create the files /etc/init.d/tomcat and /etc/init.d/handle as shown below:

[root@cd ~]# cat /etc/init.d/tomcat
#!/bin/sh
#
# description: Tomcat
#
# Shell script to to start/stop Tomcat
#
# Set Enviroment Variables and Paths
#
JAVA_HOME=/usr/java/jdk; export JAVA_HOME
CATALINA_HOME=/home/dspace/tomcat; export CATALINA_HOME
ANT_HOME=/usr/local/ant; export ANT_HOME
PATH=${PATH}:${ANT_HOME}/bin
PATH=${PATH}:${JAVA_HOME}/jre/bin; export PATH
#
case "$1" in
start)
#
# Start Tomcat
#
echo
sudo -u dspace /home/dspace/tomcat/bin/startup.sh
;;

stop)
#
# Stop Tomcat
#
sudo -u dspace /home/dspace/tomcat/bin/shutdown.sh
;;

*)
echo "Usage service tomcat start/stop"
exit 1;;
esac

[root@cd ~]# cat /etc/init.d/handle
#!/bin/sh
#
# description: Handle Server
#
# Shell script to to start/stop the Handle Server for DSpace
#
# Set Enviroment Variables and Paths
#
JAVA_HOME=/usr/java/jdk; export JAVA_HOME
CATALINA_HOME=/home/dspace/tomcat; export CATALINA_HOME
ANT_HOME=/usr/local/ant; export ANT_HOME
PATH=${PATH}:${ANT_HOME}/bin
PATH=${PATH}:${JAVA_HOME}/jre/bin; export PATH
#
case "$1" in
start)
#
# Start Handle Server
#
echo
sudo -u dspace /home/dspace/bin/start-handle-server
;;

stop)
#
# Stop Handle Server
#
pkill -u dspace
;;

*)
echo "Usage service handle start/stop"
exit 1;;
esac

I then ran the following commands as root to make the scripts executable:

[root@cd ~]# chmod 755 /etc/init.d/tomcat
[root@cd ~]# chmod 755 /etc/init.d/handle

Using an editor I added the following lines to the end of rc.local:

service postgresql start
service tomcat start
service handle start

DSpace now automatically starts on boot. (As root, I can also use the new commands to stop and start the tomcat and handle services manually. However, care has to be taken to get the order right and stop tomcat first, as the the handle stop script kills any remaining processes owned by user dspace.)

I have also stopped the Fedora Core 3 automatic nightly yum updates to prevent an inadvertant update of PostgreSQL to version 8.0 affecting DSpace operation. I plan to review updates manually in future.

Return to Menu

6) Managing DSpace, Tomcat and Handle Server logs

To solve the problem of managing the logs associated with DSpace, Tomcat and the Handle-Server, I created the shell script /etc/cron.weekly/dspace as shown below:

[root@cd cron.weekly]# cat dspace
# Custom log rotation script for DSpace
# Written by Clive Gould (27th March 2005)
service tomcat stop
service handle stop
rm -rf /home/dspace/tomcat/logs.old/*
mv /home/dspace/tomcat/logs/localhost* /home/dspace/tomcat/logs.old
cp /home/dspace/tomcat/logs/catalina.out /home/dspace/tomcat/logs.old
cat /dev/null > /home/dspace/tomcat/logs/catalina.out
#
rm -rf /home/dspace/log.old/*
mv /home/dspace/log/*20* /home/dspace/log.old
cp /home/dspace/log/*log /home/dspace/log.old
cat /dev/null > /home/dspace/log/dspace.log
cat /dev/null > /home/dspace/log/handle-plugin.log
cat /dev/null > /home/dspace/log/handle-server.log
#
rm -rf /home/dspace/handle-server/*.1
cp /home/dspace/handle-server/access.log /home/dspace/handle-server/access.log.1
cp /home/dspace/handle-server/error.log /home/dspace/handle-server/error.log.1
cat /dev/null > /home/dspace/handle-server/access.log
cat /dev/null > /home/dspace/handle-server/error.log
#
service tomcat start
service handle start

I made it executable using the following command:

[root@cd cron.weekly]# chmod 755 dspace

I then became user dspace and created the two .old log directories as shown below:

[root@cd cron.weekly]# su - dspace
[dspace@cd ~]$ mkdir log.old
[dspace@cd ~]$ mkdir tomcat/logs.old

Return to Menu

7) Making DSpace available via Apache and HTTPS

The default install of Apache with Fedora Core 3 provides full HTTPS access on port 443.

On visiting https://cd.bromley.ac.uk/dspace I found that DSpace came up over a secure connection without any further work on my part :-) (My understanding is that the browser communicates with Apache over a secure https connection via port 443 and then Apache communicates with Tomcat via the existing internal connection. This means that Tomcat does not need to be re-configured to listen over a secure connection.)

In order for DSpace to reference the revised URL correctly I edited the /home/dspace/config/dspace.cfg file as user dspace and changed the following line to add the https service as shown below:

# DSpace base URL. Include port number etc., but NOT trailing slash
dspace.url = https://cd.bromley.ac.uk/dspace

I then ran the the following command to install the revised configuration:

/home/dspace/bin/install-configs

Next, as user root, I and stopped and re-started both tomcat and the handle server so that the changes took effect:

service tomcat stop
service handle stop
service tomcat start
service handle start

DSpace now worked fully with https, with all paths correct and handles resolving to the new URL.

The next step was to create a valid certificate as Apache was currently using just the localhost.localdomain certificate that came with the default install of Fedora.

I found the following website provided invaluable guidance on creating a certificate:

http://www.tc.umn.edu/~brams006/selfsign.html

The commands I used, as root (with the system responses shown in italic and my responses shown in bold where apppriate), are illustrated below:

cd
mkdir certwork
chmod 750 certwork
cd certwork

I generated the Certificate Authority myself as shown below:

[root@cd certwork]# openssl genrsa -des3 -out ca.key 4096
Generating RSA private key, 4096 bit long modulus
..............................................................................................................................................................................++
.........................++
e is 65537 (0x10001)
Enter pass phrase for ca.key:
Verifying - Enter pass phrase for ca.key:

[root@cd certwork]# openssl req -new -x509 -days 365 -key ca.key -out ca.crt
Enter pass phrase for ca.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:GB
State or Province Name (full name) [Berkshire]:Kent
Locality Name (eg, city) [Newbury]:Bromley
Organization Name (eg, company) [My Company Ltd]:Bromley College
Organizational Unit Name (eg, section) []:School of ICT
Common Name (eg, your name or your server's hostname) []:cd.bromley.ac.uk
Email Address []:root@cd.bromley.ac.uk

I then generated a server key and request for signing as shown below:

[root@cd certwork]# openssl genrsa -des3 -out server.key 4096
Generating RSA private key, 4096 bit long modulus
..........++
.....................................................++
e is 65537 (0x10001)
Enter pass phrase for server.key:
Verifying - Enter pass phrase for server.key:

[root@cd certwork]# openssl req -new -key server.key -out server.csr
Enter pass phrase for server.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:GB
State or Province Name (full name) [Berkshire]:Kent
Locality Name (eg, city) [Newbury]:Bromley
Organization Name (eg, company) [My Company Ltd]:Bromley College
Organizational Unit Name (eg, section) []:School of ICT
Common Name (eg, your name or your server's hostname) []:cd.bromley.ac.uk
Email Address []:root@cd.bromley.ac.uk

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

I then signed the certificate signing request with the self-created certificate authority that I made earlier:

[root@cd certwork]# openssl x509 -req -days 365 -in server.csr -CA ca.crt -CAkey ca.key -signkey server.key -set_serial 01 -out server.crt
Signature ok
subject=/C=GB/ST=Kent/L=Bromley/O=Bromley College/OU=School of
ICT/CN=cd.bromley.ac.uk/emailAddress=root@cd.bromley.ac.uk
Getting CA Private Key
Enter pass phrase for ca.key:
Getting Private key
Enter pass phrase for server.key:

I then created an "insecure" server key to prevent Apache asking for a password every time I tried to restart the httpd process:

[root@cd certwork]# openssl rsa -in server.key -out server.key.insecure
Enter pass phrase for server.key:
writing RSA key
[root@cd certwork]# mv server.key server.key.secure
[root@cd certwork]# mv server.key.insecure server.key

As root, I then copied the keys over to the appropriate Apache directories as shown below:

cp /root/certwork/server.key /etc/httpd/conf/ssl.key
cp /root/certwork/server.crt /etc/httpd/conf/ssl.crt
cp /root/certwork/server.csr /etc/httpd/conf/ssl.csr

To be on the safe side I also changed the permissions of the above files to 600 as shown below:

chmod 600 /etc/httpd/conf/ssl.key/server.key
chmod 600 /etc/httpd/conf/ssl.crt/server.crt
chmod 600 /etc/httpd/conf/ssl.csr/server.csr

As root, I then restarted Apache:

[root@cd certwork]# service httpd restart
Stopping httpd: [ OK ]
Starting httpd: [ OK ]

When I visited DSpace from a browser the new certificate was successfully presented for acceptance :-)

Return to Menu

8) Changing the contact telephone number

When a contact message is displayed the phone number comes up with the default of xxx-555-xxxx

To change this I edited the file /home/dspace/dspace-1.2.1-source/jsp/components/contact-info.jsp

and changed the text shown in bold:

td class="standard" Or telephone: /td
td class="standard" 020 8295 7000 x7144 /td

(Please note that in the lines above the opening and closing html tags have been removed as otherwise the blog does not display properly.)

I then rebuilt DSpace as shown below:
[dspace@cd dspace-1.2.1-source]$ ant -Dconfig=/home/dspace/config/dspace.cfg build_wars
Buildfile: build.xml
compile:
build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.2.1-source/build/jsp
[war] Building war: /home/dspace/dspace-1.2.1-source/build/dspace.war
BUILD SUCCESSFUL
Total time: 3 seconds

I then stopped Tomcat as root:

[dspace@cd dspace-1.2.1-source]$ su - root
Password:
[root@cd ~]# service tomcat stop
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk
[root@cd ~]#

I then exited back to user DSpace and removed the tomcat dspace directory:

[dspace@cd dspace]$ rm -rf /home/dspace/tomcat/webapps/dspace

I then copied over the dspace.war file into the webapps directory:

[dspace@cd dspace]$ cp /home/dspace/dspace-1.2.1-source/build/dspace.war /home/dspace/tomcat/webapps

I then restarted Tomcat as root:
[dspace@cd webapps]$ su - root
Password:
[root@cd ~]# service tomcat start

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JAVA_HOME: /usr/java/jdk

Hurray - contact details are now as shown below:

DSpace at Bromley College administration contact details:
By e-mail: dspace-help@cd.bromley.ac.uk
Or telephone: 020 8295 7000 x7144

Return to Menu

9) Upgrading to Tomcat 5.5

I decided to upgrade Tomcat to the latest version. (I had read that Tomcat 5.5 needed the JRE, but on further investigation found that the JRE was already included in a download of the JDK.)

Before installing Tomcat 5.5 I downloaded and installed the latest JDK from Sun, as root, using the commands shown below:

cd /usr/java
lynx http://java.sun.com/j2se/1.5.0/download.jsp
chmod 755 *.bin
./jdk-1_5_0_02-linux-i586.bin
rm *.bin
cp -pr jdk1.5.0_02 jdk

As user dspace, I downloaded the latest version of Tomcat and unpacked it into the dspace home directory using the commands shown below:

cd /home/dspace
lynx http://jakarta.apache.org/site/downloads/downloads_tomcat-5.cgi
tar -xzvf jakarta-tomcat-5.5.7.tar.gz

As user root, I stopped Apache using the command:

service httpd stop

As user dspace, I then completed the installation using the commands shown below:

service tomcat stop
service handle stop
mv tomcat tomcat-4.1
mv jakarta-tomcat-5.5.7 tomcat
cd /home/dspace/dspace-1.2.1-source/build/
cp *.war /home/dspace/tomcat/webapps
service tomcat start
service handle start

As user root, I started Apache using the command:

service httpd start

Amazingly DSpace worked perfectly with Tomcat 5.5 first time and with no problems :-)

Return to Menu

10) DSpace 1.2.2 upgrade procedure

7th May 2005: Downloaded DSpace 1.2.2 from the Dublin mirror into the /home/dspace directory as follows:

[dspace@cd ~]$ lynx http://prdownloads.sourceforge.net/dspace/dspace-1.2.2-source.tar.gz?download

Unpacked the file within the /home/dpsace directory:

[dspace@cd ~]$ tar -xzvf dspace-1.2.2-source.tar.gz

removed the download file:

[dspace@cd ~]$ rm dspace-1.2.2-source.tar.gz

Needed to find the update documentation so used the following commands to copy over the update.html into the Apache webserver root directory from where I could read it using a browser:

cd dspace-1.2.2-source/docs
su root
cp update.html /var/www/html
exit

From now on this upgrade follows the procedure given in the upgrade.html document.

Copied over the jar file as follows:

[dspace@cd ~]$ cd dspace-1.2.1-source/lib
[dspace@cd lib]$ cp pg74.215.jdbc3.jar ../../dspace-1.2.2-source/lib

Stopped Tomcat and the handle-server as follows:

[dspace@cd lib]$ su - root
Password:
[root@cd ~]# service tomcat stop

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

[root@cd ~]# service handle stop
[root@cd ~]# exit

Added the following lines to the end of /home/dspace/config/dspace.cfg

##### Fulltext Indexing settings #####
# Maximum number of terms indexed for a single field in Lucene.
# Default is 10,000 words - often not enough for full-text indexing.
# If you change this, you'll need to re-index for the change
# to take effect on previously added items.
# -1 = unlimited (Integer.MAX_VALUE)
search.maxfieldlength = 10000

Changed to the directory dspace-1.2.2-source and ran the ant update command:

[dspace@cd ~]$ cd dspace-1.2.2-source
[dspace@cd dspace-1.2.2-source]$ ant -Dconfig=/home/dspace/config/dspace.cfg update

Buildfile: build.xml

compile:
[mkdir] Created dir: /home/dspace/dspace-1.2.2-source/build/classes
[javac] Compiling 136 source files to /home/dspace/dspace-1.2.2-source/build/classes
[javac] /home/dspace/dspace-1.2.2-source/src/org/dspace/browse/Browse.java:367:
warning: non-varargs call of varargs method with inexact argument type
for last parameter;
[javac] cast to java.lang.Object for a varargs call
[javac] cast to java.lang.Object[] for a non-varargs call and to
suppress this warning
[javac] new String[] { browseTables[i] });
[javac] ^
[javac] Note: * uses or overrides a deprecated API.
[javac] Note: Recompile with -Xlint:deprecation for details.
[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.
[javac] 1 warning

install_code:
[copy] Copying 5 files to /home/dspace/lib
[jar] Building jar: /home/dspace/lib/dspace.jar

build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.2.2-source/build
[mkdir] Created dir: /home/dspace/dspace-1.2.2-source/jsp/local
[mkdir] Created dir: /home/dspace/dspace-1.2.2-source/build/jsp
[copy] Copying 194 files to /home/dspace/dspace-1.2.2-source/build/jsp
[war] Building war: /home/dspace/dspace-1.2.2-source/build/dspace.war
[copy] Copying 1 file to /home/dspace/dspace-1.2.2-source/build
[war] Building war: /home/dspace/dspace-1.2.2-source/build/dspace-oai.war

update:
[echo]
[echo] ====================================================================
[echo] Updated Web application (.war) files are in the 'build' directory.
[echo]
[echo] * Stop your Web servlet container (Tomcat, Jetty, Resin etc.)
[echo]
[echo] * If you're using Tomcat, you need delete the directories
[echo] corresponding to the old .war files. For example, if dspace.war
[echo] is installed in CATALINA_HOME/webapps/dspace.war, you should
[echo] delete the CATALINA_HOME/webapps/dspace directory. Otherwise,
[echo] Tomcat will continue to use the old code in that directory.
[echo]
[echo] * Copy the new dspace.war and dspace-oai.war from the 'build'
[echo] directory over the old ones
[echo]
[echo] * Start up your Web servlet container again.
[echo] ====================================================================
[echo]

BUILD SUCCESSFUL
Total time: 10 seconds

Removed all the old files and directories associated with DSpace form the tomcat/webapps directory:

[dspace@cd ~]$ cd tomcat/webapps
[dspace@cd webapps]$ rm -rf dspace*

Copied over the new .war files into the tomcat/webapps directory:

[dspace@cd ~]$ cd dspace-1.2.2-source/build
[dspace@cd build]$ cp dspace*.war /home/dspace/tomcat/webapps

Copied over the input-forms.xml file and then restarted Tomcat and the handle-server:

[dspace@cd ~]$ cd dspace-1.2.2-source/config
[dspace@cd config]$ cp input-forms.xml /home/dspace/config

[dspace@cd config]$ su - root
Password:
[root@cd ~]# service tomcat start

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

[root@cd ~]# service handle start
[root@cd ~]# exit

Hurray DSpace still works :-)))

Correcting the telephone number (again)

19th May 2005 - The only problem I have encountered with the upgrade is that the contact phone number has been reset to the default value. To correct this I followed a slightly modified version of the procedure given above for changing the phone number in DSpace 1.2.1

The procedure I followed was:

Logged on as user dspace and edited the contact info configuration file:

[dspace@cd ~]$ nano dspace-1.2.2-source/jsp/components/contact-info.jsp

and changed the text shown in bold:

td class="standard" Or telephone: /td
td class="standard" 020 8295 7000 x7144 /td

(Please note that in the lines above the opening and closing html tags have been removed as otherwise the blog does not display properly.)

I then rebuilt DSpace as shown below:

[dspace@cd components]$ cd /home/dspace/dspace-1.2.2-source
[dspace@cd dspace-1.2.2-source]$ ant -Dconfig=/home/dspace/config/dspace.cfg build_wars
Buildfile: build.xml
compile:
build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.2.2-source/build/jsp
[war] Building war: /home/dspace/dspace-1.2.2-source/build/dspace.war
BUILD SUCCESSFUL
Total time: 4 seconds

I then stopped Tomcat as root:

[dspace@cd dspace-1.2.2-source]$ su - root
Password:
[root@cd ~]# service tomcat stop
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

I then exited back to user DSpace and removed the tomcat dspace directory:

[root@cd ~]# exit
logout
[dspace@cd dspace-1.2.2-source]$ rm -rf /home/dspace/tomcat/webapps/dspace

I then copied over the dspace.war file into the webapps directory:

[dspace@cd dspace-1.2.2-source]$ cp /home/dspace/dspace-1.2.2-source/build/dspace.war /home/dspace/tomcat/webapps

I then restarted Tomcat as root:

[dspace@cd dspace-1.2.2-source]$ su - root
Password:
[root@cd ~]# service tomcat start

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
[root@cd ~]# exit
logout

The modified telephone number now displayed correctly.

Return to Menu

11) Customising the Web User Interface

Now that DSpace has been installed on one of our new mission critical servers I wanted to extensively customise the web interface so that it matched the theme already employed on the College Website and Moodle VLE.

I found the customisation information on the DSpace Website a useful starting point.

I logged on as user DSpace and moved to the jsp directory:

cd dspace-1.2.2-source/jsp

I then created two subdirectories of local as follows:

mkdir local/image
mkdir local/layout

I then copied the following files as shown below:

cp image/arrow.gif local/image
cp image/search-go.gif local/image
cp styles.css.jsp local
cp layout/header-default.jsp local/layout

I then spent a long time customising the files local/styles.css.jsp and local/layout/header-default.jsp - the only real way I found of doing this was trial and error until eventually I got the desired effect

This proved very time consuming as after each change I had to su to root and stop tomcat before returning to user DSpace and recompiling DSpace as shown below:

ant -Dconfig=[dspace]/config/dspace.cfg build_wars
rm -rf /home/dspace/tomcat/webapps/dspace
cp /home/dspace/dspace-1.2.2-source/build/dspace.war /home/dspace/tomcat/webapps

I then had to su to root again to restart tomcat before I could preview my changes in the browser.

I also had to alter the graphics files in local/image to suit the new theme, which involved using The GIMP at one point.

You can see my completed themed interface by visting http://vle.bromley.ac.uk/dspace

I addition to customising the interface I also customised (customized) the default DSpace licence (license) agreement so that it related to Bromley College and not DSpace University (DSU). This was a two stage procedure.

Firstly, I edited the default license file at /home/dspace/dspace-1.2.2-source/config/default.license and then recompiled DSpace. (However, this did not change the license agreements associated with pre-existing collections.)

Secondly, in order to change the licence agreements associated with pre-existing collections I had to log onto DSpace as administrator and change the license agreement associated with each collection individually. I found that I had to insert a br tag at the beginning of every other line within the dialog box in order to make the layout of the completed agreement acceptable.

Return to Menu

12) Virus scanning and establishing a hot backup server

With the DSpace Repository and Moodle VLE becoming mission critical this summer we needed to have a backup server that could be brought online at a moments notice in case the there were problems with the main server.

We bought in two identical rack mount servers from Dell each with twin 3.2GHz Xeon processors, 3 x 73GB hard drives in a RAID 5 hardware array and 4GB of RAM. I installed CentOS 4 on both servers with no problems at all during the actual installation.

The two servers are to be placed in different server room locations in the College and will have Internet/Intranet access via a hardware NAT firewall.

I have decided that either server can be booted into one of three modes:

1) Main - provides Web Services
2) Backup - provides Backup services for the main server
3) Standby - an intermediate mode

Each mode has its own external IP address and domain name.

When a server is in Main mode a cron.daily script runs a backup script from the root users bin folder. This script scans the DSpace and Moodle asset store folders for Windows viruses and uses rsync to synchronise the build on the Main server with the build on the Backup server.

Additionally it also uses rsync to separately backup the DSpace and Moodle builds and databases on Sunday morning and the 28th of each month.

This script is illustrated below:

[root@cc bin]# cat backup
/usr/local/bin/freshclam --quiet
echo "Moodle anti-virus scan"
/usr/local/bin/clamscan --infected --move=/home/infected -r /home/bcvle
echo " "
echo "Dspace anti-virus scan"
/usr/local/bin/clamscan --infected -r /home/dspace/assetstore
echo " "
service mysqld stop
service postgresql stop
rsync -av --delete --exclude "/sys/" --exclude "/media/" --exclude "/proc/" --exclude "/dev/pts/" --exclude "/var/run/" --exclude "/var/log/" --exclude "/etc/cups/" --exclude "/var/lock/" --exclude "/etc/hosts" --exclude "/etc/sysconfig/network" --exclude "/etc/sysconfig/network-scripts/" --exclude "/var/lib/mrtg/mrtg.ok" --exclude "/var/lib/slocate/" --exclude "/var/lib/slocate/slocate.db" --exclude "/var/lib/ntp/" --exclude "/root/.bashrc" --exclude "/home/clive/.bashrc" --exclude "/etc/cron.weekly/dspace" --exclude "/home/backup/" --exclude "/etc/mail/sendmail.cf" --exclude "/var/spool/mail/" --exclude "/var/spool/mqueue/" --exclude "/var/spool/clientmqueue/" --exclude "/root/bin/backup" --exclude "/etc/rc.d/rc.local" --exclude "/var/spool/cron/dspace" --exclude "/etc/rsyncd.conf" / 172.31.0.6::backup
rsync /var/log/freshclam.log 172.31.0.6::backup/var/log
if test $(date cut -c-3) = Sun
then
echo "Weekly backup"
service httpd stop
service tomcat stop
service handle stop
rsync -av --delete /home/dspace /home/backup/weekly
rsync -av --delete /home/bcvle /home/backup/weekly
rsync -av --delete /home/bcvleuser /home/backup/weekly
rsync -av --delete /var/lib/mysql/bcvle /home/backup/weekly/mysql
rsync -av --delete /var/lib/pgsql/data /home/backup/weekly/pgsql
sleep 30
service httpd start
service tomcat start
service handle start
fi
if test $(date cut -c9-10) = 28
then
echo "Monthly backup"
sleep 30
service httpd stop
service tomcat stop
service handle stop
rsync -av --delete /home/dspace /home/backup/monthly
rsync -av --delete /home/bcvle /home/backup/monthly
rsync -av --delete /home/bcvleuser /home/backup/monthly
rsync -av --delete /var/lib/mysql/bcvle /home/backup/monthly/mysql
rsync -av --delete /var/lib/pgsql/data /home/backup/monthly/pgsql
sleep 30
service httpd start
service tomcat start
service handle start
fi
service postgresql start
service mysqld start

The following scripts are used to switch the server between the modes:

[root@cc bin]# cat 0mkmain
# "This script puts a server into MAIN mode"
cp -f /root/bin/0Mainfiles/dspace /etc/cron.weekly
cp -f /root/bin/0Mainfiles/hosts /etc/hosts
cp -f /root/bin/0Mainfiles/ifcfg-eth0 /etc/sysconfig/network-scripts/ifcfg-eth0
cp -f /root/bin/0Mainfiles/rc.local /etc/rc.d/rc.local
cp -f /root/bin/0Mainfiles/network /etc/sysconfig/network
cp -f /root/bin/0Mainfiles/backup /root/bin/backup
cp -f /root/bin/0Mainfiles/sendmail.cf /etc/mail
cp -f /root/bin/0Mainfiles/dspacecron /var/spool/cron/dspace
rm -rf /etc/rsyncd.conf &> /dev/null
echo "[ctrl]+[c] will cancel a running shutdown"
shutdown -r +1

[root@cc bin]# cat 0mkback
# This script puts the server into BACKUP mode"
echo "If this is the main server do you need to run the backup script first?"
cp -f /root/bin/0Backupfiles/rsyncd.conf /etc/rsyncd.conf
cp -f /root/bin/0Backupfiles/hosts /etc/hosts
cp -f /root/bin/0Backupfiles/ifcfg-eth0 /etc/sysconfig/network-scripts/ifcfg-eth0
cp -f /root/bin/0Backupfiles/rc.local /etc/rc.d/rc.local
cp -f /root/bin/0Backupfiles/network /etc/sysconfig/network
cp -f /root/bin/0Backupfiles/backup /root/bin/backup
cp -f /root/bin/0Backupfiles/sendmail.cf /etc/mail
rm -rf /etc/cron.weekly/dspace &> /dev/null
crontab -u dspace -r
echo "[ctrl]+[c] will cancel a running shutdown"
shutdown -r +1

[root@cc bin]# cat 0mkstnd
# "This script puts a server into STANDBY mode"
cp -f /root/bin/0Standbyfiles/hosts /etc/hosts
cp -f /root/bin/0Standbyfiles/ifcfg-eth0 /etc/sysconfig/network-scripts/ifcfg-eth0
cp -f /root/bin/0Standbyfiles/rc.local /etc/rc.d/rc.local
cp -f /root/bin/0Standbyfiles/network /etc/sysconfig/network
cp -f /root/bin/0Standbyfiles/backup /root/bin/backup
cp -f /root/bin/0Standbyfiles/sendmail.cf /etc/mail
rm -rf /etc/cron.weekly/dspace &> /dev/null
crontab -u dspace -r
echo "[ctrl]+[c] will cancel a running shutdown"
shutdown -r +1

By logging into both servers using ssh it is possible to switch modes quickly and easily using the above scripts.

Return to Menu

1) Upgrading to DSpace 1.3.1

These upgrade instructions are specifically written for CentOS 4. I am using Fedora Core 3 on several other servers, but am not running DSpace on these servers any more.

I initially upgraded to Dspace 1.3 only to find that 1.3.1 came out the next morning! These upgrade instructions are written for the upgrade from 1.2.2 to 1.3.1. These instructions follow on from earlier items in this blog and assume that DSpace 1.2.2 is already installed in /home/dspace.

Back up up all your data before proceeding. Include all of the contents of /home/dspace and the /var/lib/pgsql/data in your backup. Have a look at the rsync commands in the backup script in the previous section in this blog if you need help with backup.

Login as the dspace user and download dspace-1.3.1-source.tar.gz into /home/dspace using the command:

lynx http://sourceforge.net/project/showfiles.php?group_id=19984

Unpack the new installation using the following command:

cd /home/dspace
tar -xzvf dspace-1.3.1-source.tar.gz
rm *.gz

I needed to find the update documentation so I used the following commands to copy over the docs folder into the Apache webserver root directory from where I could read it using a browser:

cd dspace-1.3.1-source
su root
cp -pr docs /var/www/html
exit

From now on this upgrade follows the procedure given in the upgrade.html document.

Copy the PostgreSQL driver JAR from the 1.2.2 source directory to the 1.3.1 source directory:

cp /home/dspace/dspace-1.2.2-source/lib/pg74.215.jdbc3.jar /home/dspace/dspace-1.3.1-source/lib

(Note that there was a problem with the upgrade documentation that I downloaded in that it included the following command, which is an error: cp postgresql.jar [dspace-1.2.2-source]/lib)

Remove the old version of xerces.jar from your installation, so it is not inadvertently later used:

rm /home/dspace/lib/xerces.jar

Take down Tomcat and the handle-server:

su - root
service tomcat stop
service handle stop
exit

Install the new config files by moving dstat.cfg and dstat.map:

cp /home/dspace/dspace-1.3.1-source/config/dstat* /home/dspace/config

You need to append the following new parameters to /home/dspace/config/dspace.cfg:

###### Statistical Report Configuration Settings ######

# should the stats be publicly available? should be set to false if you only
# want administrators to access the stats, or you do not intend to generate
# any
report.public = false

# directory where live reports are stored
report.dir = /home/dspace/reports/

I suggest you leave customising the statistics feature until after the upgrade is complete. The instructions in section 14 of this blog explain how to get statistics working.

If the Web interface has been customised, copy over any custom interface files:

cp /home/dspace/dspace-1.2.2-source/jsp/components/contact-info.jsp /home/dspace/dspace-1.3.1-source/jsp/components/contact-info.jsp

cp -pr /home/dspace/dspace-1.2.2-source/jsp/local /home/dspace/dspace-1.3.1-source/jsp

(Note: If the interface hasn't been customised you can miss out the above step)

Build and install the updated DSpace 1.3.1 code. Go to the /home/dspace/dspace-1.3.1-source directory, and run:

ant -Dconfig=/home/dspace/config/dspace.cfg update

Buildfile: build.xml

compile:

install_code:
[copy] Copying 1 file to /home/dspace/lib
[jar] Building jar: /home/dspace/lib/dspace.jar

build_wars:
[copy] Copying 2 files to /home/dspace/dspace-1.3.1-source/build/jsp
[copy] Copying 6 files to /home/dspace/dspace-1.3.1-source/build/jsp
[war] Building war: /home/dspace/dspace-1.3.1-source/build/dspace.war
[war] Building war: /home/dspace/dspace-1.3.1-source/build/dspace-oai.war

update:
[echo]
[echo] ====================================================================
[echo] Updated Web application (.war) files are in the 'build' directory.
[echo]
[echo] * Stop your Web servlet container (Tomcat, Jetty, Resin etc.)
[echo]
[echo] * If you're using Tomcat, you need delete the directories
[echo] corresponding to the old .war files. For example, if dspace.war
[echo] is installed in CATALINA_HOME/webapps/dspace.war, you should
[echo] delete the CATALINA_HOME/webapps/dspace directory. Otherwise,
[echo] Tomcat will continue to use the old code in that directory.
[echo]
[echo] * Copy the new dspace.war and dspace-oai.war from the 'build'
[echo] directory over the old ones
[echo]
[echo] * Start up your Web servlet container again.
[echo] ====================================================================
[echo]

BUILD SUCCESSFUL
Total time: 6 seconds

In order to modify the existing PostgreSQL database structure to meet the requirements of DSpace 1.3.1 is necessary to run the database_schema_12-13.sql file.

To apply the changes, go to the 1.3.1 source directory, and run:

[dspace@cc dspace-1.3.1-source]$ cd etc
[dspace@cc etc]$ psql -f database_schema_12-13.sql dspace -h localhost
Password:
CREATE SEQUENCE
psql:database_schema_12-13.sql:60: NOTICE: CREATE TABLE / PRIMARY KEY
will create implicit index "epersongroup2item_pkey" for table
"epersongroup2workspaceitem"
CREATE TABLE
ALTER TABLE
ALTER TABLE
psql:database_schema_12-13.sql:70: NOTICE: ALTER TABLE / ADD UNIQUE
will create implicit index "eperson_netid_key" for table "eperson"
ALTER TABLE
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX
CREATE INDEX

Rebuild the search indices:
./index-all
Creating browse index
Indexing all Items in DSpace.... ... Done
Creating search index
Done with indexing

Remove any old dspace Tomcat files:
rm -rf /home/dspace/tomcat/webapps/*dspace*

Copy over new .war files:

cp /home/dspace/dspace-1.3.1-source/build/*.war /home/dspace/tomcat/webapps

Restart tomcat and the handle server

su - root
service tomcat start
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
service handle start
exit

Hurray DSpace 1.3.1 works :-)))

Subsequently I noticed that some images associated with the item submission process could no longer be found. I located these in last month's backup of DSpace 1.2.2 and copied them over into the /home/dspace/dspace-1.3.1-source/jsp/images/submit directory and rebuilt DSpace. The images now appear correctly during the submission process.

Return to Menu

14) Getting statistics working

I order to get statistics working I edited the
/home/dspace/config/dstat.cfg file and made the following changes to the file:

# the log directory to be analysed
dspace.log=/home/dspace/log

# The item types in the archive that you need number breakdowns on
item.type=Animation
item.type=Article
item.type=Book
item.type=Book chapter
item.type=Dataset
item.type=Learning Object
item.type=Image
item.type=Image, 3D
item.type=Map
item.type=Musical Score
item.type=Plan or Blueprint
item.type=Preprint
item.type=Presentation
item.type=Recording, acoustical
item.type=Recording, musical
item.type=Recording, oral
item.type=Software
item.type=Technical Report
item.type=Thesis
item.type=Video
item.type=Working Paper
item.type=Other

# the name and url of the service being reported on
host.name=DSpace at Bromley College
host.url=http://vle.bromley.ac.uk/dspace

I then moved to the directory /home/dspace/bin and edited each of the following scripts in turn, changing the default path for the dspace home directory from /dspace to /home/dspace where appropriate:

stat-initial
stat-report-initial
stat-monthly
stat-report-monthly
stat-general
stat-report-general

In order to initialise the statistics feature, I then ran each of the above scripts in turn from the command line, as user dspace.

The function of each script (thanks to Richard Jones for help in understanding these) is given below:

stat-initial: analyses the dspace logs (the analyser will perform its actions on any file which conforms to the regular expression: "dspace\.log.*") and generates monthly data files for all the complete months from the beginning of January to the end of the previous month. The data files (.dat) are placed in the log directory.

stat-report-initial: generates an HTML output from each of above monthly data files and places the HTML files in the reports directory.

stat-monthly: analyses the dspace logs and generates a data file for the current month.

stat-report-monthly: generates an HTML output from the current months' data file.

stat-general: analyses the dspace logs and generates a data file from the start to the end of the logs.

stat-report-general: generates an HTML output from above data file. This script generates the default statistics home page, headed "Most recent general report".

At this point I revisited https://vle.bromley.ac.uk/dspace/statistics and found the statistics were now available :-)))

I then added the following lines to the dspace crontab:

# Run the dspace analysis scripts
30 2 * * * /home/dspace/bin/stat-monthly
0 3 * * * /home/dspace/bin/stat-general
# Run the dspace reporting scripts
30 3 * * * /home/dspace/bin/stat-report-monthly
0 4 * * * /home/dspace/bin/stat-report-general

With the above settings the current months' report and the most recent general report is updated every night.

I noticed that the only period with relevant Web statistics available was the current week. I presumed that this was because I had set up a shell script /etc/cron.weekly/dspace to rotate the dspace logs every Sunday morning. In order to retain more useful log information for statistics purposes I have commented out the following lines in the above file:

# mv /home/dspace/log/*20* /home/dspace/log.old
# cp /home/dspace/log/*log /home/dspace/log.old
# cat /dev/null > /home/dspace/log/dspace.log

Return to Menu

15) Modified handle server configuration

I am in the process of changing the hostname of the server running Moodle and DSpace and have noted that the handle-server configuration has changed recently.

The modified handle server configuration that I used with DSpace 1.3.1 is illustrated below:

dsrun net.handle.server.SimpleSetup /home/dspace/handle-server

To configure your new Handle or Caching server,
please answer the questions which follow; default
answers, shown in [square brackets] when available,
can be chosen by pressing Enter.

Will this be a caching server or a regular handle server?

1 - regular Handle Server (Recommended)
2 - caching Handle Server

Please choose 1 or 2 and press Enter [1]:

Will this be a "primary" server (ie, not a mirror of another server)?(y/n) [y]:

Through what IP address will this server be accessible? (Domain names
are OK) [10.200.0.14]:

Enter the (TCP/UDP) port number this server will listen to [2641]:

What port number will the HTTP interface be listening to? [8000]:

Would you like to log all accesses to this server?(y/n) [n]: y

Please indicate whether log files should be automatically
rotated, and if so, how often.

("N" (Never), "M" (Monthly), "W" (Weekly), or "D" (Daily))? [Never] : M

NOTE: Auto-saves and restarts will be done on the first of each month.

Select a time of day for the saving and restarting (HH:MM:SS)
[00:00:00]:

Enter the full pathname of the directory where saved logs should be stored
[/home/dspace/handle-server]:

Each handle site has a version/serial number assigned
to it. This is so that a client can tell if a particular
site's configuration has changed since the last time it
accessed a server in the site. Every time you modify a site
(by changing an IP address, port, or adding a server, etc),
you should increment the version/serial number for that site.

Enter the version/serial number of this site [1]:

Please enter a short description of this server/site: Bromley College
DSpace Repository

Please enter the name of your organization: Bromley College

Please enter the name of a contact person for Bromley College (optional) [(none)]: Clive Gould

Please enter the telephone number of Clive Gould or of Bromley College
(optional) [(none)]: 020 8295 7000

Please enter the email address of Clive Gould or of Bromley College:
xyz@.bromley.ac.uk

The Handle System can communicate via UDP and/or TCP sockets.
Since UDP messages are blocked by many network firewalls, you may
want to disable UDP services if you are behind such a firewall.

Would you like to disable UDP services?(y/n) [n]: y

Server keys already exist, do you want to create new ones? (y/n) [n]:

Administrator keys already exist, do you want to create new ones? (y/n) [n]:
Generating site info record...

-------------------------------------------------------

Finished configuring regular (primary) Handle Server.

In order for the outside world to find your site, you will
need to have a naming authority and a reference to your
site in the root handle service.

To request a naming authority, please visit
http://hdl.handle.net/4263537/5014

I visited the above web page and filled in the form, including both our internal and external IP addresses and attaching sitebndl.zip and within a very short time I got an email from CNRI to say that our existing handle prefix had been updated in their database.

Handles would not resolve properly as the new server was behind a hardware firewall.

We opened firewall ports 2641 and 8000 to incoming and outgoing traffic and all was well.

Return to Menu

16) Upgrading to DSpace 1.3.2

These upgrade instructions are specifically written for CentOS 4. I am using Fedora Core 3 on several other servers, but am not running DSpace on these servers any more.

These instructions follow on from earlier items in this blog and assume that DSpace 1.3.1 is already installed in /home/dspace.

Back up up all your data before proceeding. Include all of the contents of /home/dspace and the /var/lib/pgsql/data in your backup. Have a look at the rsync commands in the backup script in the previous section in this blog if you need help with backup.

Login as the dspace user and download dspace-1.3.2-source.tar.gz into /home/dspace using the command:

lynx http://heanet.dl.sourceforge.net/sourceforge/dspace/dspace-1.3.2-source.tar.gz

Unpack the new installation using the following command:

cd /home/dspace
tar -xzvf dspace-1.3.2-source.tar.gz
rm *.gz

Copy the PostgreSQL driver JAR from the 1.3.1. source directory to the 1.3.2 source directory:

cp /home/dspace/dspace-1.3.1-source/lib/pg74.215.jdbc3.jar /home/dspace/dspace-1.3.2-source/lib

Take down Tomcat and the handle-server:

su - root
service tomcat stop
service handle stop
exit

Make a backup copy of the new 1.3.2 dspace.cfg file and just copy over the old version of dspace.cfg unless you are using either SRB File Storage or LDAP Authentication:

cp /home/dspace/dspace-1.3.2-source/config/dspace.cfg /home/dspace/dspace-1.3.2-source/config/dspace.cfg.default

cp /home/dspace/dspace-1.3.1-source/config/dspace.cfg /home/dspace/dspace-1.3.2-source/config

If the Web interface has been customised, copy over any custom interface files. For example:

cp /home/dspace/dspace-1.3.1-source/jsp/components/contact-info.jsp /home/dspace/dspace-1.3.2-source/jsp/components/contact-info.jsp

cp -pr /home/dspace/dspace-1.3.1-source/jsp/local /home/dspace/dspace-1.3.2-source/jsp

Build and install the updated DSpace 1.3.2 code. Go to the /home/dspace/dspace-1.3.2-source directory, and run:

ant -Dconfig=/home/dspace/config/dspace.cfg update

Buildfile: build.xml

compile:
[mkdir] Created dir: /home/dspace/dspace-1.3.2-source/build/classes
[javac] Compiling 151 source files to
/home/dspace/dspace-1.3.2-source/build/classes
[javac] Note: * uses or overrides a deprecated API.
[javac] Note: Recompile with -Xlint:deprecation for details.

install_code:
[copy] Copying 1 file to /home/dspace/lib
[jar] Building jar: /home/dspace/lib/dspace.jar

build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.3.2-source/build
[mkdir] Created dir: /home/dspace/dspace-1.3.2-source/build/jsp
[copy] Copying 194 files to /home/dspace/dspace-1.3.2-source/build/jsp
[copy] Copying 6 files to /home/dspace/dspace-1.3.2-source/build/jsp
[copy] Copying 1 file to /home/dspace/dspace-1.3.2-source/build/classes
[war] Building war: /home/dspace/dspace-1.3.2-source/build/dspace.war
[copy] Copying 1 file to /home/dspace/dspace-1.3.2-source/build
[war] Building war: /home/dspace/dspace-1.3.2-source/build/dspace-oai.war

update:
[echo]
[echo] ====================================================================
[echo] Updated Web application (.war) files are in the 'build' directory.
[echo]
[echo] * Stop your Web servlet container (Tomcat, Jetty, Resin etc.)
[echo]
[echo] * If you're using Tomcat, you need delete the directories
[echo] corresponding to the old .war files. For example, if dspace.war
[echo] is installed in CATALINA_HOME/webapps/dspace.war, you should
[echo] delete the CATALINA_HOME/webapps/dspace directory. Otherwise,
[echo] Tomcat will continue to use the old code in that directory.
[echo]
[echo] * Copy the new dspace.war and dspace-oai.war from the 'build'
[echo] directory over the old ones
[echo]
[echo] * Start up your Web servlet container again.
[echo] ====================================================================
[echo]

BUILD SUCCESSFUL
Total time: 13 seconds

Remove any old dspace Tomcat files:

rm -rf /home/dspace/tomcat/webapps/*dspace

Copy over new .war files:

cp /home/dspace/dspace-1.3.2-source/build/*.war /home/dspace/tomcat/webapps

Restart tomcat and the handle server

su - root
service tomcat start
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
service handle start
exit

Hurray DSpace 1.3.2 works :-)))

I found I needed to update the customised styles.css.jsp in jsp/local so that it included the new additions introduced in the default styles.css.jsp as supplied with the DSpace 1.3.2 distribution.

I then noticed that W3C XHTML validation came up with errors. This was due to the customised jsp's I originally created in DSpace 1.2.2 having been copied into subsequent versions of DSpace. I took the relevant default jsp's that came with DSpace 1.3.2 and customised them to suit our in-house theme. I also had to change the tags used in the news and sidebar pages from uppercase to lowercase. As a result of these changes validation now works properly.

Return to Menu

17) Providing OAI access to DSpace

For an introduction to OAI for beginners please select this link.

For a guide to configuring OAI with DSpace please select this link.

In order to enable OAI access to DSpace I followed this procedure:

As root stop the tomcat and handle servers:

su - root
service tomcat stop
service handle stop
exit

As user dspace copy over dspace-oai.war as follows:

cp /home/dspace/dspace-1.3.2-source/build/dspace-oai.war /home/dspace/tomcat/webapps

As root restart tomcat and the handle server:

su - root
service tomcat start
service handle start

Edit /etc/httpd/conf/workers2.properties

Add the following lines to the end of workers2.properties:

[uri:/dspace-oai/*]
context=/dspace-oai

Save the file and restart Apache:

service httpd restart
Stopping httpd: [ OK ]
Starting httpd: [ OK ]

On visiting the following URL on our site:

http://vle.bromley.ac.uk/dspace-oai/request?verb=Identify

the appropriate xml page appears in the browser :-)

The repository can now be registered with the Open Archives Initiative as a data provider.

The base URL of our site for OAI registration purposes was:

http://vle.bromley.ac.uk/dspace-oai/request

i.e. everything up to the ? is your base url.

Once registered with the Open Archives Initiative the repository will be harvested regularly and will be searchable from Oaister

(Thanks to Henk Meij for his invaluable advice on getting this working and for pointing me to the appropriate Dspace documentation that I'd missed :-)

Return to Menu

18) Using a commercial wildcard SSL certificate

The College uses a wildcard SSL certificate provided by GlobalSign for the bromley.ac.uk domain. In order to harmonise with the other servers in the College I decided to replace the self-signed certificate as created in section 7 above with the College certificate.

I logged in as root and backed up the certwork directory to be on the safe side :-)

cp -pr /root/certwork /root/certworkback

I moved to the directory certwork into which I had already uploaded the .pfx file provided to me.

cd /root/certwork

I ran the following command to extract the server key and relevant certificates from the .pfx file:

openssl pkcs12 -in 2006BromleyWildforMoodle.pfx -out outputfile.txt -nodes

enter password: xxxxxxx

The password used above was provided along with the .pfx file.

The file outputfile.txt contained the server private key and the certificates in plain text format.

I extracted the key and certificate files in turn from outputfile.txt

The first item in the outputfile was the server key. I cut and pasted everything from -----BEGIN RSA PRIVATE KEY ----- to -----END RSA PRIVATE KEY----- inclusive into a file called server.key

less outputfile.txt
pico server.key

The second item in the outputfile was the Bromley Wild server certificate. I cut and pasted everything from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- inclusive into a file called server.crt

less outputfile.txt
pico server.crt

The remaining three items in the outputfile were the GloabalSign certificates. I cut and pasted each of the remaining certificates in turn as shown below:

less outputfile.txt
pico gs-root.crt

less outputfile.txt
pico gs-primserver.crt

less outputfile.txt
pico gs-serversign.crt

I generated a public Certificate Signing Request (CSR) for the server as follows:

openssl req -new -key server.key -out server.csr

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:GB
State or Province Name (full name) [Berkshire]:Kent
Locality Name (eg, city) [Newbury]:Bromley
Organization Name (eg, company) [My Company Ltd]:Bromley College
Organizational Unit Name (eg, section) []:Bromley College
Common Name (eg, your name or your server's hostname) []:vle.bromley.ac.uk
Email Address []:root@vle.bromley.ac.uk

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

This created the file server.csr

I created an "insecure" server key to prevent Apache asking for a password every time I tried to restart the httpd process:

openssl rsa -in server.key -out server.key.insecure
writing RSA key

I copied over the relevant keys, CSR's and certificates ready for Apache to use:

cp gs* /etc/httpd/conf/ssl.crt
cp server.crt /etc/httpd/conf/ssl.crt
cp server.csr /etc/httpd/conf/ssl.csr
cp server.key.insecure /etc/httpd/conf/ssl.key/server.key

To be on the safe side I also changed the permissions of the above files to 600 as shown below:

chmod 600 /etc/httpd/conf/ssl.key/*
chmod 600 /etc/httpd/conf/ssl.crt/*
chmod 600 /etc/httpd/conf/ssl.csr/*

I then restarted Apache:

[root@cd certwork]# service httpd restart
Stopping httpd: [ OK ]
Starting httpd: [ OK ]

When I visited DSpace from a browser the new certificate was successfully presented for acceptance :-)

Return to Menu

20) Upgrading to DSpace 1.4 (failed)

Please do not follow these instructions as I have been unable so far to successfully upgrade DSpace 1.3.2 to DSpace 1.4 on a CentOS 4.3 platform.

The information below is intended to document the process I followed to help myself and the community:

After several failed upgrades from DSpace 1.3.2 on CentOS 4.3 I decided to try again one last time.

I rebuilt the testvle server from the vle server to remove all traces of DSpace 1.4

I tried out DSpace 1.3.2 on the testvle server and it worked correctly.

As regards the versions of Java and PostgreSQL:

echo $JAVA_HOME
/usr/java/jdk
/usr/java/jdk/bin/java -version
java version "1.5.0_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_04-b05)
Java HotSpot(TM) Server VM (build 1.5.0_04-b05, mixed mode

rpm -q postgresql
postgresql-7.4.13-2.RHEL4.1

I then followed the following upgrade procedure exactly

As user dspace

pwd
/home/dspace

tar -xzvf dspace-1.4-source.tar.gz
(I downloaded the above file freshly from a different mirror)

cd dspace-1.4-source
cd lib
rm -rf pg74*
(to delete any old pg74 .jar files)
lynx http://jdbc.postgresql.org/download.html
(downloaded pg74.216.jdbc2.jar)
cd ../config
rm dspace.cfg
cp /home/dspace/custom/dspace.cfg .

(dspace.cfg was the default file taken from the dspace 1.4 source and edited to include the relevant settings for the testvle server. I deliberately did not copy over custom jsp's to try and keep things as close to the default as possible.)

cd ..
ant -Dconfig=/home/dspace/config/dspace.cfg update
Buildfile: build.xml

compile:
[mkdir] Created dir: /home/dspace/dspace-1.4-source/build/classes
[javac] Compiling 232 source files to
/home/dspace/dspace-1.4-source/build/classes
[javac] Note: * uses or overrides a deprecated API.
[javac] Note: Recompile with -Xlint:deprecation for details.

install_code:
[copy] Copying 7 files to /home/dspace/bin
[copy] Copying 14 files to /home/dspace/lib
[jar] Building jar: /home/dspace/lib/dspace.jar

build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.4-source/build
[mkdir] Created dir: /home/dspace/dspace-1.4-source/jsp/local
[mkdir] Created dir: /home/dspace/dspace-1.4-source/build/jsp
[copy] Copying 216 files to /home/dspace/dspace-1.4-source/build/jsp
[copy] Copying 1 file to /home/dspace/dspace-1.4-source/build/classes
[war] Building war: /home/dspace/dspace-1.4-source/build/dspace.war
[copy] Copying 1 file to /home/dspace/dspace-1.4-source/build
[war] Building war: /home/dspace/dspace-1.4-source/build/dspace-oai.war

update:
[copy] Copying 1 file to /home/dspace/config
[echo]
[echo] ====================================================================
[echo] Copied language packs into /home/dspace/config
[echo]
[echo] ====================================================================
[echo] Updated Web application (.war) files are in the 'build' directory.
[echo]
[echo] * Stop your Web servlet container (Tomcat, Jetty, Resin etc.)
[echo]
[echo] * If you're using Tomcat, you need delete the directories
[echo] corresponding to the old .war files. For example, if dspace.war
[echo] is installed in CATALINA_HOME/webapps/dspace.war, you should
[echo] delete the CATALINA_HOME/webapps/dspace directory. Otherwise,
[echo] Tomcat will continue to use the old code in that directory.
[echo]
[echo] * Copy the new dspace.war and dspace-oai.war from the 'build'
[echo] directory over the old ones
[echo]
[echo] * Start up your Web servlet container again.
[echo] ====================================================================
[echo]

BUILD SUCCESSFUL
Total time: 13 seconds

su - root
service postgresql start
Starting postgresql service: [ OK ]
exit

As user dspace

psql -f etc/database_schema_13-14.sql dspace -h localhost
Password:
CREATE SEQUENCE
CREATE SEQUENCE
psql:etc/database_schema_13-14.sql:61: NOTICE: CREATE TABLE / PRIMARY
KEY will create implicit index "group2group_pkey" for table
"group2group"
CREATE TABLE
psql:etc/database_schema_13-14.sql:77: NOTICE: CREATE TABLE / PRIMARY
KEY will create implicit index "group2groupcache_pkey" for table
"group2groupcache"
CREATE TABLE
CREATE SEQUENCE
CREATE SEQUENCE
CREATE SEQUENCE
psql:etc/database_schema_13-14.sql:93: NOTICE: CREATE TABLE / PRIMARY
KEY will create implicit index "metadataschemaregistry_pkey" for table
"metadataschemaregistry"
psql:etc/database_schema_13-14.sql:93: NOTICE: CREATE TABLE / UNIQUE
will create implicit index "metadataschemaregistry_namespace_key" for
table "metadataschemaregistry"
CREATE TABLE
psql:etc/database_schema_13-14.sql:103: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "metadatafieldregistry_pkey"
for table "metadatafieldregistry"
CREATE TABLE
psql:etc/database_schema_13-14.sql:114: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "metadatavalue_pkey" for table
"metadatavalue"
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE INDEX
INSERT 41400 1
INSERT 0 66
INSERT 0 716
DROP TABLE
CREATE VIEW
setval
--------
66
(1 row)

setval
--------
716
(1 row)

setval
--------
1
(1 row)

DROP TABLE
ALTER TABLE
UPDATE 281
ALTER TABLE
psql:etc/database_schema_13-14.sql:167: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "checksum_results_pkey" for
table "checksum_results"
CREATE TABLE
psql:etc/database_schema_13-14.sql:187: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "most_recent_checksum_pkey" for
table "most_recent_checksum"
CREATE TABLE
psql:etc/database_schema_13-14.sql:202: NOTICE: CREATE TABLE will
create implicit sequence "checksum_history_check_id_seq" for "serial"
column "checksum_history.check_id"
psql:etc/database_schema_13-14.sql:202: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "checksum_history_pkey" for
table "checksum_history"
CREATE TABLE
INSERT 42223 1
INSERT 42224 1
INSERT 42225 1
INSERT 42226 1
INSERT 42227 1
INSERT 42228 1
INSERT 42229 1
INSERT 42230 1
INSERT 42231 1
INSERT 0 281
UPDATE 45
INSERT 0 281
UPDATE 281
ALTER TABLE
CREATE SEQUENCE
psql:etc/database_schema_13-14.sql:355: NOTICE: CREATE TABLE /
PRIMARY KEY will create implicit index "itemsbysubject_pkey" for table
"itemsbysubject"
CREATE TABLE
CREATE INDEX
CREATE VIEW
CREATE VIEW

/home/dspace/bin/index-all
Creating browse index
Indexing all Items in DSpace.... ... Done
Creating search index
Done with indexing

rm -rf /home/dspace/tomcat/webapps/*dspace*
cp /home/dspace/dspace-1.4-source/build/*.war /home/dspace/tomcat/webapps

su - root
service httpd start
Starting httpd: [ OK ]
service tomcat start

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

On visiting the testvle dapace homepage I got exactly the same problem as with previous DSpace 1.4 upgrade attempts.

The default header, footer and navigation bars were correctly displayed, but the centre pane contained the error message:

Internal System Error
The system has experienced an internal error. Please try to do what
you were doing again, and if the problem persists, please contact us
so we can fix the problem.

DSpace at Bromley College administration contact details:

By e-mail: dspace-help@vle.bromley.ac.uk
Or telephone: 020 8295 7000 x7144

Go to the DSpace home page

Clicking on a link on the Navigation bar produced the following error page:

HTTP Status 500 -

type Exception report

message

description The server encountered an internal error () that prevented
it from fulfilling this request.

exception

java.lang.NoClassDefFoundError
org.dspace.app.webui.util.UIUtil.obtainContext(UIUtil.java:118)
org.dspace.app.webui.servlet.DSpaceServlet.processRequest(DSpaceServlet.java:132)
org.dspace.app.webui.servlet.DSpaceServlet.doGet(DSpaceServlet.java:99)
javax.servlet.http.HttpServlet.service(HttpServlet.java:689)
javax.servlet.http.HttpServlet.service(HttpServlet.java:802)

note The full stack trace of the root cause is available in the Apache
Tomcat/5.5.9 logs.

Richard Jones suggested the following:

"According to the errors thrown by pages using servlets (the index page
is an exception in DSpace in the way that it is processed), there is a
missing class in your DSpace instance. Line 118 of UIUtil is:

int[] groupIDs = AuthenticationManager.getSpecialGroups(c, request);

Presumably, then, the AuthenticationManager class is missing, but how
the code compiled without this class is a mystery to me! Can you check
that there exists a class/source file
org.dspace.eperson.AuthenticationManager in the following locations:

a) your source code that you built from (in src/)
b) the built, but as yet undeployed classes (in build/classes)
c) inside the live dspace.jar file (run something like 'jar tf
dspace.jar | grep AuthenticationManager')

Perhaps there has something gone wrong in the build, most likely between
b and c above."

To help debug I tried the locate command:

updatedb
locate AuthenticationManager
/home/dspace/tomcat/webapps/dspace-oai/WEB-INF/classes/org/dspace/eperson/AuthenticationManager.class
/home/dspace/tomcat/webapps/dspace/WEB-INF/classes/org/dspace/eperson/AuthenticationManager.class
/home/dspace/dspace-1.4-source/src/org/dspace/eperson/AuthenticationManager.java
/home/dspace/dspace-1.4-source/build/classes/org/dspace/eperson/AuthenticationManager.class

I then tried:

[dspace@testvle lib]$ jar tf dspace.jar | grep AuthenticationManager
org/dspace/eperson/AuthenticationManager.class

12th August 2006: Several people (Richard Jones and Jonathan Champ) have suggested clearing the Tomcat work cache. I have tried this without success as shown below:

su - root
Password:
This is vle server B
service tomcat stop

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

exit
rm -rf /home/dspace/tomcat/work/*
cd /home/dspace/dspace-1.4-source
!ant

ant -Dconfig=/home/dspace/config/dspace.cfg update
BUILD SUCCESSFUL

rm -rf /home/dspace/tomcat/webapps/*dspace*
cp /home/dspace/dspace-1.4-source/build/*.war /home/dspace/tomcat/webapps
su - root
service tomcat start

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

No luck problem is still there:

java.lang.NoClassDefFoundError
org.dspace.app.webui.util.UIUtil.obtainContext(UIUtil.java:118)

Another problem I've noticed this morning is with the filter-media script:

/home/dspace/bin/index-all
Creating browse index
Indexing all Items in DSpace.... ... Done
Creating search index
Done with indexing
/home/dspace/bin/filter-media
Applying Media Filters
Exception in thread "main" java.lang.ClassCastException: [Ljava.lang.Object;
at org.dspace.app.mediafilter.MediaFilterManager.main(MediaFilterManager.java:160)

When filter-media is run on 1.3.2 it is fine, but on the 1.4 upgrade it fails.

Return to Menu

21) Re-installing DSpace 1.4 (success)

Wednesday 16th August 2006: I have undertaken a fresh install of DSpace 1.4 on the vle server and have copied over all the relevant content from the 1.3.2 installation.

DSpace 1.4 now works fine with all the path information, plus ant, postgresql, java, tomcat, all exactly the same as for the failed upgrade from 1.3.2 to 1.4

Before starting the reinstall it is vital to have a full backup of the entire contents of the directories /home/dspace and the /var/lib/pgsql/data as used with DSpace 1.3.2.

The process I followed is as below:

su - root
service tomcat stop
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
service postgresql stop
Stopping postgresql service: [ OK ]
exit

The following commands pre-suppose that all important files from DSpace 1.3.2 have already been copied into a new directory /home/dspace/custom or are available via rsync from our backup server.

As user dspace remove old installation and copy over custom files:

cd /home/dspace
rm -rf bin
rm -rf config
rm -rf handle-server/
rm -rf history/
rm -rf lib/
rm -rf log*
rm -rf reports
rm -rf search

cp custom/dspace-1.4-source.tar.gz .
tar -xzvf dspace-1.4-source.tar.gz
rm -rf dspace-1.4-source.tar.gz
cp custom/*.jar dspace-1.4-source/lib
cp custom/dspace.cfg.vle dspace-1.4-source/config/dspace.cfg
cp custom/*default.jsp /home/dspace/dspace-1.4-source/jsp/layout
cp custom/styles.css.jsp /home/dspace/dspace-1.4-source/jsp
cp custom/news*.html /home/dspace/dspace-1.4-source/config/
cp custom/*.gif /home/dspace/dspace-1.4-source/jsp/image
cp custom/default.license /home/dspace/dspace-1.4-source/config
su - root

As the root user recreate the dspace database:

service postgresql start
Starting postgresql service: [ OK ]
su - postgres
dropdb dspace
DROP DATABASE
-bash-3.00$ createdb -U dspace -E UNICODE dspace
CREATE DATABASE
exit
exit

As user dspace rebuild dspace and copy over the wars:

cd dspace-1.4-source/
ant fresh_install
rm -rf /home/dspace/tomcat/webapps/*dspace*
rm -rf /home/dspace/tomcat/work/*
dspace-1.4-source]$ cp /home/dspace/dspace-1.4-source/build/*.war /home/dspace/tomcat/webapps

It was also necessary to amend the path in dsrun:

pico /home/dspace/bin/dsrun

Comment out the line:

# java -Xmx256m -classpath $FULLPATH "$@"

and add the following line at the end of the file:

/usr/java/jdk/bin/java -mx2024m -classpath $FULLPATH "$@"

As the root user stop postgresql and restore the original 1.3.2 database from backup:

su - root
service postgresql stop
rsync -av --delete 10.200.0.15::backup/var/lib/pgsql/data /var/lib/pgsq
service postgresql start
Starting postgresql service: [ OK ]
exit

As user dspace run the database upgrade script:

cd dspace-1.4-source/
psql -f etc/database_schema_13-14.sql dspace -h localhost
su - root

As the root user start tomcat:

service tomcat start
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
exit

As user dspace run the index-all and filter-media scripts:

/home/dspace/bin/index-all
Creating browse index
Indexing all Items in DSpace.... ... Done
Creating search index
Done with indexing

/home/dspace/bin/filter-media
Applying Media Filters

su - root

As the root user restore the handle server from backup:

rsync -av --delete 10.200.0.15::backup/home/dspace/handle-server /home/dspace
exit

As user dspace start the handle server:

/home/dspace/bin/start-handle-server
su - root

As the root user sort out the statistics:

rsync -av --delete 10.200.0.15::backup/home/dspace/config/dstat.cfg /home/dspace/custom
rsync -av --delete 10.200.0.15::backup/home/dspace/bin/stat* /home/dspace/bin
rsync -av --delete 10.200.0.15::backup/home/dspace/reports /home/dspace

Hurray after about 20 hours of work our digital repository is now working with DSpace 1.4 :-)))

http://vle.bromley.ac.uk/dspace/

Subsequently Stuart David Lewis pointed out that sort by title and sort by date were not working properly on our installation. Birong Ho kindly posted the following solution on the Tech List:

Stop tomcat and as user dspace edit the following file:

pico /home/dspace/dspace-1.4-source/src/org/dspace/browse/Browse.java

Change the || to && on line 922 of the code:

private static void sortResults(BrowseScope scope, List results)
{
// Currently we only sort ItemsByAuthor, Advisor, Subjects browses
// Modified by Clive on 16th August 2006 || changed to &&
if ((scope.getBrowseType() != ITEMS_BY_AUTHOR_BROWSE)
&& (scope.getBrowseType() != ITEMS_BY_SUBJECT_BROWSE))
{
return;
}

Save the file, rebuild, copy over the wars and restart tomcat and all is well :-)

Subsequently I noticed that the statistics pages were headed "Edinburgh Research Archive" and not Bromley College. This was fixed as user dspace by copying over the dstat.cfg file and then re-running the statistics scripts:

cp /home/dspace/dspace-1.4-source/config/dstat.cfg /home/dspace/config

cd /home/dspace/bin
./stat-initial
./stat-report-initial
./stat-monthly
./stat-report-monthly
./stat-general
./stat-report-general

Return to Menu

21) Upgrading the handle server to version 6.2

This morning I have upgraded the handle server to version 6.2 - I was surprised by how easy it seemed. The documentation that comes with the download of the handle server 6.2 looked pretty daunting until I came across the following web page:

http://www.handle.net/upgrade_6-2_DSpace.html

The process I followed is as shown below:

As user dspace download the software from CNRI:

lynx http://www.handle.net/hs-source/hdl6.2.tar.gz

Unpack the tar.gz archive into the /home/dspace directory:

tar -xzvf hdl6*

Move into the new directory and copy over handle.jar:

cd hdl6*
cp handle.jar /home/dspace/dspace-1.4-source/lib

As root stop tomcat and the existing handle server:

su - root
service tomcat stop
service handle stop
exit

The next task is to rebuild dspace. I have created a simple shell script to do this for me. This script is run as user dspace and the source code is shown below:

cd /home/dspace/dspace-1.4-source
ant -Dconfig=/home/dspace/config/dspace.cfg build_wars
rm -rf /home/dspace/tomcat/webapps/*dspace*
rm -rf /home/dspace/tomcat/work/*
cp /home/dspace/dspace-1.4-source/build/dspace*.war /home/dspace/tomcat/webapps

As the root user it is now just a matter of restarting tomcat and the handle server:

su - root
service tomcat start
service handle start

The new handle server seems to work well, is faster than the old one and provides access to DSpace via http rather than https, which suits us well.

Return to Menu

23) Upgrading to DSpace 1.4.1

After the problems I encountered upgrading from DSpace 1.3.2 to DSpace 1.4 I was apprehensive about trying the upgrade to 1.4.1 - However it worked really well first time :-)

I followed the following upgrade procedure.

Log into the server as user dspace

pwd
/home/dspace

Download dspace-1.4.1-source.tar.gz from SourceForge and unpack it in /home/dspace:

lynx http://sourceforge.net/projects/dspace/
tar -xzvf dspace-1.4.1-source.tar.gz

Change to the dspace-1.4.1-source directory. As root delete the old 1.4 webserver docs directory. Copy over the 1.4.1 docs directory to the webserver root directory. This makes the up-to-date DSpace 1.4.1 documentation readily available over the Web. Also stop Tomcat and the Handle servers at the same time.

cd dspace-1.4.1-source
su - root
rm -rf /var/www/html/docs
cp -pr docs /var/www/html
service tomcat stop
service handle stop
exit

As user dspace copy the PostgreSQL and Handle server JAR files from the 1.4 source directory to the 1.4.1 source directory:

cd /home/dspace
cp dspace-1.4-source/lib/pg74.216.jdbc3.jar dspace-1.4.1-source/lib
cp dspace-1.4-source/lib/handle.jar dspace-1.4.1-source/lib

Copy over dspace.cfg from the 1.4 config directory to the 1.4.1 config directory:

cd dspace-1.4.1-source/config
cp /home/dspace/dspace-1.4-source/config/dspace.cfg .

Edit the freshly copied dspace.cfg and append the following to the end of the file:

#### Multi-file HTML document/site settings #####
#
# When serving up composite HTML items, how deep can the request be for us to
# serve up a file with the same name?
#
# e.g. if we receive a request for "foo/bar/index.html"
# and we have a bitstream called just "index.html"
# we will serve up that bitstream for the request if webui.html.max-depth-guess
# is 2 or greater. If webui.html.max-depth-guess is 1 or less, we would not
# serve that bitstream, as the depth of the file is greater.
#
# If webui.html.max-depth-guess is zero, the request filename and path must
# always exactly match the bitstream name. Default value is 3.
#
webui.html.max-depth-guess = 3

Save the dspace.cfg file.

Copy over any customised JSP's and images from the 1.4 jsp directories to the 1.4.1 jsp directories:

cd /home/dspace/dspace-1.4.1-source/jsp
cp /home/dspace/dspace-1.4-source/jsp/styles.css.jsp .
cp /home/dspace/dspace-1.4-source/jsp/layout/*default.jsp layout
cp /home/dspace/dspace-1.4-source/jsp/image/logo.gif image

Build and install the updated DSpace 1.4.1 code from the dspace-1.4.1-source directory:

cd /home/dspace/dspace-1.4.1-source
ant -Dconfig=/home/dspace/config/dspace.cfg update
Buildfile: build.xml

compile:
[mkdir] Created dir: /home/dspace/dspace-1.4.1-source/build/classes
[javac] Compiling 233 source files to
/home/dspace/dspace-1.4.1-source/build/classes
[javac] Note: * uses or overrides a deprecated API.
[javac] Note: Recompile with -Xlint:deprecation for details.

install_code:
[copy] Copying 2 files to /home/dspace/bin
[copy] Copying 40 files to /home/dspace/lib
- Show quoted text -
[jar] Building jar: /home/dspace/lib/dspace.jar

build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.4.1-source/build
[mkdir] Created dir: /home/dspace/dspace-1.4.1-source/jsp/local
[mkdir] Created dir: /home/dspace/dspace-1.4.1-source/build/jsp
[copy] Copying 220 files to /home/dspace/dspace-1.4.1-source/build/jsp
[copy] Copying 1 file to /home/dspace/dspace-1.4.1-source/build/classes
[war] Building war: /home/dspace/dspace-1.4.1-source/build/dspace.war
[copy] Copying 1 file to /home/dspace/dspace-1.4.1-source/build
[war] Building war: /home/dspace/dspace-1.4.1-source/build/dspace-oai.war

update:
[copy] Copying 1 file to /home/dspace/config
[echo]
[echo] ====================================================================
[echo] Copied language packs into /home/dspace/config
[echo]
[echo] ====================================================================
[echo] Updated Web application (.war) files are in the 'build' directory.
[echo]
[echo] * Stop your Web servlet container (Tomcat, Jetty, Resin etc.)
[echo]
[echo] * If you're using Tomcat, you need delete the directories
[echo] corresponding to the old .war files. For example, if dspace.war
[echo] is installed in CATALINA_HOME/webapps/dspace.war, you should
[echo] delete the CATALINA_HOME/webapps/dspace directory. Otherwise,
[echo] Tomcat will continue to use the old code in that directory.
[echo]
[echo] * Copy the new dspace.war and dspace-oai.war from the 'build'
[echo] directory over the old ones
[echo]
[echo] * Start up your Web servlet container again.
[echo] ====================================================================
[echo]

BUILD SUCCESSFUL
Total time: 18 seconds

Magic :-)))

Remove any old dspace Tomcat files:

rm -rf /home/dspace/tomcat/webapps/*dspace

Copy over the new .war files:

cp /home/dspace/dspace-1.4.1-source/build/*.war /home/dspace/tomcat/webapps

As root start tomcat and the handle server:

su - root
service tomcat start
service handle start
exit

As user dspace copy over the statistics configuration file dstat.cfg from the 1.4 config directory to the 1.4.1 config directory:

cd /home/dspace
cp dspace-1.4-source/config/dstat.cfg dspace-1.4.1-source/config/dstat.cfg

Just to make sure all is well run the index-all, filter-media, and various statistics scripts as user dspace:

cd /home/dspace/bin
./index-all
./filter-media

./stat-initial
./stat-report-initial
./stat-monthly
./stat-report-monthly
./stat-general
./stat-report-general

Hurray DSpace 1.4.1 is now fully operational :-)))

Return to Menu

23) Upgrading to DSpace 1.4.2

I followed the following upgrade procedure.

Log into the server as user dspace

pwd
/home/dspace

Download dspace-1.4.2-source.tgz from SourceForge and unpack it in /home/dspace:

wget http://downloads.sourceforge.net/dspace/dspace-1.4.2-source.tgz
tar -xzvf dspace-1.4.2-source.tgz.1

Change to the dspace-1.4.2-source directory. As root delete the old 1.4.1 webserver docs directory. Copy over the 1.4.2 docs directory to the webserver root directory. This makes the up-to-date DSpace 1.4.2 documentation readily available over the Web. Also stop Tomcat and the Handle servers at the same time.

cd dspace-1.4.2-source
su - root
rm -rf /var/www/html/docs
cp -pr docs /var/www/html
service tomcat stop
service handle stop
exit

As user dspace copy the PostgreSQL and Handle server JAR files from the 1.4.1 source directory to the 1.4.2 source directory:

cd /home/dspace
cp dspace-1.4.1-source/lib/pg74.216.jdbc3.jar dspace-1.4.2-source/lib
cp dspace-1.4.1-source/lib/handle.jar dspace-1.4.2-source/lib

Copy over dspace.cfg from the 1.4.1 config directory to the 1.4.2 config directory:

cd dspace-1.4.2-source/config
cp /home/dspace/dspace-1.4.1-source/config/dspace.cfg .

Copy over any customised JSP's and images from the 1.4.1 jsp directories to the 1.4.2 jsp directories:

cd /home/dspace/dspace-1.4.2-source/jsp
cp /home/dspace/dspace-1.4.1-source/jsp/styles.css.jsp .
cp /home/dspace/dspace-1.4.1-source/jsp/layout/*default.jsp layout
cp /home/dspace/dspace-1.4.1-source/jsp/image/logo.gif image

(Maike Dulk kindly pointed out to me that copying over *default.jsp removed the new features present in the 1.4.2 jsp's.)

Subsequently I customised the default jsp's that came with 1.4.2 and used them instead of the ones I'd copied over from 1.4.1. It proved necessary to amend the contents of the following files: header-default.jsp, footer-default.jsp and navbar-default.jsp. It was not necessary to edit location-bar.jsp and navbar-admin.jsp as they had not changed between 1.4.1 and 1.4.2

Build and install the updated DSpace 1.4.2 code from the dspace-1.4.2-source directory:

cd /home/dspace/dspace-1.4.2-source
ant -Dconfig=/home/dspace/config/dspace.cfg update
Buildfile: build.xml

Remove any old dspace Tomcat files:

rm -rf /home/dspace/tomcat/webapps/*dspace

Copy over the new .war files:

cp /home/dspace/dspace-1.4.2-source/build/*.war /home/dspace/tomcat/webapps

As root start tomcat and the handle server:

su - root
service tomcat start
service handle start
exit

As user dspace copy over the statistics configuration file dstat.cfg from the 1.4.1 config directory to the 1.4.2 config directory:

cd /home/dspace
cp dspace-1.4.1-source/config/dstat.cfg dspace-1.4.2-source/config/dstat.cfg

Just to make sure all is well run the index-all, filter-media, and various statistics scripts as user dspace:

cd /home/dspace/bin
./index-all
./filter-media

./stat-initial
./stat-report-initial
./stat-monthly
./stat-report-monthly
./stat-general
./stat-report-general

Hurray DSpace 1.4.2 is now fully operational :-)))

I subsequently noticed that the statistics pages were not updating properly. On correcting the paths to /home/dspace/... in the following files in /home/dspace/bin and re-running the above statistics report generating scripts, as the dspace user, all was well :-)

stat-monthly
stat-general
stat-report-monthly
stat-report-general

Return to Menu

25) Enabling RADIUS suthentication with DSpace 1.4.2

In order to further enable the College's use of DSpace as a Digital Respository holding both public and private collections the following considerations had to be taken into account:

1)We needed RADIUS authentication to be able to use the same logins for staff and students to DSpace that we already used for the Moodle VLE. If students were not already registered with DSpace we wanted them to be automatically registered on their first login.

2)We needed to restrict access to certain collections based on group membership. Consequently following successful authentication we wanted users to be added automatically to pre-existing DSpace groups.

Marcelo Rodrigues of IRICUP- Reitoria da Universidade do Porto had already completed a RADIUS module for DSpace and it was just a question of getting it installed and authenticating against our Windows IAS server.

(Marcelo kindly provided me with invaluable support in translating the installation documentation from Portuguese, configuring the RADIUS module and interfacing it to Freeradius. I am also grateful to members of the Freeradius mailing list (especially Claudiu Filip), who provided me with invaluable help.)

In order to get round problems with the shared secret on the Windows IAS server and to support automatic addition of authorised users to groups in DSpace I decided to install a Freeradius proxy server between DSpace and the Windows IAS server. The authentication process is summarised below:

DSpace <-----> Freeradius <-----> Windows IAS <-----> Windows AD

This is the procedure I followed to install the RADIUS authentication module:

As user dspace download radius.tar.gz

cd /home/dspace
tar -xzvf radius-dspace.tar.gz
cd modulo-radius0.5_11_july/
cd source_code
cp -r src /home/dspace/dspace-1.4.2-source
cp -r jsp /home/dspace/dspace-1.4.2-source
cp -r lib /home/dspace/dspace-1.4.2-source

Note that in the code excerpts below the brackets have been changed to square [] purely for display purposes in this blog.

Edit the file /home/dspace/dspace-1.4.2-source/etc/dspace-web.xml and
add the following lines at the end of the [!-- Servlets --] section:

[!-- Added by Clive Gould on 25th July 2007 --]
[servlet]
[servlet-name]radius-login[/servlet-name]
[servlet-class]org.dspace.app.webui.servlet.RADIUSServlet[/servlet-class]
[/servlet]

Add the following lines at the end of the [!-- Servlet Mappings --] section:

[!-- Added by Clive Gould on 25th July 2007 --]
[servlet-mapping]
[servlet-name]radius-login[/servlet-name]
[url-pattern]/radius-login[/url-pattern]
[/servlet-mapping]

Save the file

Add the following lines, suitably customised, to the end of the
/home/dspace/config/dspace.cfg file:

#to enable Radius authentication
radius.enable=true

#Radius server IP
radius.server_ip = 127.0.0.1

#Secret key of the radius server
radius.shared_key = dspaceclientkeygoeshere

# Port used by the radius server (authentication port and accounting port)
radius.authport = 1812
radius.actport = 1813

# Set to true to enable automatic addition of validated new users to DSpace groups
group.add.auto = true

# Set to true to enable automatic addition of validated existing users to groups
# Note: Setting this to false speeds up the login process
group.update_known_users = false

Save the file

Depending on the Reply-Message sent by the Freeradius server after user authentication, users can be automatically be added or removed from pre-existing groups in DSpace. The group.add.auto and the group.update_known_users parameters control how automatic group membership is handled. By default these parameters are disabled.

Add the appropriate language settings for the RADIUS module to DSpace:

cd /home/dspace/dspace-1.4.2-source/config/language-packs/
pico Messages.properties

Append the following lines to the end the file:

-------------------------------------------------
jsp.components.radius-form.newuser = New user? Click here to register.
jsp.components.radius-form.enter = Please enter your username and
password into the form below.
jsp.components.radius-form.login.button = Log In
jsp.login.radius-incorrect.title = Log In
jsp.login.radius-incorrect.heading = Log In to DSpace
jsp.login.radius-incorrect.errormsg = The username and password you
supplied were not valid. Please try again.
jsp.login.radius.title = Log In
jsp.login.radius.heading = Log In to DSpace
------------------------------------------------

To make rebuilding DSpace easier, create an executable shell script called css_1.4 in /home/dspace containing the following lines:

cd /home/dspace/dspace-1.4.2-source
ant -Dconfig=/home/dspace/config/dspace.cfg build_wars
rm -rf /home/dspace/tomcat/webapps/*dspace*
rm -rf /home/dspace/tomcat/work/*
cp /home/dspace/dspace-1.4.2-source/build/dspace*.war /home/dspace/tomcat/webapps

Save the file

Become the root user.

Create an executable shell script called reb in /home/root containing
the folowing lines:

# This script is intended to be run as root
# It stops tomcat, recompiles DSpace and copies over the new .war files,
before restarting tomcat

service httpd stop
sleep 2
service tomcat stop
sleep 2
sudo -u dspace /home/dspace/css_1.4
sleep 2
service tomcat start
sleep 2
service httpd start

Save the file

Run the file as illustrated below to rebuild DSpace:

[root@vle bin]# reb
Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk
Buildfile: build.xml

compile:
[javac] Compiling 1 source file to
/home/dspace/dspace-1.4.2-source/build/classes

build_wars:
[copy] Copying 1 file to /home/dspace/dspace-1.4.2-source/build
[copy] Copying 3 files to /home/dspace/dspace-1.4.2-source/build/jsp
[war] Building war: /home/dspace/dspace-1.4.2-source/build/dspace.war
[war] Building war: /home/dspace/dspace-1.4.2-source/build/dspace-oai.war

BUILD SUCCESSFUL
Total time: 19 seconds

Using CATALINA_BASE: /home/dspace/tomcat
Using CATALINA_HOME: /home/dspace/tomcat
Using CATALINA_TMPDIR: /home/dspace/tomcat/temp
Using JRE_HOME: /usr/java/jdk

Providing the Freeradius server is configured and running it is now possible to login to DSpace using RADIUS authentication from the following URL:

http://vle.bromley.ac.uk/dspace/radius-login

It is also possible to login to DSpace using the existing manual authentication from either of the following URL's:

http://vle.bromley.ac.uk/dspace/password-login
http://vle.bromley.ac.uk/dspace/dspace-admin

At this point I wanted to force all users to login using RADIUS authentication. This involved logging on as an authenticated radius user, which created an account on DSpace for me. I then logged out and logged in as administrator using manual login and added my new radius authenticated user account to the DSpace administrators group. I then edited the following file to set radius authentication as the default login:

cd /home/dspace/dspace-1.4.2-source/src/org/dspace/eperson/
pico PasswordAuthentication.java

Change the following section to enable radius log by default:

/**
* Returns URL of password-login servlet.
*
* @param context
* DSpace context, will be modified (EPerson set) upon success.
*
* @param request
* The HTTP request that started this operation, or null if not applicable.
*
* @param response
* The HTTP response from the servlet method.
*
* @return fully-qualified URL
*/
public String loginPageURL(Context context,
HttpServletRequest request,
HttpServletResponse response)
{
return response.encodeRedirectURL(request.getContextPath() +
"/radius-login");
}

On rebuilding and restarting DSpace RADIUS became the default login method.

There was a lot more customisation work that had to be done behind the scenes to get RADIUS login to work exactly as we needed it. This involved installing the latest version of the Freeradius server and configuring it to work as a proxy server with both staff and student realms in our Active Directory database. Additionally, because users are only required to logon using their standard College username it was also necessary to modify the source code of the RADIUS module for DSpace so that the domain name suffix was automatically added to the username to form the full email address for DSpace to use for registration. At the same time a different local domain name suffix had to be added to the username for Freeradius and AD authentication purposes.

Customising the RADIUS module

The modifications made to RADIUSServlet.java are shown below:

cd /home/dspace/dspace-1.4.2-source/src/org/dspace/app/webui/servlet/
pico RADIUSServlet.java

Added the following lines shown in context in bold:

// Process email and password fields
String netid = request.getParameter("login_netid");
String password = request.getParameter("login_password");
EPerson eperson;

// Next eight lines added by Clive on 050807
String radnetid;
if(netid.charAt(0)=='1') {
netid = netid + "@learner.bromley.ac.uk";
radnetid = netid.replaceAll("leaner.bromley.ac.uk", "learn.college.local");
} else {
netid = netid + "@teacher.bromley.ac.uk";
radnetid = netid.replaceAll("teacher.bromley.ac.uk", "teach.college.local");
}

Also modified the following line:

AttributeList attrs = new AttributeList();
// changed from netid to radnetid by Clive on 020807
attrs.add(new Attr_UserName(radnetid));
// attrs.add(new Attr_NASPortType(Attr_NASPortType.IAPP));
//attrs.add(new Attr_NASPort(new Long(1)));

In our case we only needed mschapv2 authentication so following methods were commented out to speed up the login process:

/** //EAP-TTLS
* RadiusResponse eapttls=try_auth_method(rc,attrs,"eap-ttls:trustAll=true",context,password);
* if (eapttls!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling EAP-TTLS authentication"));
* return eapttls;
* }
*
* //MSCHAP
* RadiusResponse mschap=try_auth_method(rc,attrs,"mschap",context,password);
* if (mschap!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling MSCHAP authentication"));
* return mschap;
* }
*
* //MSCHAPV1
* RadiusResponse mschapv1=try_auth_method(rc,attrs,"mschapv1",context,password);
* if (mschapv1!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling MSCHAPV1 authentication"));
* return mschapv1;
* }
*/

//MSCHAPV2
RadiusResponse mschapv2=try_auth_method(rc,attrs,"mschapv2",context,password);
if (mschapv2!=null)
{
log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling MSCHAPV2 authentication"));
return mschapv2;
}

/** //CHAP
* RadiusResponse chap=try_auth_method(rc,attrs,"chap",context,password);
* if (chap!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling CHAP authentication"));
* return chap;
* }
*
* //EAP-MD5
* RadiusResponse eapmd5=try_auth_method(rc,attrs,"eap-md5",context,password);
* if (eapmd5!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling EAP-MD5 authentication"));
* return eapmd5;
* }
*
* //PAP
* RadiusResponse pap=try_auth_method(rc,attrs,"pap",context,password);
* if (pap!=null)
* {
* log.info(LogManager.getHeader(context,"[RADIUSServlet] Authentication:"," handling PAP authentication"));
* return pap;
* }
*/

Saved the file and rebuilt DSpace.

Customising the Freeradius Server

There were also various configuration options required with the proxying Freeradius server including the addition of the appropriate entries in the users file so that different Reply-Message (s) were sent for staff and student logins. This was necessary so that DSpace added new users to the appropriate groups based on whether they were staff of students.

The default configuration was used with the radiusd.conf file with the exception that the following lines were commented out to speed up the authentication process:

authenticate {
# Auth-Type PAP {
# pap
# }
# Auth-Type CHAP {
# chap
# }
# Auth-Type MS-CHAP {
# mschap
# }
unix
# eap
}

The contents of the clients.conf file containing connection settings for the DSpace client is shown below:

cd usr/local/etc/raddb
cat clients.conf
client 127.0.0.1 {
secret = "dspaceclientkeygoeshere"
shortname = vle
nastype = other
}

The contents of the proxy.conf file containing connection settings for the Windows IAS proxy is shown below:

proxy server {
synchronous = no
retry_delay = 5
retry_count = 3
dead_time = 120
default_fallback = yes
post_proxy_authorize = yes
}

# Added by Clive on 26th July 2007
realm teach.college.local {
type = radius
authhost = 10.200.0.2:1812
accthost = 10.200.0.2:1813
secret = "the\\$hared$ecretforIASgoeshere"
nostrip
}

# Added by Clive on 3rd August 2007
realm learn.college.local {
type = radius
authhost = 10.200.0.2:1812
accthost = 10.200.0.2:1813
secret = "the\\$hared$ecretforIASgoeshere"
nostrip
}

realm LOCAL {
type = radius
authhost = LOCAL
accthost = LOCAL
}

nostrip
}

Note that in the preset shared secret for the IAS server there were over 22 characters including unusual characters such as $ and also a single \

It took a long time to find out that in order to get proxying to work it was necessary to double quote the shared secret in proxy.conf and escape the backslash using a second backslash \\

The contents of the users file, which contains details of the Reply-Message for staff and students is shown below:

DEFAULT Auth-Type = System
Fall-Through = 1

DEFAULT Service-Type == Framed-User
Framed-IP-Address = 255.255.255.254,
Framed-MTU = 576,
Service-Type = Framed-User,
Fall-Through = Yes

# Next three lines added by Clive on 03/08/07 so that DSpace automatically adds staff on login to the STAFF group
DEFAULT Suffix == "teach.college.local", Auth-Type = System
Reply-Message = "Group_STAFF:yes;",
Fall-Through = Yes

# Next three lines added by Clive on 03/08/07 so that DSpace automatically adds students on login to the STUDENT group
DEFAULT Suffix == "learn.college.local", Auth-Type = System
Reply-Message = "Group_STUDENT:yes;",
Fall-Through = Yes

DEFAULT Framed-Protocol == PPP
Framed-Protocol = PPP,
Framed-Compression = Van-Jacobson-TCP-IP

DEFAULT Hint == "CSLIP"
Framed-Protocol = SLIP,
Framed-Compression = Van-Jacobson-TCP-IP

DEFAULT Hint == "SLIP"
Framed-Protocol = SLIP

The above files were saved and the radius server restarted so that the changes took effect.

I also had to modify the startup script rc.local so that Freeradius started on system boot.

Return to Menu

26) Using a commercial host specific SSL certificate

The College has now started using machine specific wildcard SSL certificates provided by IKERNA and GlobalSign. I have replaced the wildcard certificate used above with a host specific certificate. The process I used is outlined below:

Create a folder off /root called Certwork_Sept_07 and change into this folder.
md /root/Certwork_Sept_07
cd /root/Certwork_Sept_07

Create a certificate signing request and send it off to IKERNA:

openssl req -new -nodes -keyout myserver.key -out myserver.csr
Generating a 1024 bit RSA private key
.................++++++
...++++++
writing new private key to 'myserver.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:GB
State or Province Name (full name) [Berkshire]:Kent
Locality Name (eg, city) [Newbury]:Bromley
Organization Name (eg, company) [My Company Ltd]:Bromley College
Organizational Unit Name (eg, section) []:School of ICT
Common Name (eg, your name or your server's hostname) []:vle.bromley.ac.uk
Email Address []:root@vle.bromley.ac.uk

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:Bromley College

Backup myserver.csr and myserver.key and keep them in a very safe place.

When the reply comes back from IKERNA save the .pem attachment from the Globalsign certificate email in the Certwork_Sept_07 folder. As root enter the following commands:

cd /root/Certwork_Sept_07
cp cert_1616716307.pem myserver.crt
openssl rsa -in myserver.key -out myserver.key.insecure
cp myserver.key.insecure /etc/httpd/conf/ssl.key/server.key
cp myserver.csr /etc/httpd/conf/ssl.csr/server.csr
cp myserver.crt /etc/httpd/conf/ssl.crt/server.crt
service httpd restart

Return to Menu

27) Upgrading to DSpace 1.5.0

I have just upgraded our test server to DSpace 1.5.0 and summarise the process I used below.

DSpace 1.5.0 will not be deployed on our production server for some time as despite a lot of help from Rui Ramos, I have to date, been unable to get RADIUS authentication to work with DSpace 1.5.0

### DSpace 1.4.2 to 1.5.0 upgrade procedure

## In terms of the Web based upgrade documentation

#[dspace-source] is /home/dspace/dspace-1.5.0-release/
#[dspace] is /home/dspace

# The build directory is

# /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/

## Login as user dspace:
# download dspace 1.5.0 default release and untar it

## Login as user root
# copy dspace installation documentation into the Webserver root

su - root
cp -pr docs /var/www/html/docs_1.5

# install and test maven

cd /usr/local
mkdir apache-maven
cd apache-maven
lynx http://maven.apache.org/download.html
tar -xzvf apache-maven-2.0.9-bin.tar.gz

pico /etc/profile
# append the following lines:

export M2_HOME=/usr/local/apache-maven/apache-maven-2.0.9
export M2=$M2_HOME/bin
export PATH=${PATH}:$M2
# save /etc/profile

# Put the testvle server into upgrade mode and stop tomcat and handle servers:

cd /root/bin
./backup_to_upgrade
service httpd stop
service tomcat stop
service handle stop
logout

## Login as user dspace:

# compile dspace

mvn --version

cd /home/dspace/dspace-1.5.0-release/dspace
mvn package

# Edit the /home/dspace/dspace-1.5.0-release/dspace/config/dspace.cfg copied by rysnc from the vle server to customise it for the testvle server.

sed s/"vle.bromley"/"testvle.bromley"/g /home/dspace/dspace-1.5.0-release/dspace/config/dspace.cfg >

/home/dspace/config/dspace.cfg

# Copy over some new required files:

cp /home/dspace/dspace-1.5.0-release/dspace/config/xmlui.xconf /home/dspace/config/xmlui.xconf

cp /home/dspace/dspace-1.5.0-release/dspace/config/item-submission.xml /home/dspace/config/item-submission.xml

cp /home/dspace/dspace-1.5.0-release/dspace/config/item-submission.dtd /home/dspace/config/item-submission.dtd

cp /home/dspace/dspace-1.5.0-release/dspace/config/input-forms.xml /home/dspace/config/input-forms.xml

cp /home/dspace/dspace-1.5.0-release/dspace/config/input-forms.dtd /home/dspace/config/inputforms.dtd

cp /home/dspace/dspace-1.5.0-release/dspace/config/crosswalks/sword-swap-ingest.xsl /home/dspace/config/crosswalks/sword-swap-ingest.xsl

cp /home/dspace/dspace-1.5.0-release/dspace/config/crosswalks/xhtml-head-item.properties /home/dspace/config/crosswalks/xhtml-head-item.properties

# Update the database

psql -f /home/dspace/dspace-1.5.0-release/dspace/etc/database_schema_14-15.sql dspace -h localhost

# Apply any JSP customisations here.
# Probably best to start again with the new files that come with DSpace 1.5.0
#

# Edit dsrun
cd /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/bin
pico /home/dspace/bin/dsrun and make the following amendments:

# Now invoke Java
# Modified by Clive Gould on 11th August 2008
# java -Xmx256m -classpath $FULLPATH "$@"
/usr/java/jdk/bin/java -mx2024m -classpath $FULLPATH "$@"

Save dsrun

# Build DSpace

cd /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/
ant -Dconfig=/home/dspace/config/dspace.cfg update

# Rebuild browse and search indexes
./home/dspace/bin/index-init

# Update statistics scripts

Copy the new stats scripts:

cp /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/bin/stat* /home/dspace/bin/

# Then edit your statistics configuration file with the start details.
# The statistics scripts have been rewritten for DSpace 1.5. First, make a note of the dates you have specified in your statistics scripts
# for the statistics to run from. You will find these in /home/dspace/bin/stat-initial, as $start_year and $start_month.

cp /home/dspace/dspace-1.5.0-release/dspace/config/dstat.cfg /home/dspace/config/dstat.cfg

pico /home/dspace/conf/dstat.cfg

# and add the following replacing '2005' and '1' as with the values you noted down.

# the year and month to start creating reports from
# - year as four digits (e.g. 2005)
# - month as a number (e.g. January is 1, December is 12)
start.year = 2005
start.month = 1

# Upgrade Tomcat to 5.5.26 as the existing version of 5.5.9 gives internal server errors with DSpace 1.5

cd /home/dspace
lynx http://tomcat.apache.org/download-55.cgi#5.5.26
tar -xzvf apache-tomcat-5.5.26.tar.gz
mv tomcat tomcat5.5.9
mv apache-tomcat-5.5.26 tomcat
cd /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/webapps

# Copy over the new webapps directories:

cd /home/dspace/dspace-1.5.0-release/dspace/target/dspace-1.5.0-build.dir/webapps
cp -pr jspui /home/dspace/tomcat/webapps/dspace
cp -pr oai /home/dspace/tomcat/webapps/dspace-oai

# Edit the following files to correct the path to dspace.cfg:

/home/dspace/tomcat/webapps/dspace/WEB-INF/web.xml
/home/dspace/tomcat/webapps/dspace-oai/WEB-INF/web.xml

logout

## Login as root

service tomcat start
service handle start
service httpd start

# Hurray DSpace 1.5.0 finally works on our test server :)

Return to Menu