Wednesday, January 18, 2012

DSpace 1.8.1 Upgrade Procedure

Upgrade DSpace from version 1.7.1 to version 1.8.1

Notes

1) The tutorial below records the steps used to upgrade our DSpace instance at Bromley College.

2) The upgrade process involves building DSpace from source because we use a custom hierarchical authentication module at Bromley.


This tutorial assumes you are initially logged in as user dspace

Just to be on the safe side take a backup of the database:

cd
pg_dump -U dspace -f /home/dspace/dspace_backup_180112 dspace

Download and unpack the source code:

lynx http://sourceforge.net/projects/dspace/files/DSpace%20Stable/1.8.1/
tar -xzvf /home/dspace/dspace-1.8.1-src-release.tar.gz

Stop Tomcat and the handle server:

su - root
service tomcat stop
service handle stop (n/a with standbyvle test server)
exit

Apply the Bromley College customisations to the file LDAPHierarchicalAuthentication.java

Replace the getSpecialGroups code with the customised version (this is specifically for our installation):

nano /home/dspace/dspace-1.8.1-src-release/dspace-api/src/main/java/org/dspace/authenticate/LDAPHierarchicalAuthentication.java

Copy over the stylesheets and the Bromley College logo from version 1.7.1:

cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/styles.css.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/header-default.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/layout/footer-default.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/home.jsp
cp /home/dspace/dspace-1.7.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif /home/dspace/dspace-1.8.1-src-release/dspace-jspui/dspace-jspui-webapp/src/main/webapp/image/logo.gif

Build DSpace (note can take up to 15 minutes):

cd /home/dspace/dspace-1.8.1-src-release
mvn -U clean package

With the move from DSpace 1.7.x to 1.8.x there have been major changes to the configuration files. Many of the directives that used to be in the dspace.cfg file have now been put into separate configuration files in the /home/dspace/config/modules directory. Note that these new files will not be present until after ant has been run to update DSpace.

The first step is to backup the old dspace.cfg file and obtain a clean copy of the new dspace.cfg file:

cp /home/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg.1.7.1
cp /home/dspace/dspace-1.8.1-src-release/dspace/config/dspace.cfg /home/dspace/config/dspace.cfg.1.8.1

Enter custom settings into dspace.cfg.1.8.1 and then overwrite dspace.cfg. Note that the diff command can be very useful in comparing old and new configuration files:

diff /home/dspace/config/dspace.cfg.1.7.1 /home/dspace/config/dspace.cfg.1.8.1
nano /home/dspace/config/dspace.cfg.1.8.1
cp /home/dspace/config/dspace.cfg.1.8.1 /home/dspace/config/dspace.cfg

Update DSpace:

cd /home/dspace/dspace-1.8.1-src-release/dspace/target/dspace-1.8.1-build
ant -Dconfig=/home/dspace/config/dspace.cfg update

The new configuration files will have now appeared in the /home/dspace/config/modules directory. It is now necessary to compare these new files with the appropriate sections in the old dspace.cfg file and modify the directives in the new files appropriately.

Note: I particularly ran into problems here with the path to the solr statistics server as our installation of DSpace is on a Tomcat server with non standard port allocations and is behind Apache. The path I ended up using in the solr-statistics.cfg and discovery.cfg configuration files in the config/modules directory was http://127.0.0.1/solr/statistics

The database schema has changed slightly between DSpace 1.7.1 and 1.8.1 so it is necessary to run the following upgrade script:

psql -U dspace -f dspace-1.8.1-src-release/dspace/etc/postgres/database_schema_17-18.sql dspace

Run the following scripts to clean up and re-index the site:

cd /home/dspace/bin
dspace cleanup
dspace index-init
dspace filter-media

As the root user, start Tomcat and the handle server. Restart Apache and it works :)

su - root
service tomcat start
service handle start
service httpd restart
exit

Just to make sure view the source code of the DSpace homepage, where the metadata will confirm the new version number:

meta name="Generator" content="DSpace 1.8.1

Running the following script updates any old statistics files to work with DSpace 1.8.x

dspace stats-util -b -r


Making subsequent configuration changes

If any configuration changes to source files or jsp files need to be made it is necessary to use the -Doverwrite=false switch with ant to prevent the existing customised configuration files being overwritten. Typical commands are shown below:

cd /home/dspace/dspace-1.8.1-src-release
mvn -U clean package
cd /home/dspace/dspace-1.8.1-src-release/dspace/target/dspace-1.8.1-build
ant -Dconfig=/home/dspace/config/dspace.cfg -Doverwrite=false update