Test Drive

Putting mds Through Its Paces

Although the focus of mds is code, design, libraries, etc, it is useful to be able actually to run it sometimes. What follows is a rough, terse guide to getting mds up and running and creating a (minimal) repository with it.

Prerequisites

As with DSpace, one needs a relational database, some disk storage for the asset store, and an app server (servlet container). Currently mds requires:

RDBMS - Only PostgreSQL has been done, and versions 8.4 or better ought to suffice. Prepare the database just as you would DSpace, although I find it handy to name the database 'mds' instead of 'dspace' so that I can run them side-by-side in a DB server instance.

App Server - mds requires containers that support the Servlet 3.0 spec, so that means Tomcat 7, Jetty 8, Glassfish 3, etc. I have only tested Tomcat 7.

Java 7 is required to build or run mds.

Getting the code

Github mds (i.e. here) is the best choice. Most top-level directories ('kernel', 'admin' etc) are mds modules, which are the units of assembly, so to speak. One exception is the directory 'mdsa', which a maven project for sharing an assembly descriptor. This is required if you want to build the modules, so the first order of business is to download and install this project in your local maven repository:

mvn install

Then you can build the modules themselves, starting with 'kernel'. Simply download (or clone in git, etc) the kernel, and run

mvn install

(since most all other modules declare a dependency on the kernel, it too should be locally installed in the maven repo, not just packaged). For other modules (here, we will only describe two: 'admin' and 'oai-pmh'):

mvn package

will suffice.

Installing the code

A good orientation to this section is the wiki page Modules. We assume you have read this, and will use the terminology here. We also assume you have read Runtime Injectable Configuration in order to set any site-specific configuration values. Simply select any directory (local to where you want to install) as the [stage] directory, and copy the target/dsm-kernel-1.0-SNAPSHOT-dsmod.zip (target relative to wherever you built the kernel module) into it. Unzip the archive, then

cd bin
edit setenv.sh
./dspace install kernel

(you may need to chmod the 'dspace' batch file to be executable first). setenv.sh holds the site-specific configuration, and there are surprisingly few properties you have to set: 'MDS_SITE_HOME', the DB settings, etc

After the kernel has been installed, you can proceed to the other modules, having copied them into subdirectories of the [stage]/modules directory and unzipped them (we use the directories 'admin' and 'oai' to put the archives in - the name is immaterial):

./dspace install admin
./dspace install oai

In the case of the OAI-PMH module, We must also copy the 'war' file into the Tomcat container 'webapps'. All wars can be found in the '[stage]/webapps/deploy' directory. The war file has not been localized, so to inform Tomcat how to use it, we must add:

<Parameter name="dspaceHome" value="[install]"/>

to the conf/context.xml in the Tomcat installation (where '[install]' is of course replaced by wherever the installation is located). You must also copy the 'bin/setenv.sh' to Tomcat's 'CATALINA/bin' directory so that site-specific configurations are loaded.

Running the code

The installation process should be complete, so we can begin to use the instance. As with DSpace, the first order of business is to create an administrator:

[install]/bin/dspace create-administrator

Next, we can import some actual content. The admin module installed above includes a command-line tool ContentImport, which is a descendent of ItemImport batch tool, except that it also creates communities, collections, etc. I created a sample data file (that has a simple community, collection, and 2 items) 'saf2.zip', which you can obtain from here. Unzip to any location [import], we can add this data to the repository:

[install]/bin/dspace import add -s <import> -m <mapfile> -e admin@foo.bar

To see the result, fire up Tomcat, and look at the content from the OAI-PMH perspective:

http://localhost:8080/oai/request?verb=ListRecords&metadataPrefix=oai_dc

(assuming you deployed the war to 'oai' in Tomcat).