Upgrading From 4.0 to 4.x

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 4.x: Either download DSpace 4.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 4.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. Updating to 4.7 database schema:The database schema has minor updates in 4.7.  So, you will need to update your existing DSpace 4.x database. Please use the appropriate command and SQL script to update your database:
      
      • PostgreSQL: psql --user [dspace-dbms-user] -f [dspace-source]/dspace/etc/postgres/database_schema_4-47.sql [dspace-database]
        You should be prompted for the database password.
      • Oracle: sqlplus [dspace-dbms-user]/[database password] [dspace-source]/dspace/etc/oracle/database_schema_4-47.sql
      • NOTE: [dspace-dbms-user] will be the value of db.username in config/dspace.cfg. The database password will be the value of db.password. [dspace-database] will be the part of db.url following the last slash.

   3. Updating to 4.8 database schema: The database schema has minor updates in 4.8.  So, you will need to update your existing DSpace 4.7 database. (NOTE: ensure your database has been upgraded to 4.7 prior to updating to 4.8). Please use the appropriate command and SQL script to update your database:
      
      • PostgreSQL: psql --user [dspace-dbms-user] -f [dspace-source]/dspace/etc/postgres/database_schema_4-48.sql [dspace-database]
        You should be prompted for the database password.
      • Oracle: sqlplus [dspace-dbms-user]/[database password] [dspace-source]/dspace/etc/oracle/database_schema_4-48.sql
      • NOTE: [dspace-dbms-user] will be the value of db.username in config/dspace.cfg. The database password will be the value of db.password. [dspace-database] will be the part of db.url following the last slash.

7. Check whether your DSpace instance is affected by either of the below bugs.  There were a few database level bugs resolved in DSpace 4.1 and 4.2, which may require some institutions to run a script on their database content to resolve them. These do NOT affect all institutions, but you should be aware of them:
   1. Fixing the effects of DS-1536 - If your institution uses a Handle prefix which contains a period (e.g. 123.456/x), then you should run the recommended scripts (see below) on your database.
   2. Fixing the effects of DS-2036 - If your institution uses an Oracle database backend with Discovery (for search/browse), then you should run the recommended script (see below) on your database.
8. Update your DSpace Configurations (if needed). There are no new required configurations in DSpace 4.1 or 4.2. So, your existing DSpace 4.x configurations should work fine.  

9. 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-discovery -f
   

   1. If you're still using Lucene (you disabled Discovery): If you are using Lucene for search/browse, you will also need to refresh Lucene indexes by running the following command:

      [dspace]/bin/dspace index-lucene-init

10. 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.

11. Restart servlet container. Now restart your Tomcat/Jetty/Resin server program and test out the upgrade.

Fixing the effects of DS-1536

If you're affected by  Unable to locate Jira server for this macro. It may be due to Application Link configuration. , DSpace 4.1 fixes it, but you still need to fix the incorrect metadata generated by DSpace 4.0. To do so, execute the following SQL against the DSpace database. PLEASE ensure you test these scripts on a non-Production server, and also you have backed up your database PRIOR to running the scripts. Replace XXXXX with your handle prefix before the dot; e.g. if your prefix is "10123.1", replace "XXXXX" with "10123".

Instructions for Postgres

SELECT handle, text_value AS current, 'http://hdl.handle.net/'||handle as fixed 
FROM metadatavalue, metadatafieldregistry, handle 
WHERE text_value = 'http://hdl.handle.net/XXXXX'
AND metadatafieldregistry.metadata_field_id = metadatavalue.metadata_field_id
AND metadatafieldregistry.element = 'identifier'
AND metadatafieldregistry.qualifier = 'uri'
AND handle.resource_type_id = 2
AND handle.resource_id = metadatavalue.item_id;

UPDATE metadatavalue
SET text_value = 'http://hdl.handle.net/'||handle
FROM metadatafieldregistry, handle
WHERE text_value = 'http://hdl.handle.net/XXXXX'
AND metadatafieldregistry.metadata_field_id = metadatavalue.metadata_field_id
AND metadatafieldregistry.element = 'identifier'
AND metadatafieldregistry.qualifier = 'uri'
AND handle.resource_type_id = 2
AND handle.resource_id = metadatavalue.item_id;

Instructions for Oracle

SELECT handle, text_value, 'http://hdl.handle.net/'||handle AS fixed 
FROM metadatavalue, metadatafieldregistry, handle 
WHERE to_char(text_value) = 'http://hdl.handle.net/XXXXX'; 
AND metadatafieldregistry.metadata_field_id = metadatavalue.metadata_field_id 
AND metadatafieldregistry.element = 'identifier' 
AND metadatafieldregistry.qualifier = 'uri' 
AND handle.resource_type_id = 2 
AND handle.resource_id = metadatavalue.item_id; 

/* NOTE, you'll need to run this code in two stages: in SQL Developer, first run the query below, then cut/paste the results back into a new query, and run that query */


SELECT 'UPDATE metadatavalue SET text_value = ''http://hdl.handle.net/'||handle||''' WHERE metadatavalue.metadata_field_id = '||metadata_field_id
 FROM metadatavalue 
  JOIN metadatafieldregistry USING(metadata_field_id) 
  JOIN handle ON handle.resource_id = metadatavalue.item_id 
 WHERE metadatafieldregistry.element = 'identifier' 
  AND metadatafieldregistry.qualifier = 'uri' 
  AND handle.resource_type_id = 2 
  AND to_char(text_value) = 'http://hdl.handle.net/XXXXX' 
;

Fixing the effects of DS-2036

If you previously upgraded DSpace from 1.8.x to 3.0 and you use Oracle as your DBMS, you may be affected by Unable to locate Jira server for this macro. It may be due to Application Link configuration. .  The following SQL statement should correct the problem. PLEASE ensure you test these scripts on a non-Production server, and that you have backed up your database PRIOR to running the scripts.

UPDATE item SET discoverable=1 WHERE discoverable IS NULL;