Upgrading DSpace

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.
• Statistics data: what to back up depends on what you were using before: the options are the default SOLR statistics, optional Elastic Search statistics, or the legacy statistics. Legacy stats utilizes the dspace.log files, Elastic Search stats stores data in [dspace]/elasticsearch, SOLR Statistics stores data in [dspace]/solr/statistics. A simple copy of the data directory should give you a point of recovery, should something go wrong in the update process. We can't stress this enough, your users depend on these statistics more than you realize. You need a backup.

Update Prerequisite Software (as necessary)

DSpace 6.x requires the following versions of prerequisite software:

• Java 7 (Oracle or OpenJDK)
• Apache Maven 3.0.5 or above
• Apache Ant 1.8 or above
• Database
  • PostgreSQL 9.4 or above, OR 
  • Oracle 10g or above
• Tomcat 7 or above

Refer to the Prerequisite Software section of "Installing DSpace" for more details around configuring and installing these prerequisites.

Upgrade Steps

1. Download DSpace 5.x: Either download DSpace 5.x from DSpace.org or check it out directly from the Github repository. 
   1. NOTE: 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 User Interface customizations or other customizations (if needed or desired).  If you have made any local customizations to your DSpace installation they may need to be migrated over to the new DSpace. 
   1. NOTE: If you are upgrading across many versions of DSpace at once (e.g. from 1.x.x to 5.x), you may find it easier to first upgrade DSpace, and then attempt to migrate over your various customizations. Because each major version of DSpace tends to add new configurations and features to the User Interface, older customizations may require more work to "migrate" to the latest version of DSpace. In some situations, it may even be easier to "start fresh", and just re-customize the brand new User Interface with your local color scheme, header/footer, etc.
   2. Customizations are typically housed in one of the following places:
      1. JSPUI modifications: [dspace-source]/dspace/modules/jspui/src/main/webapp/
      2. XMLUI modifications: [dspace-source]/dspace/modules/xmlui/src/main/webapp/
      3. Config modifications: [dspace]/config

3. Edit the build.properties file (if needed) ([dspace-source]/build.properties).  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

   The above command will re-compile the DSpace source code and build its "installer". You will find the result in [dspace-source]/dspace/target/dspace-installer

   Defaults to PostgreSQL settings

   Without any extra arguments, the DSpace installation package is initialized for PostgreSQL. If you use Oracle instead, you should build the DSpace installation package as follows:
   mvn -Ddb.name=oracle -U clean package

   Enabling and building the DSpace 5 Mirage 2 theme

   Mirage 2 is a responsive theme for the XML User Interface, added as a new feature in DSpace 5. It has not yet replaced the Mirage 1 theme as the XMLUI default theme.

   To enable Mirage 2, add the following to the  <themes>  section of  src/dspace/config/xmlui.xconf , replacing the currently active theme:
   

     <theme name="Mirage 2" regex=".*" path="Mirage2/" /> 

   It is important to do this before executing the maven build.

   Mirage 2 is not yet activated in the default "mvn package" build. To include it as part of the build, run:
    

       mvn -U clean package -Dmirage2.on=true

   The speed of this specific step of the build can be increased by installing local copies of the specific dependencies required for building Mirage 2. The Mirage 2 developer documentation provides detailed instructions for these installations. After the installation of these dependencies, you can choose to run:
    

       mvn -U clean package -Dmirage2.on=true -Dmirage2.deps.included=false

   Warning: The Mirage 2 build process should NOT be run as "root". It must be run as a non-root user. For more information see: Mirage 2 Common Build Issues

5. Stop Tomcat (or servlet container). Take down your servlet container. 
   1. 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 Installation. Update the DSpace installation directory with the new code and libraries. Issue the following commands:

   cd [dspace-source]/dspace/target/dspace-installer
   ant update

   The above command will also automatically upgrade all your existing Solr indexes (e.g. for Discovery, Statistics, OAI-PMH) to the latest version. For large instances, this may take some time. But, it is important to ensure that your indexes are usable by the latest version of DSpace.

   1. If the Solr index upgrade fails, you may need to Manually Upgrade your Solr Indexes.  See the "Troubleshooting Upgrade Issues" section below.
7. Update your DSpace Configurations. You should review your configuration for new and changed configurations in DSpace 5.x. 
   1. In the specific case of dspace.cfg it is recommended to start with a fresh copy of the file from the new version and copy your site-specific settings from the old file.  Read the new file carefully to see if you need (or want) other alterations. 
   2. Please notice that as of DSpace 4, the default search and browse support has changed from the old Lucene/DBMS-based method to Discovery.
   3. It is recommended to review all configuration changes that exist in the config directory, and its subdirectories. It is helpful to compare your current configs against a clean checkout of your current version to see what you have customized. You might then also want to compare your current configs with the configs of the version you are upgrading to. A tool that compares files in directories such as Meld or DiffMerge is useful for this purpose.
      1. Upgrading from 4.x to 5.x, notice that file config/crosswalks/google-metadata.properties uses google.citation_author instead of google.citation_authors

