View source for Installing isis-oai-provider

Isis-oai-provider is a software application that provides access to ISIS databases through OAI protocol to be harvested.

The application works with PHP 5.3.x.

==Setting up==

===Method 1 - Download files===

Download the last version from ''Downloads'' link at the ''github'' repository (zip or tar gz file) and extract the file to your server.

* Creating a structure and extracting application files under server /opt/ directory on a Linux server:
    $ cd /opt/
    $ mkdir bireme
    $ cd bireme
    $ wget https://github.com/bireme/isis-oai-provider/tarball/master -O isis-oai-provider.tar.gz
    $ tar xvfzp isis-oai-provider.tar.gz
    $ mv bireme-isis-oai-provider-53c0abc/ isis-oai-provider
'''NOTE''': the term '''53c0abc''' is automatically generated during the creation of the tar.gz file, thus being different at every execution.
* Downloading the application files on a Windows server:
** access the application page available at https://github.com/bireme/isis-oai-provider
** click on the '''download zip''' button to download the application files
** unpack to the directory it is intended to

===Method 2 - Clone the project git repository===

The advantage of this method is that you can easily update the application later, but it is necessary that the server has the ''git-core'' package installed.

Example: Creating a structure and downloading the application from repository under /opt/ directory in the server:

    $ cd /opt/
    $ mkdir bireme
    $ cd bireme
    $ git clone git://github.com/bireme/isis-oai-provider.git

Deploy the aplication on the Web Server (ex. Apache Web Server)

'''Option A - Using a specific VirtualHost for the web application'''

    <VirtualHost *:80>
       ServerName isis-oai-provider.local
       DocumentRoot /opt/bireme/isis-oai-provider/htdocs/

       <Directory "/opt/bireme/isis-oai-provider/cgi-bin">
            Options +ExecCGI
            AllowOverride None
            Order deny,allow
       </Directory>

       ScriptAlias /cgi-bin/ /opt/bireme/isis-oai-provider/cgi-bin/
       LogLevel warn
       CustomLog /var/log/apache2/isis-oai-provider.log combined
       ServerSignature On
    </VirtualHost>

'''Option B - Using a existing VirtualHost'''

Assuming you have a website already running you will only need to find out the paths to the following components:

* '''DocumentRoot''' --- the directory where static files and PHP scripts are located - usually ''htdocs''
* '''cgi-bin''' --- the directory with special permissions for executing CGI scripts - usually ''cgi-bin''
* '''ISIS databases''' --- the directory on the server where ISIS databases are located - usually ''bases''

Then move/copy or create symbolic links to the isis-oai-provider directories:

Ex. Assuming a website with the following directory structure:

  /home/sites/
             /site1/
                    htdocs/
                    cgi-bin/
                    bases/

Follow the steps below to create symbolic link to the application directories:

  $ cd /home/sites/site1/htdocs
  $ ln -s /opt/bireme/isis-oai-provider/htdocs/isis-oai-provider/ .
  $ cd /home/sites/site1/cgi-bin
  $ ln -s /opt/bireme/isis-oai-provider/cgi-bin/isis-oai-provider/ .

== Adjustments before configuring ==

In order that ISIS-OAI-Provider works correctly, it is mandatory to rename some directories according to the platform in use.

# In case it is a '''Linux operating system''', rename the directories as follows:
#* Binary executables (WWWISIS)
#** from: cgi-bin/isis-oai-provider-linux
#** to: cgi-bin/isis-oai-provider
#* Metadata translation table (oai_dc)
#** from: htdocs/isis-oai-provider/gizmo-linux
#** to: htdocs/isis-oai-provider/gizmo
# In case it is a '''Windows operating system''', rename the directories as follows:
#* Binary executables (WWWISIS)
#** from: cgi-bin/isis-oai-provider-windows
#** to: cgi-bin/isis-oai-provider
#* Metadata translation table (oai_dc)
#** from: htdocs/isis-oai-provider/gizmo-windows
#** to: htdocs/isis-oai-provider/gizmo

'''NOTES''':
# Be sure that all binary executable files have execute rights either in the command line, or through CGI interface;
# All binary executables are 32 bits version;
# There are 64 bits version files compiled only for Linux.

==Configuring files==

Rename the sample configuration files as follows:

  $ cd htdocs/isis-oai-provider/
  $ mv oai-config-sample.php oai-config.php
  $ mv oai-databases-sample.php oai-databases.php

Modify the '''oai-config.php''' and '''oai-databases.php''' files according to the steps below:

=== oai-config.php ===

* change the variable DATABASE_PATH to the 'bases' directory of current installation

 DATABASE_PATH=/home/www/my-iah/bases

* change the variable NAME to a label that best identify the instance

 NAME=MyIAHdb

* change the variable EMAIL to the mail address of the person in charge of data 

 EMAIL=me@institution.org

* change the variables IDPREFIX and IDDOMAIN according to the domain information of your instance

 IDPREFIX=br

 IDDOMAIN=bvs

* set the variable EARLIESTDATESTAMP to a date close to the beginning of data recording

 EARLIESTDATESTAMP=1998-12-30

===oai-databases.php===

Each database must be configured having in mind the following structure and mandatory elements:

 [set-spec]

 name=
 description=
 database=
 mapping=
 prefix=oai_date_
 isis_key_length=<1660|1030>
 identifier_field=<tag>
 datestamp_field=<tag>

* '''[set-spec]''' starts and describes a section for that database and identifies the logical name of that set. This information is presented in the verb ListSets and it is also part of the unique identifier for each document within the set.

e.g.
 [lilacs]

* The '''name''' variable is the label to the data set to be displayed in the ListSets verb.

e.g.
 name=LILACS

* the '''description''' variable is the content of description showed in the ListSets verb.

e.g.
 description="LILACS Database"

* the '''database''' variable has the path and the database master file name.

e.g.
 database=/home/www/my-iah/bases/iah/dblil

* the '''mapping''' refers to the filename format used to do the mapping of contents. (Located in map/ directory)

e.g.
 mapping=lilacs-dc.pft
 
* the '''prefix''' stands for a prefix for the date field. This should be inserted in the FST file used by the invertion process. 

e.g.
 prefix=oai_date_

inversion sample to be included in the LILACS.FST
 93 0 |oai_date_|v93^*/

* the '''isis_key_length''' specifies the minimum and maximum key length used to invert data. Pay attention to the version according to the database source (e.g.. LILACS is 1660, IAH is 1030)

e.g.
 isis_key_length=1660

* the '''identifier_field''' informs the tag for the unique identifier of records

e.g.
 identifier_field=2

* the '''datestamp_field''' informs the tag for record creation date on the record

e.g.
 datestamp_field=93

Therefore, when the user needs to add new databases to the configuration file, it is only required to fullfil the fields above accordingly and append them to the file.

'''NOTE''': provided that section name is also the database name, no database duplicates are allowed.

==Testing==

Test the application by opening the internet browser and accessing the domain name as: http://nome_do_servidor/isis-oai-provider/

E.g. http://isis-oai-provider.local/isis-oai-provider/


[[Category: Applications]]
[[Category: RST]]
[[Category: Interface]]

==Testing==

Test the application calling your browser and informing your server name like: http://your_server_name/isis-oai-provider/

Ex. http://isis-oai-provider.local/isis-oai-provider/


[[Category: Applications]]
[[Category: RST]]
[[Category: Interface]]