SUNScholar/Upgrading/DSpace/General Notes

From Libopedia
Jump to navigation Jump to search
Back to Software Upgrade


My Upgrade Procedure (Hilton Gibson)

We let users know well in advance that the production server will be offline for this period.
Please note:
  1. Radical changes between versions of DSpace make upgrades a very time consuming and risky process.
  2. Prepare yourself well in advance on a development server.

Using an Ubuntu desktop, the program "meld" is installed. "meld" allows you to compare two folders for differences.

To do a comparison, the working version is copied to my desktop and the new version is extracted to my desktop as well.

Using meld I investigate all the differences and update the new version with new settings as appropriate.

When I am satisfied that the new version has most of my customisation from the old version, then I test on my development server.

I do more debugging on the development server as needed and then finally activate it on the production server and test.

On the production server we test for a couple of days.

Step 1 - Backup Databases

This must done before attempting any upgrade actions.

After logging in as the "dspace" user, type the following to backup the databases.

Create a backup folder.

mkdir $HOME/backup
chmod 0777 $HOME/backup


Become the postgres user. Supply the "dspace" user password after hitting "Enter".

sudo -i

Become the "postgres" user.

su - postgres

Dump the PostgreSQL database

pg_dump dspace > /tmp/dspace-db.sql

Return to "dspace" user.


Copy the database backup to the dspace user's backup folder

cp /tmp/dspace-db.sql $HOME/backup/


Before upgrading optimise the SOLR databases

Before backing up or upgrading DSpace, make sure to run any maintenance scripts on the SOLR database. See below.
$HOME/bin/dspace stats-util -o

Backup the SOLR databases

Stop Tomcat (If using Ubuntu 12.04 LTS then replace tomcat7 with tomcat6)

sudo service tomcat7 stop

Create backup folder

mkdir $HOME/backup

Backup the SOLR databases

cp -Rv $HOME/solr/ $HOME/backup/

Start Tomcat

sudo service tomcat7 start

SOLR Index Upgrading

Please read the following before upgrading;

Step 2 - Backup folders with customisations

Backup the config folder.

cp -Rv $HOME/config $HOME/backup/

Backup the module overlay folders for the XMLUI theme.

cp -Rv $HOME/source/dspace/modules/xmlui $HOME/backup/

Step 3 - Do the upgrade

Check the following first

  • Remember to update the sources link to point to the new DSpace version before running database upgrade scripts.

Release Notes

Please check the DSpace documentation and the following links:

Step 4 - Database upgrades

Check the following first

If you have database permission errors, check the db installation at:

4.1 - Update database sequences

 sudo -i
 su - postgres
 psql -U %dspace-database-username% -f /home/dspace/source/dspace/etc/postgres/update-sequences.sql %dspace-database-name%

Change the items enclosed in percent quotes (%) to match the installation of DSpace on your system.

Also see:

4.2 - Update database schema's

For DSpace versions >=5.X


Also see:

For DSpace versions <=4.X

The following steps only apply to DSpace versions <=4.X

This should be the 1st step of the upgrade process after the backups above.

To do database upgrades use the psql command as the postgres user.

Login to the server, become the "root" user, then change to the "postgres" user.

sudo -i
su - postgres

Now run the DB upgrades one-by-one from the current version up to the version you are upgrading to, by copying and pasting the following into the command line and pressing enter:

DSpace version 1.1.x to DSpace version 1.2.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_11-12.sql dspace
DSpace version 1.2.x to DSpace version 1.3.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_12-13.sql dspace
DSpace version 1.3.x to DSpace version 1.4.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_13-14.sql dspace
DSpace version 1.4.x to DSpace version 1.5.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_14-15.sql dspace
DSpace version 1.5.x to DSpace version 1.6.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_15-16.sql dspace
DSpace version 1.6.x to DSpace version 1.7.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_16-17.sql dspace
DSpace version 1.7.x to DSpace version 1.8.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_17-18.sql dspace
DSpace version 1.8.x to DSpace version 3.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_18-3.sql dspace
DSpace version 3.x to DSpace version 4.x
psql -U dspace -f $HOME/source/dspace/etc/postgres/database_schema_3-4.sql dspace

Step 5 - Update /home/dspace file permissions and ownership

If you upgraded from tomcat6 to tomcat7, then type the following to update file permissions and ownership:

sudo chown dspace.tomcat7 -R /home/dspace
sudo chmod 0777 -R /home/dspace
sudo adduser tomcat7 dspace
sudo adduser dspace tomcat7

Tip: Things might go quicker if you stop a few services, while you are updating files.

Upgrade checklist

Using whatever method suits you best, begin the upgrade as per the official DSpace documentation.

Some tips for upgrading are below.

Release Notes

Check the release notes before continuing.


Merge any configs from the following folder and sub-folders.


Good programs for doing config file and folder comparisons are listed below.


Merge any "modules" configurations from the following folder and sub-folders.


For example: If the new DSpace version has an updated Mirage theme, then check those updates with your previously customised version of the Mirage theme.

For more info about theming, see: Theme modification

XMLUI Language

Check for differences between the old "messages.xml" file and the new one.

For more info about language, see: Language modification

XMLUI Discovery/Search

Check for differences with the "discovery.xml" file.

For more info about discovery, see: Search Indexes

SOLR Services

Since the release of DSpace version 3.2 the SOLR server is used for search indexes and the OAI interface.

Check these services for any tasks to perform before and after the upgrade.

Handle Server

The new DSpace version will probably have new handle server code.

Therefore you will probably need to re-build your handle server config files.

Check the link below for details.

Daily Tasks

Check for upgrades to daily tasks. Click on the link below.

Proposed Software Release Process

Reference Architecture

Click on the heading above.

Software Release Cadence

Click on the heading above.

The Debian Way

(Keep on clicking on the image to zoom in for greater detail)


Automated Software Testing