Contribute to the DSpace Development Fund

The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.

One of the limiting factors to the adoption of DSpace by the community has historically been the the difficulty in installing DSpace and all of its prerequisites. This goal of this guide is to provide a simplistic path that will get a user up-and-running as quickly as possible.

The simple act of installing DSpace is actually quite simple, as changing between DSpace versions (eg between 1.6 and 1.7) can be done in a few minutes, however is it the installation and configuration of the prerequisites that is usually time consuming and difficult. Within Ubuntu, this is standard stuff, so we can have Ubuntu do all of that dirty work for us. The following is steps that are performed from Terminal, the command line interface in Ubuntu.

This how-to was originally written for Ubuntu 10.10 (Maverick Meerkat) and has been tested with Ubuntu 11.04 (Natty Narwhal).

Install Prerequisites

Make sure your sources are up to date before beginning

sudo apt-get update

Install the server stack of Tomcat (web server) and PostgreSQL (database)

sudo apt-get install tasksel
sudo tasksel

  • Select the following packages

    [*] LAMP server
[*] PostgreSQL database
[*] Tomcat Java server

Install the Compile / Build tools

sudo apt-get install ant maven2

Configure the Prerequisite Software

Create the database user (dspace)

sudo su postgres
createuser -U postgres -d -A -P dspace
exit

Allow the database user (dspace) to connect to the database

sudo vi /etc/postgresql/8.4/main/pg_hba.conf
# Add this line to the configuration: local all dspace md5
sudo service postgresql restart

Create the dspace database

createdb -U dspace -E UNICODE dspace

Configure Tomcat to know about the DSpace webapps.

sudo vi /etc/tomcat6/server.xml
# Insert the following chunk of text just above the closing </Host>

<!-- Define a new context path for all DSpace web apps -->
<Context path="/xmlui" docBase="/dspace/webapps/xmlui" allowLinking="true"/>
<Context path="/sword" docBase="/dspace/webapps/sword" allowLinking="true"/>
<Context path="/oai"   docBase="/dspace/webapps/oai"   allowLinking="true"/>
<Context path="/jspui" docBase="/dspace/webapps/jspui" allowLinking="true"/>
<Context path="/lni"   docBase="/dspace/webapps/lni"   allowLinking="true"/>
<Context path="/solr"  docBase="/dspace/webapps/solr"  allowLinking="true"/>

Download and Install DSpace

Create the [dspace] directory.

The [dspace] directory is where the running dspace code will reside.

sudo mkdir /dspace

Download the Source Release

The source release allows you to customize every aspect of DSpace. This step downloads the compressed archive from SourceForge, and unpacks it in your current directory. The dspace-1.x.x-src-release directory is typically referred to as [dspace-src]. 

wget http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.7.2/dspace-1.7.2-src-release.tar.bz2
tar -xvjf dspace-1.7.2-src-release.tar.bz2

Compile and Build DSpace

The source release that has been obtained is human readable source code, and must be compiled to machine code for the server to run it. "mvn package" compiles the source code, and "ant" will do all the work necessary to initialize the database with the DSpace schema, and copy all of the compiled machine code to a location where the web server can serve it.

ant fresh_install will populate the dspace database and [dspace] directory with new information. This will overwrite any existing installation of DSpace that you may have.
For upgrades the better command to use would be ant update, as it doesn't alter the database or modify your assetstore.

cd dspace-1.7.2-src-release
mvn -U package
cd dspace/target/dspace-1.7.2-build.dir
sudo ant fresh_install

Fix Tomcat permissions, and restart the Tomcat server

This guide follows the convention where the tomcat user will own all of the files in [dspace], so we have to change the owner of the files to tomcat6. Restarting tomcat will deploy the dspace webapps that are now ready to be viewed.

sudo chown tomcat6:tomcat6 /dspace -R
sudo service tomcat6 restart

Test it out in your browser

That is all that is required to install DSpace on Ubuntu. There are two main webapps that provide a similar turn-key repository interface

http://localhost:8080/xmlui

http://localhost:8080/jspui

(OPTIONAL) Change to using Sun/Oracle Java JDK

An optional step that can be done after installation would be to switch to the Sun/Oracle Java JDK. The tasksel task to install Tomcat installs the default OpenJDK which is a viable form of Java, however the official recommendation of DSpace is to use the Sun/Oracle Java JDK which offers better performance and other proprietary enhancements.

Note: Recent Change to Java Distribution

Oracle has changed their partner distribution license, which means that Canonical/Ubuntu has had to purge Sun-Java-6 from their repository. Thus, updating Ubuntu will remove Sun-Java from your system, and installing Sun-Java from the partner repository will no longer work.

See more: https://lists.ubuntu.com/archives/ubuntu-security-announce/2011-December/001528.html

Enable the Canonical Partners repository.

The Sun Java is available in the partners repository which makes for an easy installation. From the GUI this can be changed by going to Software Sources. Change "natty" to the name of the Ubuntu version you're using (if you aren't using Ubuntu 11.04)

sudo vi /etc/apt/sources.list
# Uncomment the line: deb http://archive.canonical.com/ubuntu natty partner
sudo apt-get update

Install Sun Java