8. Decide which DSpace Web Applications you want to install. DSpace comes with a variety of web applications (in [dspace]/webapps), each of which provides a different "interface" to your DSpace.  Which ones you install is up to you, but there are a few that we highly recommend (see below):

   1. "xmlui" = This is the XML-based User Interface, based on Apache Cocoon. It comes with a variety of out-of-the-box themes, including Mirage 1 (the default) and Mirage 2 (based on Bootstrap).Between the "xmlui" and "jspui", you likely only need to choose one.

   2. "jspui" = This is the JSPUI-based User Interface, which is based on Bootstrap. Between the "xmlui" and "jspui", you likely only need to choose one.

   3. "solr" (required) = This is Apache Solr web application, which is used by the "xmlui" and "jspui" (for search & browse functionality), as well as the OAI-PMH interface. It must be installed in support of either UI.

   4. "oai" = This is the DSpace OAI interface. It allows for metadata and bitstream (content-file) harvesting, supporting OAI-PMH (Protocol for Metadata Harvest) and OAI-ORE (Object Reuse and Exchange) protocols
   5. "rest" = This is the DSpace REST API
   6. "sword" = This is the DSpace SWORDv1 interface. More info on SWORD protocol and its usage.
   7. "swordv2" = This is the DSpace SWORDv2 interface. More info on SWORD protocol and its usage.
   8. "rdf" = This is the DSpace RDF interface supporting Linked (Open) Data.

9. Deploy DSpace Web Applications. If necessary, copy the web applications 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.

10. Upgrade your database (optional, but recommended for major upgrades). As of DSpace 5, the DSpace code will automatically upgrade your database (from any prior version of DSpace).  By default, this database upgrade occurs automatically when you restart Tomcat (or your servlet container).  However, if you have a large repository or are upgrading across multiple versions of DSpace at once, you may wish to manually perform the upgrade (as it could take some time, anywhere from 5-15 minutes for large sites).

    1. First, you can optionally verify whether DSpace correctly detects the version of your DSpace database. It is very important that the DSpace version is detected correctly before you attempt the migration:

       [dspace]/bin/dspace database info
       # Look for a line at the bottom that says something like:
       # "Your database looks to be compatible with DSpace version ___"

    2. In some scenarios, if your database's "sequences" are outdated, inconsistent or incorrect, a database migration error may occur (in your DSpace logs). In order to AVOID this scenario, you may wish to manually run the "update-sequences.sql" script PRIOR to upgrade. This "update-sequences.sql" script will auto-correct any possible database sequence issues. In the future, we plan to automate this step to avoid any sequence problems (see DS-2480 ticket):

       # Example for a PostgreSQL database named "dspace"
       psql -U dspace -f [dspace]/etc/postgres/update-sequences.sql

    3. Then, you can upgrade your DSpace database to the latest version of DSpace. (NOTE: check the DSpace log, [dspace]/log/dspace.log.[date], for any output from this command)

       [dspace]/bin/dspace database migrate

    4. More information on this new "database" command can be found in Database Utilities documentation.
