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:
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).
This is a choice that you made during the Fedora installation checklist. If you have used the default config and installation file provided in in our Installing Fedora page, 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.
If your Drupal and Fedora installations use different database types, Fedora will require the Drupal database driver's jar file in this directory as well. For instance, if Fedora uses PostgreSQL and Drupal uses MySQL, Fedora will require the MySQL jar file for the Drupal Servlet Filter in order to connect to the Drupal database.
2. Make the Fedora Repository Aware of the New Filter
Follow the instructions for either a) Legacy Authentication, or b) FeSL Authentication:
a. If using Legacy Authentication
New XML elements must be added in order to configure Fedora's servlet filtering.
Edit the web.xml file located in $FEDORA_HOME/tomcat/webapps/fedora/WEB-INF/ to include a reference to the Drupal Servlet Filter. Immediately after the <filter> element named XmlUserfileFilter, insert the following:
Then, immediately after the <filter-mapping> element named XmlUserfileFilter, insert the following:
b. If using FeSL Authentication
Edit the file jaas.conf located in $FEDORA_HOME/server/config/ to allow the Drupal Servlet Filter to authenticate against Drupal’s database.
Insert the following reference to the DrupalServlet filters class files:
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.
Fedora requires a separate <connection> entry for each connecting Drupal site.
<?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-->
<connection server="localhost" dbname="drupaldb" user="dbuser" password="password" port="3306">
<!--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=?;
If you use the Drupal servlet filter to connect to multiple Drupal databases there is potential for users with the same username in each database to access each others private objects. To avoid this, use the Drupal LDAP module. A Drupal multi-site environment utilizing the LDAP module for all sites ensures a unique username/site configuration.
The Drupal Filter does not currently escape the database url before attempting to connect to the Mysql database, which can cause problems if the user name or password has '%' symbol within it.
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 username and password you would use to log into your Drpual site as a user).
In the Fedora log in, you will need to offer the MD5 hash of your Drupal user's password (rather than the plaintext password). You can use the following Linux command to get this MD5 hash:
echo -n "yourpassword" | md5sum
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
- 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:
- From Drupal.org:
- jQuery Update
- jQuery UI
- From Islandora:
- Content Model Forms
- Objective Forms
- PHP Lib
- XML Forms (Package includes the following modules)
- XML Form API
- XML Form Builder
- XML Form Elements
- XML Schema API
- 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.
- Enable the module by logging in to Drupal and navigating to Administer > Modules. Locate and enable the Islandora Repository module.
- Navigate to 'Islandora Configure' under Administer > Site Configuration.
- 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
Major configuration options for the Islandora module are available on the Islandora Configuration page under Administer > Site configuration > Islandora Configure (/admin/settings/fedora_repository)
Allows you to customize the tabs available when viewing Fedora objects, and how they will display.
- Determine whether or not to allow users (with proper permissions) to view the Object Details tab (containing datastreams for that object.)
- Configure how objects details will be displayed. Please note that as a nested scheme, MODS does not display well in a Table format.
Advanced configuration options
Additional options for advanced users. More most installations the default settings do not need to be altered.
If you encounter problems with your Islandora configuration, check the following:
- Your Fedora connection information is correct: The Fedora URLs in the Islandora Configure panel 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.
- You have the appropriate user permissions to determine who can do what to Fedora objects from within Drupal.
- Your Lucene index is set to the index name configured in GSearch, if GSearch has been installed and enabled.
If you specify an IP address other than localhost in your Islandora configuration you will need to delete the following Fedora policies:
These policies can usually be found in /usr/local/fedora/data/fedora-xacml-policies/repository-policies/default
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.