Unsupported Release

This documentation relates to DSpace 1.8.x, an old, unsupported version. Looking for another version? See all documentation.

As of January 2015, DSpace 1.8.x is no longer supported. We recommend upgrading to a more recent version of DSpace. See DSpace Software Support Policy.

In the notes below [dspace] refers to the install directory for your existing DSpace installation, and [dspace-1.4.x-source] to the source directory for DSpace 1.4.x. Whenever you see these path references, be sure to replace them with the actual path names on your local system.

Upgrade Steps

  1. First and foremost, make a complete backup of your system, including:
    • A snapshot of the database
    • The asset store ([dspace]/assetstore by default)
    • Your configuration files and localized JSPs
  2. Download the latest DSpace 1.4.x source bundle and unpack it in a suitable location (not over your existing DSpace installation or source tree!)
  3. Copy the PostgreSQL driver JAR to the source tree. For example:
    cd  [dspace]/lib
    cp postgresql.jar  [dspace-1.4.x-source]/lib
  4. Note: Licensing conditions for the handle.jar file have changed. As a result, the latest version of the handle.jar file is not included in this distribution. It is recommended you read the new license conditions and decide whether you wish to update your installation's handle.jar. If you decide to update, you should replace the existing handle.jar in [dspace-1.4.x-source]/lib with the new version.
  5. Take down Tomcat (or whichever servlet container you're using).
  6. Your DSpace configuration will need some updating:
    • In dspace.cfg, paste in the following lines for the new stackable authentication feature, the new method for managing Media Filters, and the Checksum Checker.
      #### Stackable Authentication Methods #####
      # Stack of authentication methods
      #  (See org.dspace.eperson.AuthenticationManager)
      plugin.sequence.org.dspace.eperson.AuthenticationMethod = \
      #### Example of configuring X.509 authentication
      #### (to use it, add org.dspace.eperson.X509Authentication to stack)
      ## method 1, using keystore
      #authentication.x509.keystore.path = /var/local/tomcat/conf/keystore
      #authentication.x509.keystore.password = changeit
      ## method 2, using CA certificate
      #authentication.x509.ca.cert = ${dspace.dir}/config/mitClientCA.der
      ## Create e-persons for unknown names in valid certificates?
      #authentication.x509.autoregister = true
      #### Media Filter plugins (through PluginManager) ####
      plugin.sequence.org.dspace.app.mediafilter.MediaFilter = \
      	org.dspace.app.mediafilter.HTMLFilter, \
      # to enable branded preview: remove last line above, and uncomment 2
      	lines below
      #   org.dspace.app.mediafilter.WordFilter,
      	org.dspace.app.mediafilter.JPEGFilter, \
      #   org.dspace.app.mediafilter.BrandedPreviewJPEGFilter
      filter.org.dspace.app.mediafilter.PDFFilter.inputFormats = Adobe PDF
      filter.org.dspace.app.mediafilter.HTMLFilter.inputFormats = HTML,
      filter.org.dspace.app.mediafilter.WordFilter.inputFormats = Microsoft
      filter.org.dspace.app.mediafilter.JPEGFilter.inputFormats = GIF,
      	JPEG, image/png
      s = GIF, JPEG, image/png
      #### Settings for Item Preview ####
      webui.preview.enabled = false
      # max dimensions of the preview image
      webui.preview.maxwidth = 600
      webui.preview.maxheight = 600
      # the brand text
      webui.preview.brand = My Institution Name
      # an abbreviated form of the above text, this will be used
      # when the preview image cannot fit the normal text
      webui.preview.brand.abbrev = MyOrg
      # the height of the brand
      webui.preview.brand.height = 20
      # font settings for the brand text
      webui.preview.brand.font = SansSerif
      webui.preview.brand.fontpoint = 12
      #webui.preview.dc = rights
      #### Checksum Checker Settings ####
      # Default dispatcher in case none specified
      # Standard interface implementations. You shouldn't need to tinker
      	with these.
      # check history retention
    • If you have customized advanced search fields (search.index.n fields, note that you now need to include the schema in the values. Dublin Core is specified as dc. So for example, if in 1.3.2 you had:
      search.index.1 = title:title.alternative
      That needs to be changed to:
      search.index.1 = title:dc.title.alternative
    • If you use LDAP or X509 authentication, you'll need to add org.dspace.eperson.LDAPAuthentication or org.dspace.eperson.X509Authentication respectively. See also configuring custom authentication code.
    • If you have custom Media Filters, note that these are now configured through dspace.cfg (instead of mediafilter.cfg which is obsolete.)
    • Also, take a look through the default dspace.cfg file supplied with DSpace 1.4.x, as this contains configuration options for various new features you might like to use. In general, these new features default to 'off' and you'll need to add configuration properties as described in the default 1.4.x dspace.cfg to activate them.
  7. Your 'localized' JSPs (those in jsp/local) now need to be maintained in the source directory. If you have locally modified JSPs in your [dspace]/jsp/local directory, you will need to merge the changes in the new 1.4.x versions into your locally modified ones. You can use the diff command to compare your JSPs against the 1.4.x versions to do this. You can also check against the DSpace CVS.
  8. In [dspace-1.4.x-source] run:
    ant -Dconfig= [dspace]/config/dspace.cfg update
  9. The database schema needs updating. SQL files containing the relevant file are provided. If you've modified the schema locally, you may need to check over this and make alterations.
    • For PostgreSQL: [dspace-1.4.x-source]/etc/database_schema_13-14.sql contains the SQL commands to achieve this for PostgreSQL. To apply the changes, go to the source directory, and run:psql -f etc/database_schema_13-14.sql [DSpace database name] -h localhost
    • For Oracle: [dspace-1.4.x-source]/etc/oracle/database_schema_13-14.sql should be run on the DSpace database to update the schema.
  10. Rebuild the search indexes: [dspace]/bin/index-all
  11. Copy the .war Web application files in [dspace-1.4-source]/build to the webapps sub-directory of your servlet container (e.g. Tomcat). e.g.:
    cp  [dspace-1.4-source]/build/*.war
    If you're using Tomcat, you need to delete the directories corresponding to the old .war files. For example, if dspace.war is installed in [tomcat]/webapps/dspace.war, you should delete the [tomcat]/webapps/dspace directory. Otherwise, Tomcat will continue to use the old code in that directory.
  12. Restart Tomcat.
  • No labels