Installing & Configuring the Islandora Module and Servlet Filter

This chapter will show you how to install and configure the Islandora module and servlet filter.

Pre-installation software checklist

The Islandora framework relies upon a number of other open source applications. Before beginning the installation of any Islandora modules, ensure:

1. You have Drupal installed and properly configured with:

• Clean URLs enabled
• The Drupal file system set to public*
  *Note: Currently, only Drupal 6.xx is supported by Islandora and it must be running on PHP 5.2 at a minimum.

2. You have Fedora installed and properly configured:

• Ensure you can use the admin tools in Fedora to ingest and purge (e.g. http://localhost:8080/fedora/admin).
• A requirement for collection objects: To make the module more flexible and useful we have also made some specific decisions regarding our Fedora objects. For the module to be able to browse collections, your collection objects must have a hasModel entry in the RELS-EXT Datastream that points to islandora:collectionCModel. This lets the module know that the object represents a collection and it will then query for objects that are members of this collection.

3. Other requirements beyond what is needed by Fedora and Drupal include:

• PHP5-curl
• PHP-soap
• PHP5-xsl

You will also need to install any dependencies that are needed for the Solution Packs you are using.

To take full advantage of the module you will need to enable the Fedora Resource Index in the Fedora config file.  You should also have Fedora GSearch installed, although this step does not need to be completed prior to installing the Module and Servlet Filter. Fedora GSearch includes Lucene and enables full text searching.

At the end of this installation, you will be ready to populate your site with digital assets and be capable of accepting Solution Packs.

Drupal Servlet Filter

The Drupal Servlet Filter allows the Fedora Repository to use Drupal’s database for authentication, including integration with Drupal user roles.

1. Download the Latest Version of the Drupal Servlet Filter

Download the Drupal Filter files from the Release Notes and Downloads page. Extract the contents of the archive, and make sure you choose the correct JAR file for a) your version of Fedora and b) your authentication type (FeSL or legacy).

 If you have used the default config and installation file above, you are using legacy authentication.

Place the JAR file in $FEDORA_HOME/tomcat/webapps/fedora/WEB-INF/lib

.  Note: This directory will not exist on your system until Fedora has been run at least once.

2. Make the Fedora Repository Aware of the New Filter

Follow the instructions for either a) Legacy Authentication, or b) FeSL Authentication:

<filter>
<filter-name>DrupalFilter</filter-name>
<filter-class>ca.upei.roblib.fedora.servletfilter.FilterDrupal</filter-class>
</filter>

<filter-mapping>
<filter-name>DrupalFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

fedora-auth
{
org.fcrepo.server.security.jaas.auth.module.XmlUsersFileModule required
debug=true;
ca.upei.roblib.fedora.servletfilter.DrupalAuthModule required
debug=true;
};

3. Configure the Drupal Servlet Filter

Create the file filter-drupal.xml in $FEDORA_HOME/server/config. Copy the following text as a template, then modify the attributes of the <connection>  tag to match the server, port, database name, username and password of your site's Drupal database.

<?xml version="1.0" encoding="UTF-8"?>
<!--File to hold drupal connection info for the FilterDrupal servlet filter.  For multisite drupal installs you can include multiple
connection elements.  We will query all the databases and assume any user in any drupal db with the same username and password are the same
user.  We will gather all roles for that user from all databases.  This is a potential security risk if a user in one drupal db has the same
username and password as another user in a separate drupaldb.  We are also assuming all drupal dbs to be mysql.  This file should be located
in the same directory as the fedora.cfcg file-->

<FilterDrupal_Connection>
  <connection server="localhost" dbname="drupaldb" user="dbuser" password="password" port="3306">
    <sql>
                  <!--Different sql statement for each connection.  This is for drupal multisites that are setup using one database with
                  table prefixes.  We don't do this but some people might.-->
                  SELECT DISTINCT u.uid AS userid, u.name AS Name, u.pass AS Pass, r.name AS Role FROM (users u LEFT JOIN users_roles ON
                  u.uid=users_roles.uid) LEFT JOIN role r ON r.rid=users_roles.rid WHERE u.name=? AND u.pass=?;
    </sql>
  </connection>
</FilterDrupal_Connection>

4. Stop and Restart Fedora

This will enable the Drupal Servlet Filter.

5. Test the Drupal Servlet Filter

Access your Fedora Admin client (http://your.site:8080/fedora/admin) using your Drupal login credentials.

The Islandora Module

The Islandora module is a Drupal module written to allow the Drupal content management system to act as a front end to a Fedora Digital Repository. The module enables viewing and management of Fedora objects. This includes ingest, purge, add Datastream, searching and browsing by collection. This version of the module does not store any data regarding any of the Fedora Objects in the Drupal database. The only data stored in Drupal is the configuration data telling Drupal how to connect to Fedora.

How to Install the Islandora Module

1. Download the latest versions of the following required modules and place the uncompressed contents of the module in your sites/all/modules or the sites/default/modules directory. For multi-site Drupal environments, refer to the Drupal.org instructions:
   
   1. From Drupal.org:
      
      1. ImageAPI
      2. jQuery Update
      3. jQuery UI
   2. From Islandora:
      
      1. Content Model Forms
      2. Objective Forms
      3. PHP Lib
      4. Tabs
      5. XML Forms (Package includes the following modules)
         
         • XML Form API
         • XML Form Builder
         • XML Form Elements
         • XML Schema API
2. Download the latest version of the Islandora module and place the uncompressed contents of the module in your sites/all/modules or the sites/default/modules directory.
3. Enable the module by logging in to Drupal and navigating to Administer > Modules. Locate and enable the Islandora Repository module. 
4. Navigate to 'Islandora Configure' under Administer > Site Configuration.
5. Click the 'Install' button under 'Islandora Core' to create the islandora:root and islandora:collectionCModel Fedora objects. 

You have now enabled the Islandora module. Navigate to your newly created Digital Repository menu item to view the objects from your Fedora Repository through your web site.

How to Configure the Islandora Module

If you encounter problems with your Islandora configuration, check the following:

1. Your Fedora connection information is correct: The Fedora URLs in the Islandora Configure panel (Administer > Site configuration > Islandora Configure) should point to your Fedora server's IP or domain name. Note: You may experience connection issues if you specify 'localhost' instead of the IP address of your Fedora server. Therefore, we recommend using the actual IP address of the server.
2. You have the appropriate user permissions to determine who can do what to Fedora objects from within Drupal.
3. Your Lucene index is set to the index name configured in GSearch, if GSearch has been installed and enabled. 

The Fedora Default Display Object PID and Fedora Datastream ID are the defaults used by Drupal when it can't find a PID/Datastream.  Ensure these point to an object/Datastream that is known to exist in your Fedora repository. So, for example, you could use an image that will communicate to your users that the object they are looking for was not found, or is not available. Remember that only the PID namespaces permitted in the Islandora module's config pages will be visible to users of a given site. 

Developer Tip: You can always retrieve the most up-to-date information via our git repository at https://github.com/islandora. However, the most stable release of Islandora will always be available at http://islandora.ca/download.