Running DSpace on a Root URL

Roadside Eating on Hylan Boulevard in Staten Island 06/1973

By default a DSpace installation will be set up to run on a URL something like or depending on which interface you prefer. In a comment on my past post regarding installing DSpace on Debian 5 I was asked how to run DSpace on the root of the URL, e.g. I had done this in the past but didn’t have a reference to hand so I tried it out on a fresh installation of DSpace 1.7. Here is what I did to get it working.

Some Caveats

Before leaping into the instructions it is important to give some context on how my DSpace installation was set up. It is following the formula set out in my posts on installing on Debian 5 and CentOS 5. This post therefore assumes that you have a similar configuration:

  • [dspace-source] is /usr/local/dspace-<version>-release/
  • [dspace] is /usr/local/dspace/
  • Tomcat is installed to /usr/local/tomcat/
  • Requests are proxied through apache using mod_jk

Also, it is very important to note that this approach changes the default document base for tomcat. This means that all access to the default tomcat applications will be lost unless you set Contexts for them in your server.xml file and specifically handle the paths for them in your jk.conf file. This is the reverse of the process used to set paths for /xmlui and /oai in the DSpace installation posts referenced above.

The steps

The process is fairly painless except for some slight confusion around the editing of the DSpace configuration files.

First back up your existing configuration, in particular these files:


Configure DSpace

Edit the DSpace configuration file for your source directory, in my case this is /usr/local/dspace-1.7.0-release/dspace/config/dspace.cfg. Make the following changes:

  • Remove any port number from the dspace.baseUrl setting
  • Remove /xmlui (or /jspui) from the end of the dspace.url setting

Manually copy these changes to the build target configuration directory, e.g. /usr/local/dspace-1.7.0-release/dspace/target/dspace-1.7.0-build.dir/config/dpace.cfg – i.e. make these changes by hand rather than copying the file.

Update the runtime configuration files:

ant update_configs

This will create a new file in [dspace]/config/ called Replace the existing config file with this new version:

cd [dspace]/config
mv dspace.cfg

An aside: note on updating the DSpace configuration

Updating the configuration files for DSpace is, it might be said, somewhat more complicated than one would have thought was necessary. This isn’t helped by the ambiguous wording of the manual which lays out a number of commands that need to be run but is not clear about the circumstances under which any of the given commands should be used.

Now, this gets kind of complicated:

The manual says that to update the runtime configuration file ([dspace]/config/dspace.cfg) it is necessary to first edit [dspace-source]/config/dspace.cfg and then cd to [dspace-source]/dspace/target/dspace-<version>-build.dir and run ant update_configs. This should then create a file called [dspace]/config/ that can be copied over the existing configuration file.

In my tests this did not work. The ant update_configs command seems to apply any chages that have been made to [dspace-source]/dspace/target/dspace-<version>-build.dir/config/dspace.cfg but not those that have been made to [dspace-source]/config/dspace.cfg.

In addition, the main DSpace build process seems to replace some tokens in the dspace.cfg file when it generates the version that goes into [dspace-source]/dspace/target/dspace-<version>-build.dir/config/. This is why I do not recommend copying the [dspace]/config/dspace.cfg version directly over the top of this file.

How far you want to go with editing the different versions of dspace.cfg depends on how concerned you are about making sure they are all in sync. The approach I have described attempts to synchronise all versions so that any future builds incorporate the changes. It is actually possible to make the changes direcly to the runtime configuration file [dspace]/config/dspace.cfg but then you are required to keep track of the changes that might be wiped out by future builds. Some people on the DSpace tech list take this approach, keeping the configuration file under source control to allow for relatively simple merging of changes.

Now back to our configuration steps.

Set root webapp

Later in this process we will be making the DSpace webapps directory the default for tomcat. In preparation for this we want to make our chosen interface the root web application. We do this by adding a symbolic link to the required webapp called ROOT:

cd [dspace]/webapps/
ln -s xmlui ROOT

Replace xmlui with jspui if you are using the JSP interface.

Note: this symbolic link will need to be recreated if you run ant update in the future.

Configure tomcat

Edit the tomcat conf/server.xml file making the following changes:

  • In the Host element, change the appbase attribute value from webapps to [dspace]/webapps
  • Comment out any Context elements for the paths /xmlui, /jspui and /oai

Configure apache

Edit the apache mod_jk configuration file /etc/httpd/conf.d/jk.conf:

  • Change the paths in the JkMount directives for /xmlui and /xmlui/* to / and /* respectively (or similar for any references to /jspui)
  • Comment out the JkMount directives for paths /oai and /oai/*

Restart services

After restarting apache and tomcat you should be able to access the repository on the root URL and the OAI interface on /oai/request.

Image credit: The U.S. National Archives via flickr

About Rob Ingram
Rob Ingram is the Technical Officer for the Repositories Support Project offering technical advice and support to UK repository networks.

2 Responses to Running DSpace on a Root URL

  1. Augusto Carvalho says:

    Thanks for the information !!
    cd [dspace]/webapps/
    ln -s xmlui ROOT

    *That helps me a lot!!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: