OAI installation instructions

The DLESE OAI software includes a data provider that supports protocol version 2.0 and a harvester that supports protocol versions 2.0 and 1.1. For more information about OAI, see http://www.openarchives.org/. The data provider serves XML metadata. Likewise, the harvester saves downloaded XML metadata in a specified directory.

Knowledge needed

• Understand XML instance documents
• Working knowledge of UNIX or Windows directory structures depending on type of installation
• Ability to edit UNIX or Windows files depending on type of installation

Operating systems & web browsers

• OAI has been tested and used in Linux (7.x and 9.x), Windows XP and Mac OSX Jaguar
• Assumed to work under other versions of UNIX but no testing has been completed
• Works best in Firefox 1.0.7, Netscape 6 or higher or Internet Explorer 5.5 or higher

General installation procedure

This quick start process describes how to set up the supporting software for OAI, the OAI software itself, and a basic OAI configuration. The process also includes doing a test harvesting and providing of metadata records. This process assumes a stand-alone Tomcat instance.

To install and run the DLESE OAI software you must have the following:

• oai.war - the DLESE OAI software.
• A servlet container such as Tomcat to run the OAI software.
• Java2 platform v1.4 or later. Note that the IBM Java2 package has been shown to be considerably faster than the Sun Java2 package for search operations in this software when running on Linux.

1. Install Tomcat and Java2 JDK
2. Download and Install the OAI
3. Start or Restart Tomcat
4. OAI Software should now be running
5. Harvest Test Records
6. Provide Test Records
7. Quick Start Summary and Help

1. Install Tomcat and a Java2 JDK on your server

The following example shows how to install and configure the software using the Tomcat servlet container. Tomcat is a free, open source servlet container available from Apache at http://tomcat.apache.org/.

• These instructions were written for Tomcat version 5.x running in a UNIX environment but should be similar to other versions and platforms.
• Version 2.0.9.3 of the DLESE OAI software has been tested successfully in Tomcat 4.x and minimally tested in 5.0.18 and 5.5.9.
• You must configure Tomcat to run using the Java2 platform v1.4 or later.
• If using Tomcat 5.5.x, you must also download and install the compatibility package as well (even if using a 1.5 JVM).

Java2 JDKis available at:

• IBM (recommended for Linux): http://www6.software.ibm.com/dl/lxdk/lxdk-p
• Sun (for Linux and Windows): http://java.sun.com/j2se/
• For Mac OSX (Jaguar or later): Java2 comes pre-installed or may be installed using software update.
• GLIBC 2.2 / Linux 2.4 users should define an environment variable: export LD_ASSUME_KERNEL=2.2.5
• Redhat Linux 9.0 users should use the following setting to avoid stability problems: export LD_ASSUME_KERNEL=2.4.1

2. Download and install OAI

To download and unpack OAI, follow the steps below:

1. Download the latest version of the software from the DLESE SourceForge download page: http://sourceforge.net/project/showfiles.php?group_id=23991&package_id=30203
2. Place the file 'oai.war' into the 'webapps' directory found in your Tomcat installation. 'webapps' is the default location where Tomcat expects to find web applications.

3. Start and Restart Tomcat

Upon startup the first time, Tomcat will automatically unpack the oai.war archive, creating a directory and application context named 'oai'.

• Tip: if Tomcat does not unpack the archive you may do so manually:
  1. Create an 'oai' directory in the 'webapps' directory.
  2. cd into 'oai.'
  3. Enter the command 'jar xvf ../oai.war.

4. OAI Software should now be running

Launch a web browser and type in the URL to the oai servlet context,

• The address will use the context path created in step 3 ('oai').
• If the domain name to your server is http://www.myserver.edu and Tomcat has been installed using the default port (8080), the URL to the OAI software will be http://www.myserver.edu:8080/oai/
• Alternatively you may access the software using the localhost domain shortcut: http://localhost:8080/oai/.

If there are errors accessing the software try repeating or verifying Steps 1 and 2.

• Tip: Check the Tomcat logs for error messages located in the 'logs' directory of your Tomcat installation if there are problems.

At the URL mentioned above, you will be greeted by a 'Getting started' page that will walk through the remaining few steps necessary to use the harvester and/or make your metadata available in the data provider. More detailed instructions are provided in Steps 5 and 6.

5. Harvest test records

Section 5 and 6 test the OAI harvest and data provider components.

To set your OAI software to harvest records from DLESE do the following:

1. Click on Harvester administration from the menu at the top of the page
2. Do a Perform a one-time harvest
3. Enter http://dlese.org/oai/provider as the data provider base URL
4. Enter adn as the metadata format
5. Click Harvest
6. At the top of the page access the harvest report. Click view the harvest status report for this harvest
7. Refresh the page several times and you will see the number of records increase. The entire harvest may take a minute or two
8. To see that records have arrived, note the directory location of where records are being saved to. To see records in this example, you would go to:
   {TOMCAT_HOME}/webapps/oai/WEB-INF/harvested_records/dlese.org/oai/provider/
   (where {TOMCAT_HOME} is the top directory of your Tomcat installation)
9. Then based on the repository name follow the directory structure down to the records.
10. If records are present, your harvest was successful. You may now want to disable harvesting from DLESE

6. Provide test records

To set your OAI software to provide the enclosed sample records do the following:

1. Click on To provider administration
2. Complete repository name. Make one up.
3. Add an email address
4. Scroll down to add a metadata set. Click Add new set
5. Enter Samples of records as the a set name
6. Enter samples as the setSpec
7. Click Save
8. Click Add new directory/format
9. Enter format of files, adn
10. Enter directory of files, {TOMCAT_HOME}/webapps/oai/WEB-INF/sample_metadata
11. Click Save
12. Click on Provider data search
13. Enter * in the search dialog box and click Search
14. The sample metadata records should appear in the results list. This may take a few seconds.Your provider is now working.

7. Quick start summary and help

If you have harvested and provided with your OAI tool, you are operational. However, based on user experiences, the information below may help answer further questions about memory issues with Linux (a known issue with Red Hat 9) or how to add XML schema or namespace information to the ListMetadataFormats response. For other questions, please contact support@dlese.org.

• Fixes for Java crashes when running on Linux
• Add XML schemas and namespaces to the ListMetadataFormat response (needed if NSDL is to harvest you)
• Enable access control (see included documentation at http://localhost:8080/oai/docs/index.html)

Other possible documents that may answer questions:

• OAI documentation at http://localhost:8080/oai/docs/index.html
• View the DLESE OAI Information page
• Read about Interoperability from a metadata perspective

Last updated: 2005-12-09
Maintained by: Katy Ginger (support@dlese.org), DLESE Metadata

---

DLESE HOME | FAQ | GLOSSARY | SITE MAP | CONTACT US