Skip to content

02-install-jOAI.md

Latest commit

 

History

History
201 lines (160 loc) · 7.67 KB

02-install-jOAI.md

File metadata and controls

201 lines (160 loc) · 7.67 KB
Raw

Installing an OAI server

This document describes how to install and set up a full implementation of an Open Archives Initiative (OAI) server based on the open source software jOAI. An OAI server can be used to provide metadata records via OAI Protocol for Metadata Harvesting (OAI-PMH). It can also be used to a harvest metadata from OAI-PMH endpoints.

In the next two modules, 02.a and 02.b, we will explain how to configure the OAI-PMH data provider and harvester tool repectively, based on this software. In our examples, jOAI will run within Apache Tomcat on an Ubuntu machine.

Environment

Ubuntu 14.04 server

Prerequisites

1. Update and upgrade if necessary

sudo apt-get update
sudo apt-get upgrade

2. Internet connection and browser

In general, an internet browser, e.g. Firefox, should be installed on your computer. If you are using a VM, e.g. in VirtualBox Manager, you will need to configure the network to work in bridge mode.

If you are using a VM in a cloud environment, you might need to configure the firewall. Below we demonstrate setting up an example firewall using iptables-persistent. If you are using a different firewall configuration tool, it is important that port 80 and port 8080 are open for use (also port 8181 in most cases, see the next section).

  • Install iptables-persistent
sudo apt-get install iptables-persistent
  • Edit /etc/iptables/rules.v4:
*filter
:INPUT ACCEPT [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [4538:480396]
-A INPUT -m state --state INVALID -j DROP
-A INPUT -p tcp -m tcp ! --tcp-flags FIN,SYN,RST,ACK SYN -m state --state NEW -j DROP
-A INPUT -f -j DROP
-A INPUT -p tcp -m tcp --tcp-flags FIN,SYN,RST,PSH,ACK,URG NONE -j DROP
-A INPUT -p tcp -m tcp --tcp-flags FIN,SYN,RST,PSH,ACK,URG FIN,SYN,RST,PSH,ACK,URG -j DROP
-A INPUT -p icmp -m limit --limit 5/sec -j ACCEPT
-A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
-A INPUT -p tcp -m tcp --dport 22 -j ACCEPT
-A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
-A INPUT -p tcp -m tcp --dport 8080 -j ACCEPT
-A INPUT -p tcp -m tcp --dport 8181 -j ACCEPT
-A INPUT -p tcp -m tcp --dport 8983 -j ACCEPT
-A INPUT -p tcp -m tcp --dport 5432 -j ACCEPT
-A INPUT -j LOG
-A INPUT -j DROP
COMMIT
  • Restart the firewall
/etc/init.d/iptables-persistent restart

Installation

2. Download and unpack the jOAI Software

See this page for details about jOAI.

The current version can be downloaded from Sourceforge as zip file:

wget https://sourceforge.net/projects/dlsciences/files/jOAI%20-%20OAI%20Provider_Harvester/v3.1.1.4/joai_v3.1.1.4.zip
unzip joai_v3.1.1.4.zip

Note, unzip does not come by default with an Ubuntu server 14.04, you can install it with:

sudo apt-get install unzip

3. Install Tomcat

In the INSTALL.txt of the jOAI package above, it is recommended to download the Tomcat server container from the official Tomcat webpage. However, in most cases (and in case of Ubuntu version 12 and greater), you can use the pre-installed Tomcat package.
The current version of tomcat is 7, but jOAI also runs within tomcat6, if that is what is on your system.

sudo apt-get install tomcat7

3a. Tomcat troubleshooting

One known problem with Tomcat is that there are conflicts with other web servers, e.g. Apache, running on the same machine. If you want run a CKAN instance in parallel, for instance, you must change the port of the connector in the file /etc/tomcat7/server.xml :

   <!-- Changed port 8080 to 8181 -->
    <Connector port="8181" protocol="HTTP/1.1"
               connectionTimeout="20000"
               URIEncoding="UTF-8"
               redirectPort="8443" />

Then restart Tomcat by

sudo service tomcat7 restart

Hence, jOAI will run on:

http://localhost:8181/,

or if you work on a remote server (VM):

http://<ip-address or fully qualified domain name>:8181/

We will deploy CKAN, which makes use of apache, so we advise you to use port 8181, the firewall has also been set up accordingly in section 2).

For general troubleshooting and Diagnostic techniques, refer to the Apache Tomcat troubleshooting page.

4. Add the web application jOAI to the Tomcat container

Place the file oai.war into the webapps directory found in your Tomcat installation directory. The webapps directory is the default location where Tomcat searches for web applications:

sudo cp joai_v3.1.1.4/oai.war /var/lib/tomcat7/webapps/

During its first start, Tomcat will unpack the application oai.

5. Install the Java Platform, Standard Edition v5 or later

Tomcat needs the Java Runtime environment (JRE). Often, this is already preinstalled on ubuntu by an apt-get update.

You can check the installation (path) by:

readlink -f $(which java)

If java is not installed, at least install JRE:

sudo apt-get install default-jdk

or for the latest java version execute:

sudo apt-get install oracle-java8-installer.

Finally set the environment variable JRE_HOME, e.g.

JRE_HOME=/usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java

or

JRE_HOME=/usr/lib/jvm/java-8-oracle/jre/bin/java

in your sh ~/.bashrc.

6. Start Tomcat

Try to start Tomcat using:

sudo service tomcat7 start

To stop, start, or restart Tomcat you can use the follwing command:

sudo service tomcat7 <stop, start, restart>

Now, if you are working on the current machine, try the following in an internet browser:

<localhost>:8181

If you are working on a remote server (VM), try:

<ip address or fully qualified domain name>:8181

If all works fine, you should see a page with the title 'It works!', and the graphical user interface of the web application jOAI should be opened by:

localhost:8181/oai

or

http://<ip-address or fully qualified domain name>:8181/oai/

Congratultaions!

Note, when running tomcat for the first time after a configuration change, the loading of the webpage can take very long.

Now you can configure and use your OAI-PMH provider and harvester as described in the following module, 02.a-Configuring an OAI Data Provider.

7. Repository configuration

First, some basic configurations should be set. On the Overview page, by clicking on the link Set up the Provider, you will be lead to the Data Provider Documentation page, where you can find lots of information that will be needed in the next module.

For now, click on the Repository information link. By clicking on the Edit repository info button on this page, you will be lead to a page similar to the image below, where information describing your repository can be added.

This page can also be accessed through the menus, following Data Provider, and then Repository Information and Administration.

Note: For now we will not specify the optional Namespace identifier.

8. (Optional) Repository security

After this installation, anyone can access all ionformation on the server. To restrict access to sensitive data, such as harvesting information, follow the instructions on this page. This is optional and not required for this tutorial. However we strongly recommend to restrict access on a production system .