Old Release

This documentation relates to an old version of DSpace, version 4.x. Looking for another version? See all documentation.

This DSpace release is end-of-life and is no longer supported.

These instructions are valid for any of the following upgrade paths:

  • Upgrading 3.0 to 3.1 (or 3.2)
  • Upgrading 3.1 to 3.2

For more information about specific fixes released in each 3.x version, please refer to the appropriate release notes:

In the notes below [dspace] refers to the install directory for your existing DSpace installation, and [dspace-source] to the source directory for DSpace 3.x. Whenever you see these path references, be sure to replace them with the actual path names on your local system.

Backup your DSpace

Before you start your upgrade, it is strongly recommended that you create a backup of your DSpace instance. Backups are easy to recover from; a botched install/upgrade is very difficult if not impossible to recover from. The DSpace specific things to backup are: configs, source code modifications, database, and assetstore. On your server that runs DSpace, you might additionally consider checking on your cron/scheduled tasks, servlet container, and database.

Make a complete backup of your system, including:

  • Database: Make a snapshot/dump of the database. For the PostgreSQL database use Postgres' pg_dump command. For example:

    pg_dump -U [database-user] -f [backup-file-location] [database-name]
  • Assetstore: Backup the directory ([dspace]/assetstore by default, and any other assetstores configured in the [dspace]/config/dspace.cfg "assetstore.dir" and "assetstore.dir.#" settings)
  • Configuration: Backup the entire directory content of [dspace]/config.
  • Customizations: If you have custom code, such as themes, modifications, or custom scripts, you will want to back them up to a safe location.

Upgrade Steps

  1. Download DSpace 3.x: Either download DSpace 3.x from DSpace.org or check it out directly from the Github repository. If you downloaded DSpace do not unpack it on top of your existing installation. Refer to Installation Instructions, Step 3 for unpacking directives.
  2. Merge any customizations (if needed).  If you have made any local customizations to your DSpace installation they may need to be migrated over to the new DSpace. For minor upgrades, there are often fewer changes, but it is still worth checking to see if any effect your customizations. Customizations are typically housed in one of the following places:
    • JSPUI modifications: [dspace-source]/dspace/modules/jspui/src/main/webapp/
    • XMLUI modifications: [dspace-source]/dspace/modules/xmlui/src/main/webapp/
    • Config modifications: [dspace]/config
  3. Edit the build.properties file (if needed) ([dspace-source]/build.properties).  As this is a minor upgrade, your previous 3.x build.properties file should work fine.  However, you may want to double check your settings. Any settings changed in this build.properties file are automatically copied over to the final dspace.cfg file during the "Build DSpace" process (in the next step).  For more information on the build.properties file, see "The build.properties Configuration Properties File" section of the Configuration Reference documentation.

  4. Build DSpace. Run the following commands to compile DSpace:

    cd [dspace-source]/dspace/
mvn -U clean package

    You will find the result in [dspace-source]/dspace/target/dspace-[version]-build.dir . Inside this directory is the compiled binary distribution of DSpace. Before rebuilding DSpace ('package'), the above command will clean out any previously compiled code ('clean') and ensure that your local DSpace JAR files are updated from the remote maven repository.

  5. Stop Tomcat. Take down your servlet container. For Tomcat, use the $CATALINA_HOME/shutdown.sh script. (Many Unix-based installations will have a startup/shutdown script in the /etc/init.d or /etc/rc.d directories.)
  6. Update DSpace.

    1. Update the DSpace installed directory with the new code and libraries. Issue the following commands:

      cd [dspace-source]/dspace/target/dspace-[version]-build.dir
ant update
    2. No database changes have been made in DSpace 3.1 or 3.2.  So, there is no need to update your existing DSpace 3.x database.
  7. Update your DSpace Configurations (if needed). There are no new required configurations in DSpace 3.1 or 3.2. So, your existing DSpace 3.x configurations should work fine.  However, there are a few minor, optional updates to be aware of:
    1. In DSpace 3.0, the OAI Harvester (XMLUI only) settings were accidentally removed from the [dspace]/config/modules/oai.cfg file. They have been reinstated in DSpace 3.1 or above. Please see DS-1461 for more info.
    2. In DSpace 3.2, it is again possible to custom the <description> tag of the OAI-PMH "Identify" response. This is achieved through a new (optional) configuration "description.file" within the [dspace]/config/modules/oai.cfg file. Please see DS-1479 for more info.

  8. Refresh Browse and Search Indexes. Though there are not any database changes, it is a good policy to rebuild your search and browse indexes when upgrading to a new release.  To do this, run the following command from your DSpace install directory (as the dspace user):

    [dspace]/bin/dspace index-init

    1. Refresh Discovery: If you are using Discovery (Solr) for search/browse, you will also need to refresh Discovery indexes by running the following command:

      [dspace]/bin/dspace update-discovery-index -f

  9. Deploy Web Applications. If necessary, copy the web applications files from your [dspace]/webapps directory to the subdirectory of your servlet container (e.g. Tomcat):

    cp -R [dspace]/webapps/* [tomcat]/webapps/

    See the installation guide for full details.

  10. Restart servlet container. Now restart your Tomcat/Jetty/Resin server program and test out the upgrade.
  • No labels

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