11. Remove deprecated Database Browse Tables (optional, but recommended)
    1. By default, DSpace now uses Discovery (backed by Solr) for its Search and Browse engine. Discovery offers additional features like filtered (or faceted) searching, and "access aware" searching which was not offered by the Legacy Search and Browse system. We highly recommend using Discovery for a better Search and Browse experience. In the future, the Legacy Search and Browse system likely will be removed.

    2. As long as you plan to use the default settings in DSpace (with Discovery enabled), you can safely remove any old Legacy browse tables (named "bi_*", where "bi" = browse index). To do so, simply run: 

       [dspace]/bin/dspace index-db-browse -f -d

    3. The contents of one more leftover Legacy browse table needs to be removed, the "communities2item" table. From an SQL client, execute the following SQL (and commit the changes/purge the recyclebin if you're using Oracle):

       DELETE FROM COMMUNITIES2ITEM;

12. Restart Tomcat (servlet container). Now restart your servlet container (Tomcat/Jetty/Resin) and test out the upgrade.
    1. Upgrade of database: If you didn't manually upgrade your database in the previous step, then your database will be automatically upgraded to the latest version. This may take some time (seconds to minutes), depending on the size of your repository, etc. Check the DSpace log ([dspace]/log/dspace.log.[date]) for information on its status.

    2. Reindexing of all content for search/browse: If your database was just upgraded (either manually or automatically), all the content in your DSpace will be automatically re-indexed for searching/browsing. As the process can take some time (minutes to hours, depending on the size of your repository), it is performed in the background; meanwhile, DSpace can be used as the index is gradually filled. But, keep in mind that not all content will be visible until the indexing process is completed. Again, check the DSpace log ( [dspace]/log/dspace.log.[date]) for information on its status.

13. Reindex SOLR Stats. If you were previously using SOLR stats, the schema changed with DSpace 5; if you are upgrading from any version earlier than 5x, you will need to reindex your stats in order to ensure all of your stats data conforms to the new schema specification. NOTE: it is safe to run a reindex on a live site, the script will store incoming usage data in a temporary core.
    

     

14. Check your cron / Task Scheduler jobs.  In recent versions of DSpace, some of the scripts names have changed. 

    1. Check the Scheduled Tasks via Cron documentation for details.  Especially pay attention to the Solr Index optimization commands, which ideally should be run regularly (as noted in the previous step).

Troubleshooting Upgrade Issues

Manually Upgrading Solr Indexes

If you run into issues with the auto-upgrade of your Solr search/browse indexes (during the final part of the ant update step), then you may need to manually upgrade your Solr indexes. Depending on the type of failure, there are a few possible fixes.

1. If the "ant update" process failed to download the lucene-core-3.5.0.jar, in order to upgrade a DSpace 1.6.x, 1.7.x or 1.8.x index.
   1. You can manually download the lucene-core-3.5.0.jar from http://search.maven.org/remotecontent?filepath=org/apache/lucene/lucene-core/3.5.0/lucene-core-3.5.0.jar 
   2. Place the lucene-core-3.5.0.jar in your [dspace-source]/dspace/target/dspace-installer/ directory (i.e. the directory where you ran "ant update" from)
   3. Re-Run "ant update". This time, it should find the lucene-core-3.5.0.jar locally and re-attempt the upgrade of your Solr indexes.
2. If some other error occurred, you may need to manually upgrade your Solr indexes.
   1. Upgrading from DSpace 1.6.x, 1.7.x or 1.8.x: In DSpace 1.x versions, we used and older version of Solr which is no longer compatible with the current version of Solr.
      

      1. If you are using an older version of DSpace, you will see errors similar to this one until you manually upgrade your index:

         Caused by: org.apache.lucene.index.IndexFormatTooOldException: Format version is not supported (resource: segment _386q in resource ChecksumIndexInput(MMapIndexInput(path="/space/dspace/solr/statistics/data/index/segments_37m6"))): 2.x. This version of Lucene only supports indexes created with release 3.0 and later.

      2. Manually upgrading your Solr index involves temporarily downloading an older version of Lucene (on which Solr is based), and calling its IndexUpgrader script, e.g.

         # Download Lucene 3.5.0, which can upgrade older Solr/Lucene indexes
         wget "http://search.maven.org/remotecontent?filepath=org/apache/lucene/lucene-core/3.5.0/lucene-core-3.5.0.jar" -O lucene-core-3.5.0.jar
         
         # Then, actually upgrade the indexes by loading the lucene-core-3.5.0.jar and calling IndexUpgrader
         
         # Upgrade the Usage Statistics index. Run this if you have Solr Usage Statistics enabled in your UI.
         java -cp lucene-core-3.5.0.jar org.apache.lucene.index.IndexUpgrader [dspace]/solr/statistics/data/index/
          
         # Upgrade the OAI-PMH indexes. Run this if you use the "oai" webapp.
         java -cp lucene-core-3.5.0.jar org.apache.lucene.index.IndexUpgrader [dspace]/solr/oai/data/index/
          
         # NOTE: You do not need to upgrade the Discovery Search and Browse indexes as they will be automatically rebuilt on upgrade (See previous upgrade step)

      3. At this point in time, your older indexes will now be compatible with Solr / Lucene 3.5.  At this point they are readable by the latest version of Solr. 
      4. However, as a final step, you should still optimize each of these indexes using the commands detailed in the "Upgrading from DSpace 3.x or Above" step below

   2. Upgrading from DSpace 3.x or above: DSpace provides optimization commands for all Solr indexes. Which ones you need to run depend on which features you are using in DSpace. 

      # First, ensure your Tomcat is started up. All of the below commands will call Solr directly, which requires Tomcat to be running.
       
      # Optimize Usage Statistics (based on Solr). Run this if you have Usage Statistics enabled in your UI.
      [dspace]/bin/dspace stats-util -o
       
      # Optimize OAI-PMH indexes (based on Solr). Run this if you use the "oai" webapp.
      [dspace]/bin/dspace oai import -o
       
      # NOTE: You should not need to optimize the Discovery Search and Browse indexes, as they will be automatically rebuilt on upgrade (See previous upgrade step)
      # However, you still may wish to schedule optimizing of Discovery Search & Browse (via cron or similar)
      # [dspace]/bin/dspace index-discovery -o

"Property was circularly defined" errors

If, after running ant update, you see an error like this:

[dspace-src]/dspace/target/dspace-installer/build.xml:88: Property ____ was circularly defined.

This usually means that you are attempting to build the new version of DSpace using an outdated build.properties file. Specifically, the property which is reported as being "circularly defined" is likely missing from your local [dspace-source]/build.properties file. To resolve this issue, simply:

1. Check your local build.properties file to ensure it is up to date, specifically looking for properties which are missing and adding them in.
2. Rebuild DSpace (e.g. mvn -U clean package). See Upgrade Steps (step #4) above.
3. Continue the rest of the upgrade process (again from step #4) above