Theses Alive!
at Edinburgh University Library

Installing The Tapir

Current Version: 0.3

The following instructions will guide you through the installation of The Tapir. The process is relatively simple, although at some points it is necessary to modify DSpace files in order to make the system work.

In order to make a clear distinction between your DSpace install and The Tapir source code, we will use the notation:

[tapir] - The directory in which you have the unpacked The Tapir code.

[dspace] - Your target DSpace installation to add our code to.

[dspace-source] - The source code from which you installed your current DSpace instance, and from which you launch code updates.

[tomcat] - The installation directory of your working tomcat web-server

This software has been tested for compatibility with v1.2 of DSpace, and should also work with earlier versions, although currently no documentation exists to install Tapir 0.3 on previous versions of DSpace.

1. Preparing DSpace for the Installation

Before shutting down tomcat to perform the Tapir installation, please ensure that the following DC element-qualifier pairs are registered in the DSpace Dublin Core Registry:

contributor.advisor
contributor.author
contributor.editor
contributor.sponsor
coverage.spatial
date.issued
date.verified
description.abstract
description.sponsorship
format.extent
format.mimetype
identifier.citation
identifier.govdoc
identifier.isbn
identifier.ismn
identifier.issn
identifier.uri
identifier
language.iso
publisher
relation.hasversion
relation.ispartof
relation.ispartofseries
relation.requires
relation.references
subject.ddc
subject.lcc
subject.lcsh
subject.mesh
subject.other
subject.udc
title.alternative
title
type

2. Compulsory Installation Steps

This section explains how to install the parts of the system that are required before any of the subsequent facilities can be made to work. It does not matter if you are upgrading or installing from scratch for this section.

2.1.

Download and unpack the .tar.gz (available here) to the directory to which we will refer as [tapir] from now on.

2.2.

Ensuring that ant is in the environment path, go to the [tapir]/java directory and use the following command:

% ant -Ddslib=[dspace]/lib -Dtarget=[dspace-source]/lib -Dconfig=[dspace]/config/dspace.cfg install

The file tapir.jar will be created in [dspace-source]/lib

You now have all the compiled java installed that is required to run any of the following facilities.

If you have been using Tapir (EUL-DSpace Add-On) 0.2.1 on a previous version of DSpace, and have data to maintain then you need to upgrade to DSpace 1.2. first and then install Tapir 0.3 immediately after. If this is the case please go to section 4.

3. Full Installation of all Tapir Facilities

This section details how to install all of the additional facilities provided by The Tapir.

3.1.

Update the database configuration:

% ant -Dconfig=[dspace]/config/dspace.cfg database

3.2.

Open [tapir]/jsp/WEB-INF/tapir-web.xml and insert the different sections into the equivalent sections of [dspace-source]/etc/dspace-web.xml

In [tapir]/jsp/WEB-INF/tapir-web.xml you are given the choice at one point of selecting one of two submit servlets:

<!-- ########## EUL Servlet Options ########## --> <!-- You may use one or other of the below servlets, but not both -->

At this stage you should include the lines under:

<!-- Servlet: submit (option 2)-->

and leave the other option out.

You must also comment out the default dspace submission servlet:

<servlet> <servlet-name>submit</servlet-name> <servlet-class>org.dspace.app.webui.servlet.SubmitServlet</servlet-class> </servlet>

around line 300 of [dspace-source]/etc/dspace-web.xml

3.3.

Open [tapir]/jsp/WEB-INF/tapir-tags.tld and insert the new tags into the tags of the same name in [dspace-source]/jsp/WEB-INF/dspace-tags.tld.

For example, replace:

<tag> <name>item</name> <tagclass>org.dspace.app.webui.jsptag.ItemTag</tagclass> ... </tag>

with:

<tag> <name>item</name> <tagclass>ac.ed.dspace.app.webui.jsptag.ItemTag</tagclass> ... </tag>

3.4.

Copy all of the custom JSPs from [tapir]/jsp to [dspace-source]/jsp/local

Ensure that there are no clashes between custom Tapir JSPs and your own locally modified JSPs. Use a command like:

% cp -ir [tapir]/jsp [dspace-source]/jsp/local

To be questioned before any files are overwritten. To see a list of the file changes history for Tapir, please look at the file [tapir]/docs/FILE_LIST

If there are clashes you will need to open up the Tapir JSPs and copy across the relevant bits of code, which are delimited by:

//******* Start EUL Code Inclusion ********

and

//******* End EUL Code Inclusion ********

3.5.

Remove the directory [dspace-source]/jsp/local/WEB-INF:

% rm -r [dspace-source]/jsp/local/WEB-INF

3.6.

Append the contents of [tapir]/config/tapir-dspace.cfg to the dspace.cfg file that we will use when we run the update to the main dspace code:

% cat [tapir]/config/tapir-dspace.cfg >> [dspace]/config/dspace.cfg

Customise your Tapir installation by editing the new [dspace]/config/dspace.cfg and updating the property restrict.domain to be equal to the domain of your institution (e.g. The University of Edinburgh).

3.7.

Install the licences that come with The Tapir (be careful to spell everything exactly as below):

% cp [tapir]/config/default.license [tapir]/config/licence.* [dspace-source]/config

The licences packaged with The Tapir should be customised to your institution's requirements. Simply edit the files copied above in situ before building doing the DSpace update in section 3.9.

3.8.

Add the contents of [dspace-source]/jsp/local/tapir-styles.css.jsp to the DSpace style sheet document [dspace-source]/jsp/styles.css.jsp.

For completeness, once this has been done you can remove the tapir-styles.css.jsp file.

3.9.

Now update the DSpace installation with The Tapir inside it. Go to the directory [dspace-source] then:

% ant -Dconfig=[dspace]/config/dspace.cfg update

Move the new WAR files to the working Tomcat directory:

% cp [dspace-source]/build/dspace.war [dspace-source]/build/dspace-oai.war [tomcat]/webapps

Remove the current dspace and dspace-aoi directories that tomcat maintains:

% rm -r [tomcat]/webapps/dspace % rm -r [tomcat]/webapps/dspace-oai

3.10.

To deploy DSpace with Tapir as a web application first remove the tomcat file cache to ensure that the correct files are served. To do this remove all the content of the [tomcat]/work directory.

Now you may restart tomcat.

4. Upgrading to 0.3 from 0.2 or 0.2.1

In general you will need to perform a full install of The Tapir 0.3 since it is primarily designed to run with DSpace 1.2. The following documentation, therefore, is designed to deal with the situation where you have upgraded from DSpace 1.1.1 with Tapir (EUL-DSpace Add-On) 0.2.1 to DSpace 1.2 and wish to re-instate required Tapir version (0.3) to manage data already collected under 0.2.1.

4.1.

Upgrade the database contents to deal with metadata changes:

% ant -Dconfig=[dspace]/config/dspace.cfg upgrade_0.2_0.3

4.2.

Since installation of DSpace 1.2 should have overwritten most customisations it is easiest to perform a full installation again. Please go to section 4.2. and follow the instructions from there.

Last updated: Wed, 01 September, 2004