This documentation relates to an old version of DSpace, version 3.x. Looking for another version? See all documentation.
In the notes below
[dspace] refers to the install directory for your existing DSpace installation, and [dspace-source] to the source directory for DSpace 1.7.x. Whenever you see these path references, be sure to replace them with the actual path names on your local system.
Before upgrading you need to check you are using the current recommended minimum versions of Java (1.6), Maven (2.0.8 or above) and ant (1.7 or above). For more details, see the current listing of Prerequisite Software
- Backup Your DSpace. First, and foremost, make a complete backup of your system, including:
- A snapshot of the database. To have a "snapshot" of the PostgreSQL database, you need to shut it down during the backup. You should also have your regular PostgreSQL Backup output (using Postgres' pg_dump command).
- The asset store (
- Your configuration files and customizations to DSpace (including any customized scripts).
- Download DSpace 1.7.x Retrieve the new DSpace 1.7.x source code either as a download from DSpace.org or check it out directly from the SVN code repository. If you downloaded DSpace do not unpack it on top of your existing installation. Refer to Installation Instructions, Step 3 for unpacking directives.
- Stop Tomcat. Take down your servlet container. For Tomcat, use the
$CATALINA_HOME/bin/shutdown.shscript. (Many Unix-based installations will have a startup/shutdown script in the
- Apply any customizations. If you have made any local customizations to your DSpace installation they will need to be migrated over to the new DSpace. These are normally housed in one of the following places:
- JSPUI modifications:
- XMLUI modifications:
- JSPUI modifications:
- Update Configuration Files. Some parameters have changed and some are new. You can either attempt to make these changes in your current 1.6.x
dspace.cfgfile, or you can start with a new 1.7
dspace.cfgand re-modify it as needed. Configuration changes are noted below:
- *CORRECTION* There was a missing hyphen "-" in the property key for mail character set:
- *CORRECTION* This was moved from the end of the solr configuration section to just under Logging Configurations:
- *CHANGE* The MediaFilter is now able to process Power Point Text Extracter
- *CHANGE* The Crosswalk Plugin Configuration has changed with additional lines. Edit your file accordingly:
- *CHANGE* The Packager Plugin Configuration has changed considerably. Carefully revise your configuration file:
- *CHANGE* The Mets Ingester configuration has change and been updated. Carefully edit:
- *NEW* A new property has been added to control the discovery index for the Event System Configuration:
- *NEW* License bundle display is now configurable. You are able to either display or suppress.
- *CORRECTION* Thumbnail generation. The width and height of generated thumbnails had a missing equal sign.
- *CORRECTION and ADDITION* Authority Control Settings have changed. Formerly called ChoiceAuthority, it is now referred to as DCInputAuthority.
- *NEW* Controls autocomplete for authority control
- *NEW* You are now able to order your bitstreams by sequence id or file name.
- *NEW* DSpace now includes a metadata mapping feature that makes repository content discoverable by Google Scholar:
- *NEW* XMLUI is now able to concatenate CSS, JS and JSON files:
- *NEW* XMLUI Mirage Theme. This is a new theme with it's own configuration:
- *NEW* OAI Response default change.
- *CHANGE* EPDCX property key has been renamed.
- *NEW* New SOLR Statistic Property keys:
- Build DSpace. Run the following commands to compile DSpace.:
[dspace-source]/dspace/target/dspace-[version]-build.dir. Inside this directory is the compiled binary distribution of DSpace. Before rebuilding DSpace, 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 code repository.
You will find the result in
- Update DSpace. Update the DSpace installed directory with the new code and libraries. Issue the following commands:
- Update the Database. You will need to run the 1.6.x to 1.7.x database upgrade script.
- For PostgreSQL: (Your database name is by default 'dspace'). Example:
- For Oracle: Execute the upgrade script, e.g. with sqlplus, recording the output:
- Start SQL*Plus with
sqlplus [connect args]
- Record the output:
SQL> spool 'upgrade.lst'
- Run the upgrade script
- Turn off recording of output:
SQL> spool off
- Start SQL*Plus with
- Generate Browse and Search Indexes. It's always 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):
- Deploy Web Applications. If your servlet container (e.g. Tomcat) is not configured to look for new web applications in your
[dspace]/webappsdirectory, then you will need to copy the web applications files into the appropriate subdirectory of your servlet container. For example:
- Restart servlet container. Now restart your Tomcat/Jetty/Resin server program and test out the upgrade.
- Add a new crontab entry, or add to your system's scheduler, the following, run as the DSpace user, to enable routine maintenance of your SOLR indexes. If you do not run this command daily, it is likely your production instances of DSpace will exhaust the available memory in your servlet container