Running DSpace on a Root URL
March 22, 2011 2 Comments
By default a DSpace installation will be set up to run on a URL something like
http://mydomain.com/jspui/ 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.
http://mydomain.com/. 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.
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:
- Tomcat is installed to
- 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
/oai in the DSpace installation posts referenced above.
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:
<version>-build.dir/config/dpace.cfg /usr/local/dspace/config/dspace.cfg /usr/local/tomcat/conf/server.xml /etc/httpd/conf.d/jk.conf
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
/jspui) from the end of the
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:
This will create a new file in
dspace.cfg.new. Replace the existing config file with this new version:
cd [dspace]/config mv dspace.cfg.new 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
[dspace-source]/dspace/target/dspace-<version>-build.dir and run
ant update_configs. This should then create a file called
[dspace]/config/dspace.cfg.new 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
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
cd [dspace]/webapps/ ln -s xmlui ROOT
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.
Edit the tomcat
conf/server.xml file making the following changes:
- In the
Hostelement, change the
appbaseattribute value from
- Comment out any
Contextelements for the paths
Edit the apache mod_jk configuration file
- Change the paths in the
/*respectively (or similar for any references to
- Comment out the
JkMountdirectives for paths
After restarting apache and tomcat you should be able to access the repository on the root URL and the OAI interface on