Page History

...

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.

...

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:

         Code Block
         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.

         Code Block

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

      Code Block

      # 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 stat-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