SUNScholar/Upgrading/DSpace/General Notes

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

PostgreSQL
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. exit

exit Copy the database backup to the dspace user's backup folder cp /tmp/dspace-db.sql $HOME/backup/

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

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;
 * https://wiki.duraspace.org/display/DSDOC5x/Upgrading+DSpace#UpgradingDSpace-ManuallyUpgradingSolrIndexes
 * https://wiki.duraspace.org/display/DSDOC5x/SOLR+Statistics+Maintenance#SOLRStatisticsMaintenance-ReindexSOLRstatistics,forupgradesorwhenevertheSolrschemaforstatisticsischanged

Backup the config folder.
cp -Rv $HOME/config $HOME/backup/

Backup the module overlay folders for the XMLUI theme.
cp -Rv $HOME//dspace/modules/xmlui $HOME/backup/

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:


 * DSpace Version 5.X
 * DSpace Version 4.X
 * DSpace Version 3.X

http://wiki.lib.sun.ac.za/index.php/SUNScholar/Install_DSpace

http://wiki.lib.sun.ac.za/index.php/SUNScholar/Customisation

Check the following first
If you have database permission errors, check the db installation at: http://wiki.lib.sun.ac.za/index.php/SUNScholar/Prepare_Ubuntu/S06

4.1 - Update database sequences
sudo -i

su - postgres

psql -U %dspace-database-username% -f /home/dspace//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: http://wiki.lib.sun.ac.za/index.php/SUNScholar/Install_DSpace/S09

For DSpace versions >=5.X
PLEASE NOTE STEP 10 IN THE LINK BELOW: https://wiki.duraspace.org/display/DSDOC5x/Upgrading+DSpace#UpgradingDSpace-UpgradeSteps

Also see: https://jira.duraspace.org/browse/DS-2480

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

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.

Features
Merge any configs from the following folder and sub-folders. $HOME//dspace/config Good programs for doing config file and folder comparisons are listed below.
 * http://meldmerge.org - For Ubuntu linux computers
 * http://winmerge.org - For Microsoft Windows computers

XMLUI Theme
Merge any "modules" configurations from the following folder and sub-folders. $HOME//dspace/modules/xmlui/src/main/webapp/

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. http://wiki.lib.sun.ac.za/index.php/SUNScholar/Handle_Server

Daily Tasks
Check for upgrades to daily tasks. Click on the link below. http://wiki.lib.sun.ac.za/index.php/SUNScholar/Daily_Admin

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
http://en.wikipedia.org/wiki/Portal:Software_Testing http://en.wikipedia.org/wiki/Selenium_(software) http://en.wikipedia.org/wiki/List_of_GUI_testing_tools http://en.wikipedia.org/wiki/Regression_testing http://en.wikipedia.org/wiki/Acceptance_testing