sudo apt-get install sun-java6-jdk sun-java6-plugin

Change the in-use Java to Sun Java, as opposed to OpenJDK

First we list the available jdk's installed on the system, then we set the sun java to be the new default.

sudo update-java-alternatives -l
# java-6-openjdk 1061 /usr/lib/jvm/java-6-openjdk
# java-6-sun 63 /usr/lib/jvm/java-6-sun
sudo update-java-alternatives -s java-6-sun

Tomcat ignores the system default and continues to use OpenJDK. To make Tomcat use Sun Java instead, add the following line to /etc/default/tomcat6:

JAVA_HOME=/usr/lib/jvm/java-6-sun

You will need to restart Tomcat to make it pick up the change (sudo service tomcat6 restart).

  • No labels

13 Comments

  1. Nate Poell

    I've installed this on both Ubuntu 10.04 and 11.04 (just today!) and while these instructions are great, there are maybe one or two edits I'd recommend:

    1. The mvn command requires sudo privileges, as does the "tar -xvjf dspace-1.7.0-src-release.tar.bz2" command
    2. I tried several times installing DSpace while only the default-jdk was installed, and it never worked.  I always ran into weird encoding errors.  Both times after I installed openjdk-6-jdk, the installation went smoothly.

    That's it.  Thank you so much for creating this guide!
    tar -xvjf dspace-1.7.0-src-release.tar.bz2

  2. Richard Pearce-Moses

    Not clear which user account I should use to do this work.  I did a lot under my personal account, but would it be better to have a default account "dspace"?  Or does that conflict (or confuse) other users?

    Very helpful.  Thanks. 

  3. Oscar Duarte

    Thanks for this guide. I'm not sure, but I think the dspace user creation is missed:sudo useradd -m dspace
    sudo passwd dspace
    sudo mkdir /dspace
    sudo chown dspace /dspace

    1. nueces...

      there is not necessity of a new user dspace for the setup, the files are owned for the user tomcat6, that is the same that run the tomcat server.

  4. Unknown User (schweer@waikato.ac.nz)

    Just to clarify:

    • The tar -xvjf and the mvn command do not require sudo because you do these in the home directory of whatever user you're running this with, not in the /dspace directory. The ant fresh_install command copies all relevant files to the /dspace directory.
    • You can use any account to run this under, no need for a dspace user. As nueces... says above, the files are owned by the tomcat6 user and this is also the user account that runs the server. The dspace user is used only for the database -- ie it is a database user (role), not a user account in Ubuntu.

  5. Hilton Gibson

    Here is something in more detail: http://wiki.lib.sun.ac.za/index.php/SUNScholar/Dspace

  6. Quang Vo

    I think the step Compile and Build DSpace is not very clear. When build was finished, it cannot run if we don't copy / move it to /dspace as preparation above.

    So:

    cd dspace-1.7.2-src-release
mvn -U package
cd dspace/target/dspace-1.7.2-build.dir
sudo ant fresh_install

    should be:

    cd dspace-1.7.2-src-release
mvn -U package
cd dspace/target/dspace-1.7.2-build.dir
sudo ant fresh_install
# we are current dspace/target/dspace-1.7.2-build.dir now
sudo cp -R * /dspace

    Anything else?

  7. winter snow

    Hi,

    I'm trying to install DSpace on Ubuntu 12.04 but I've hit a snag at the step for "Configure the prerequisite software". I'm a bit new to Ubuntu so that might be part of the reason. My problem is, after I enter the command

    sudo vi /etc/postgresql/8.4/main/pg_hba.conf

    I don't know as to how to proceed to actually edit the file, add the recommended line and persists (save) the changes. I've tried opening the file on LeafPad but was denied permission. I've tried typing the suggested code (with some difficulty) but afterwards, I was stuck as to how to "Save" the changes.Since no one else has raised this issue, I guess I'm having trouble because I'm not used to Ubuntu.

    I'd really appreciate any help to pass this hurdle. Thanks

    1. winter snow

      never mind. a friend of mine told me i can replace "vi" with "nano" to use the nano editor. so i'm progressing ok now

  8. winter snow

    So my struggle continues. I've successfully completed most of the steps, but in "Compile and Build Dspace" after running

    mvn -U package

    i can't cd into the dspace/targer. The folder doesn't exist. When and where is it created? and how can i fix this?

    Thanks

    1. Tim Donohue

      Hi,

      We recommend posting questions about DSpace errors to the DSpace Technology Listserv (dspace-tech):
      https://groups.google.com/d/forum/dspace-tech

      Posting your questions to the mailing list ensures that others can help you resolve your problems (which is extremely useful when it is a problem that others may have encountered in the past).  In addition, you are much more likely to get an immediate response via email than via comments on wiki pages.

      Finally, just as a note...the directory you need to "cd" into is "dspace/target" (NOT "dspace/targer").

      1. Tim Donohue

        One other thing to note...the official Installation instructions for DSpace are linked from:

        All Documentation

        So, if you are installing a more recent version of DSpace (newer than 1.7), you should follow the most recent documentation's instructions on installing DSpace.

        1. winter snow

          thanks for the information. I'll refer to the mailing list for any other problem i might encounter

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.