Installation instructions for the jOAI software v3.0.11.

If you are upgrading from a previous version, see notes on 
upgrading below.

To install and run the jOAI software you must have the following:
  
1. oai.war - the jOAI software.
2. Apache Tomcat v5.x or later or other JSP 2.0 compliant servlet container.
3. Java 2 Platform v1.5 or later.


Step 1: Download and install the Tomcat servlet container on your server. 
To install Tomcat, follow the instructions available from Apache at
http://tomcat.apache.org/.

Tomcat requires the Java Platform, Standard Edition v1.5 or later, available here:
Sun: http://java.sun.com/javase/
IBM: http://www-128.ibm.com/developerworks/java/jdk/linux/download.html
For Mac OSX (Jaguar or later): Java 2 comes pre-installed or may be installed
using software update.
Note: Sun jdk1.5.0_09 has shown improved memory management and stability on Linux 
than other versions of Java.

Step 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.

Step 3: Start or restart Tomcat. Upon startup the first time, Tomcat will 
automatically unpack the oai.war archive, creating a directory and 
application context named 'oai'.
  
Step 4: The jOAI software should now be running. Launch a
web browser and type in the URL to the oai servlet context, which will
have the following form:
- 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 
was 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.
  
Step 5: 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 OAI harvester,
data provider or repository search portions of the software.


============ Upgrading from a previous version ===============

If you are upgrading from v3.0.2 or earlier versions of the software,
please note the following:

- Saved indexes, settings and configuration files from previous versions of the 
software are not compatible with the new version.

- Remove any previous installations from your tomcat webapps directory 
before installing the new version. You can save the previous installation
by moving it's directory (e.g. the 'oai' directory) out of webapps and 
reinstall it later by placing it back into webapps if needed.

- Only one instance of the software should be installed and running in a single
Tomcat (or other application server) at any given time.


============ Tips and notes ============

1. Only one instance of the software should be installed and running in a single
Tomcat (or other application server) at any given time.

2. Tomcat on Linux

	The following tips taken from the Tomcat 5 release notes has been used to 
	fix stability problems reported with the OAI software on Linux:

	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

3. If Tomcat does not unpack the oai.war archive automatically, you may do so manually. 
	
	On Linux: 1. Create an 'oai' directory in the 'webapps' directory. 
	2. cd into 'oai.' 3. Enter the command 'jar xvf ../oai.war.'
	
	
	
If you have questions or comments, please e-mail support@dlese.org