Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Ensure that your database is compatible: Starting with DSpace 6.x, there are new database requirements for DSpace (refer to the Prerequisite Software section of "Installing DSpace" for full details).
    1. PostgreSQL databases: PostgreSQL 9.4 or above is required and the "pgcrypto" extension must be installed.
      1. Notes on installing pgcrypto
        1. On most Linux operating systems (Ubuntu, Debian, RedHat), this extension is provided in the "postgresql-contrib" package in your package manager. So, ensure you've installed "postgresql-contrib".
        2. On Windows, this extension should be provided automatically by the installer (check your "[PostgreSQL]/share/extension" folder for files starting with "pgcrypto")
      2. Enabling pgcrypto on your DSpace database. (Additional options/notes in the Installation Documentation)

        Code Block
        # Login to your "dspace" database as a superuser
        psql --username=postgres dspace
        # Enable the pgcrypto extension on this database
        CREATE EXTENSION pgcrypto;


    2. Oracle databases: Oracle database have no additional requirements at this time.
  2. Download DSpace 7.x: Either download DSpace 7.x from DSpace.org or check it out directly from the Github repository
    1. NOTE: You will need both the services component (DSpace/DSpace in Github) and the user interface component (DSpace/dspace-angular in Github).
    2. NOTE: If you downloaded DSpace do not unpack it on top of your existing installation. Refer to Installation Instructions, Step 3 for unpacking directives.
  3. Migrate to new User Interface. If you have made any local customizations to your DSpace installation they must be re-implemented in the new DSpace, because the old UIs have been replaced
  4. Anchor
    dump_solr
    dump_solr
    From your old version of DSpace, dump your authority and statistics Solr cores.  (Only necessary when upgrading from DSpace 6 or older & you want to keep both your authority records and/or SOLR Statistics)

    Code Block
    languagebash
    [dspace]/bin/dspace solr-export-statistics -i authority
    [dspace]/bin/dspace solr-export-statistics -i statistics

    The dumps will be written to the directory [dspace]/solr-exportThis may take a long time and require quite a lot of storage.  In particular, the statistics core is likely to be huge, perhaps double the size of the content of solr/statistics/data.  You should ensure that you have sufficient free storage.

    This is not the same as the disaster-recovery backup that was done above.  These dumps will be reloaded into new, reconfigured cores later.

    If you are sharding your statistics data, you will need to dump each shard separately.  The index names for prior years will be statistics-YYYY (for example:  statistics-2017 statistics-2018 etc.)  The current year's statistics shard is named statistics and you should dump that one too.

  5. Download DSpace 7.x: Either download DSpace 7.x from DSpace.org or check it out directly from the Github repository
    1. NOTE: You will need both the server component (DSpace/DSpace in Github) and the user interface component (DSpace/dspace-angular in Github).
  6. Replace your old build.properties file with a local.cfg (ONLY REQUIRED if upgrading from DSpace 5 or previous): As of DSpace 6.0, the build.properties configuration file has been replaced by an enhanced local.cfg configuration file. Therefore, any old build.properties file (or similar [dspace-source]/*.properties files) WILL BE IGNORED. Instead, you should create a new local.cfg file, based on the provided [dspace-source]/

    Replace your old build.properties file with a local.cfg (REQUIRED if upgrading from DSpace 5 or previous): As of DSpace 6.0, the build.properties configuration file has been replaced by an enhanced local.cfg configuration file. Therefore, any old build.properties file (or similar [dspace-source]/*.properties files) WILL BE IGNORED. Instead, you should create a new local.cfg file, based on the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE and use it to specify all of your locally customized DSpace configurations.  This new local.cfg can be used to override ANY setting in any other configuration file (dspace.cfg or modules/*.cfg). To override a default setting, simply copy the configuration into your local.cfg and change its value(s).  For much more information on the features of local.cfg, see the Configuration Reference documentation and the local.cfg Configuration File section on that page.

    Code Blockcd [dspace-source] cp

    dspace/config/local.cfg.EXAMPLE and use it to specify all of your locally customized DSpace configurations.  This new local.cfg can be used to override ANY setting in any other configuration file (dspace.cfg or modules/*.cfg). To override a default setting, simply copy the configuration into your local.cfg and change its value(s).  For much more information on the features of local.cfg, see the Configuration Reference documentation and the local.cfg Configuration File section on that page.

    Code Block
    cd [dspace-source]
    cp dspace local.cfg
    
    # Then edit the local.cfg, specifying (at a minimum) your basic DSpace configuration settings.
    # Optionally, you may copy any settings from other *.cfg configuration files into your local.cfg to override them.
    # After building DSpace, this local.cfg will be copied to [dspace]/config/local.cfg, where it will also be used at runtime.

    Build DSpace Backend. Run the following commands to compile DSpace :

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

    Info
    titleDefaults 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

    Anchordump_solrdump_solrDump your authority and statistics Solr cores.  (Only when upgrading from DSpace 6 or older.)
    Code Block
    languagebash
    [dspace]/bin/dspace solr-export-statistics -i authority
    [dspace]/bin/dspace solr-export-statistics -i statistics
    The dumps will be written to the directory [dspace]/solr-export.  This may take a long time and require quite a lot of storage.  In particular, the statistics core is likely to be huge, perhaps double the size of the content of solr/statistics/data.  You should ensure that you have sufficient free storage.
    This is not the same as the disaster-recovery backup that was done above.  These dumps will be reloaded into new, reconfigured cores later.
    If you are sharding your statistics data, you will need to dump each shard separately.  The index names for prior years will be statistics-YYYY (for example:  statistics-2017 statistics-2018 etc.)  The current year's statistics shard is named statistics and you should dump that one too.
  7. 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.)
  8. .EXAMPLE local.cfg
    
    # Then edit the local.cfg, specifying (at a minimum) your basic DSpace configuration settings.
    # Optionally, you may copy any settings from other *.cfg configuration files into your local.cfg to override them.
    # After building DSpace, this local.cfg will be copied to [dspace]/config/local.cfg, where it will also be used at runtime.


  9. Build DSpace Backend. Run the following commands to compile DSpace Update DSpace Installation. Update the DSpace installation directory with the new code and libraries. Issue the following commands:

    Code Block
    cd [dspace-source]/dspace/target/dspace-installer
    ant update
    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

    Info
    titleDefaults 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


  10. 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.)
  11. Update DSpace Installation. Update the DSpace installation directory with the new code and libraries. Issue the following commands:

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


  12. Update your DSpace Configurations. Depending on the version of DSpace you are upgrading from, not all steps are required.  
    1. If you are upgrading from DSpace 5.x or below. If you are upgrading from DSpace 6.x you can skip these steps and move to the next bullet.
      1. Search/Browse requires Discovery: As of DSpace 6, only Discovery (Apache Solr) is supported for search/browse. Support for Legacy Search (using Apache Lucene) and Legacy Browse (using database tables) has been removed, along with all their configurations.
      2. XPDF media filtering no longer exists: XPDF media filtering, deprecated in DSpace 5, has been removed.  If you used this, you will need to reconfigure using the remaining alternatives (e.g. PDF Text Extractor and/or ImageMagick PDF Thumbnail Generator)
    2. If you are upgrading from DSpace 6.x or below.  All administrators will need to perform these steps.
      1. Review your customized configurations (recommended to be in local.cfg): As mentioned above, we recommend any local configuration changes be placed in a local.cfg Configuration File.  With any major upgrade some configurations may have changed. Therefore, it is recommended to review all configuration changes that exist in the config directory, and its subdirectories, concentrating on configurations your previously customized in your local.cfg.  See also the Configuration Reference
    Update your DSpace Configurations. Depending on the version of DSpace you are upgrading from, not all steps are required.  
    1. If you are upgrading from DSpace 5.x or below. If you are upgrading from DSpace 6.x you can skip these steps and move to the next bullet.
      1. Consider using the local.cfg file for your local configurations: As of DSpace 6, there is a new local.cfg Configuration File.  So, rather than editing the dspace.cfg (or any of the modules/*.cfg), it's recommended to simply override the default values in your own local.cfg. That way, your local.cfg can serve as the record of which configurations you have actually tweaked in your DSpace, which may help to simplify future upgrades.
        1. WARNING: in order to create this powerful ability to override configurations in your local.cfg, all modules/*.cfg files had their configurations renamed to be pre-pended with the module name.  As a basic example, all the configuration settings within the modules/oai.cfg configuration now start with "oai.".  Unfortunately, these means that DSpace 5.x configuration files are NOT guaranteed to be compatible with later versions of DSpace. For more information see the Configuration Reference.
        2. 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. After reviewing which configurations you've changed, we recommend moving all your customized configurations into your local.cfg file, as described above. Examples of how this might be accomplished are provided in the Configuration Reference.
      2. Search/Browse requires Discovery: As of DSpace 6, only Discovery (Apache Solr) is supported for search/browse. Support for Legacy Search (using Apache Lucene) and Legacy Browse (using database tables) has been removed, along with all their configurations.
      3. XPDF media filtering no longer exists: XPDF media filtering, deprecated in DSpace 5, has been removed.  If you used this, you will need to reconfigure using the remaining alternatives (e.g. PDF Text Extractor and/or ImageMagick PDF Thumbnail Generator)
    2. If you are upgrading from DSpace 6.x or below.  All administrators will need to perform these steps
      1. .
      2. Migrate or recreate your Submission configuration.  As of DSpace 7, the submission configuration has changed.  The format of the "item-submission.xml" file has been updated, and the older "input-forms.xml" has been replaced by a new "submission-forms.xml".   You can choose to either start fresh with the new v7 configuration files, or you can use the steps below to migrate your old configurations into the new format.  See the Submission User Interface for more information
        1.  First, create a temporary folder to copy your old v6 configurations into

          Code Block
          # Example of creating a [dspace]/config/temp folder for this migration
          # You must replace [dspace] with the full path of your DSpace 7 installation.
          cd [dspace]/config
          mkdir temp


        2. Copy your old (v5 or v6) "item-submission.xml" and "input-forms.xml" into that temporary folder
        3. Run the command-line migration script to migrate them to v7 configuration files

          Code Block
          # This example uses [dspace] as a placeholder for all paths.
          # Replace it with either the absolute or relative path of these files
          [dspace]/bin/dspace submission-forms-migrate -s [dspace]/config/temp/item-submission.xml -f [dspace]/config/temp/input-forms.xml


        4. The result will be two files. These are valid v7 configurations based on your original submission configuration files.
          1. [dspace]/config/item-submission.xml.migrated 
          2. [dspace]/config/submission-forms.xml.migrated 
        5. These "*.migrated" files have no inline comments, so you may want to edit them further before installing them (by removing the ".migrated" suffix).  Alternatively, you may choose to copy sections of the *.migrated files into the default configurations in the [dspace]/config/ folder, therefore retaining the inline comments in those default files.
      3. City IP Database file for Solr Statistics has been renamed. The old [dspace]/config/GeoLiteCity.dat file is no longer maintained by its provider.  You can delete it.  The new file is named GeoLite2-City.mmdb by default. The upgrade process will automatically download a copy of the new database if you don't already have it.  If you have configured a different name and/or location for this file, you should check the setting of usage-statistics.dbfile in [dspace]/config/modules/usage-statistics.cfg (and perhaps move your custom setting to local.cfg).
      4. tm-extractors media filtering (WordFilter) no longer exists:  the PoiWordFilter plugin now fulfills this function.  If you still have WordFilter configured, remove from dspace.cfg and/or local.cfg all lines referencing org.dspace.app.mediafilter.WordFilter and uncomment all lines referencing org.dspace.app.mediafilter.PoiWordFilter.
      5. Re-configure Solr URLs:  change the value of solr.server to point at your new Solr v7 service.  It will probably become something like solr.server = https://${dspace.hostname}:8983/solr.  Also review the values of
        1. discovery.search.server
        2. oai.solr.url
        3. solr.authority.server
        4. solr.statistics.server
  13. 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. "server" = (Required) This contains all of the standard back-end services:  REST, SWORD, SWORDv2, RDF, OAI.  It must be installed for the DSpace UI to work.

    2. "rest" = (Optional) This is the deprecated, old DSpace REST API.  The required, new REST API is part of "server".  If you use applications written to the pre-v7 REST API, you will need this until you have converted them.  Otherwise, it is recommended to only install the "server" webapp.
  14. Enable DSpace Web Applications. If necessary, copy the web applications from your [dspace]/webapps directory to the subdirectory of your servlet container (e.g. Tomcat):

    Code Block
    cp -R [dspace]/webapps/* [tomcat]/webapps/
    

    See the installation guide for full details.  Also move or delete superseded webapps (oai, sword, swordv2, rdf) that you may have here.

  15. Upgrade your database (optional, but recommended for major upgrades). As of DSpace 5 (and above), 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:

      Code Block
      [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 rare scenarios, if your database's "sequences" are outdated, inconsistent or incorrect, a database migration error may occur (in your DSpace logs). While this is seemingly a rare occurrence, you may choose to run the "update-sequences" command PRIOR to upgrading your database. If your database sequences are inconsistent or incorrect, this "update-sequences" command will auto-correct them (otherwise, it will do nothing).

      Code Block
      # General PostgreSQL example
      psql -U [database-user] -f [dspace]/etc/postgres/update-sequences.sql [database-name]
      
      # Example for a PostgreSQL database named "dspace", and a user account named "dspace"
      # psql -U dspace -f [dspace]/etc/postgres/update-sequences.sql dspace


    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)

      Code Block
      [dspace]/bin/dspace database migrate

      If you are upgrading from DSpace 6 or earlier, there are database changes which were previously optional but now are mandatory (specifically Configurable Workflow database changes).  Instead of (or after) the above command:

      Code Block
      [dspace]/bin/dspace database migrate ignored

      to apply these changes.

    4. The database migration should also automatically trigger your metadata/file registries to be updated (based on the config files in [dspace]/config/registries/).  However, if this update was NOT triggered, you can also manually run these registry updates (they will not harm existing registry contents) as follows:

      Code Block
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/dcterms-types.xml
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/dublin-core-types.xml
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/eperson-types.xml
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/local-types.xml
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/sword-metadata.xml
      [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/workflow-types.xml
      


    5. If the database upgrade process fails or throws errors, then you likely have manually customized your database structure (and/or backported later DSpace features to an older version of DSpace). In this scenario, you may need to do some manual migrations before the automatic migrations will succeed. The general process would be something like this:
      1. Revert back to your current DSpace database
      2. Manually upgrade just your database past the failing migration.  For example, if you are current using DSpace 1.5 and the "V1.6" migration is failing, you may need to first manually upgrade your database to 1.6 compatibility. This may involve either referencing the upgrade documentation for that older version of DSpace, or running the appropriate SQL script from under [dspace-src]/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/)
      3. Then, re-run the migration process from that point forward (i.e. re-run ./dspace database migrate)
    6. More information on the "database" command can be found in Database Utilities documentation.
    Note
    titleBy default, your site will be automatically reindexed after a database upgrade

    If any database migrations are run (even during minor release upgrades), then by default DSpace will automatically reindex all content in your site. This process is run automatically in order to ensure that any database-level changes are also immediately updated within the search/browse interfaces. See the notes below under "Restart Tomcat (servlet container)" for more information.

    However, you may choose to skip automatic reindexing. Some sites choose to run the reindex process manually in order to better control when/how it runs.

    To disable automatic reindexing, set discovery.autoReindex = false in config/local.cfg or config/modules/discovery.cfg.

    As you have disabled automatic reindexing, make sure to manually reindex your site by running [dspace]/bin/dspace discovery -b (This must be run after restarting Tomcat)

    WARNING: It is not recommended to skip automatic reindexing, unless you will manually reindex at a later time, or have verified that a reindex is not necessary. Forgetting to reindex your site after an upgrade may result in unexpected errors or instabilties.


  16. Sites with Oracle database backends (and Configurable Workflow enabled) may need to run a "repair" on your database.

    1. In version 6.3, we fixed an Oracle migration issue related to Configurable (XML) Workflow. See DS-3788.

    2. If you are upgrading an Oracle-based site to 6.3 from 6.0, 6.1 or 6.2 AND had Configurable Workflow already enabled, then you will need to manually "repair" your database to align it with the latest schema. This does not affect PostgreSQL-based backends or any sites that are upgrading from 5.x or below.

    3. Simply run the following to repair your Oracle database:  [dspace]/bin/dspace database repair

  17. Install new Solr cores and rebuild your indexes.  (Only necessary if upgrading from 6.x or below)
    1. Copy the new, empty Solr cores to your new Solr instance.

      Code Block
      languagebash
      cp -r [dspace]/solr/* [solr]/server/solr
      chown -R solr:solr [solr]/server/solr/authority [solr]/server/solr/oai [solr]/server/solr/search [solr]/server/solr/statistics


    2. Start Solr, or restart it if it is running, so that these new cores are loaded.
    3. Anchor
      reload_solr
      reload_solr
      Load authority and statistics from the dumps that you made earlier (not the disaster-recovery backup).

      Code Block
      languagebash
      [dspace]/bin/dspace solr-import-statistics -i authority
      [dspace]/bin/dspace solr-import-statistics -i statistics

      This could take quite some time.

      If you had sharded your statistics, you will need to load the dump of each shard separately.  As when dumping, the index names will be ... statistics-2017 statistics-2018 statistics.

    4. For Statistics shards only, upgrade legacy DSpace Object Identifiers (pre-6.4 statistics) to UUID Identifiers.

      Code Block
      [dspace]/bin/dspace solr-upgrade-statistics-6x -i statistics

      Again If you had sharded your statistics, you will need to run this for each shard separately. See also  SOLR Statistics Maintenance#UpgradeLegacyDSpaceObjectIdentifiers(pre-6xstatistics)toDSpace6xUUIDIdentifiers

    5. Rebuild the oai and search cores.

      Code Block
      languagebash
      [dspace]/bin/dspace oai import
      [dspace]/bin/dspace index-discovery

      If you have a great deal of content, this could take a long time.

  18. Update Handle Server Configuration. If you are using the built-in Handle server, you'll need to add the follow to the server_config section of your config.dct file:

    Code Block
    "enable_txn_queue" = "no"


  19. (Optional) Set up IP to City database for location-based statistics.  If you wish to (continue to) record the geographic origin of client activity, you will need to install (and regulary update) one of the following:
    • Either, a copy of MaxMind's GeoLite City database (in MMDB format)
      • NOTE: Installing MaxMind GeoLite2 is free.  However, you must sign up for a (free) MaxMind account in order to obtain a license key to use the GeoLite2 database.
      • You may download GeoLite2 directly from MaxMind, or many Linux distributions provide the geoipupdate tool directly via their package manager.  You will still need to configure your license key prior to usage.
      • Once the "GeoLite2-City.mmdb" database file is installed on your system,  you will need to configure its location as the value of usage-statistics.dbfile in your local.cfg configuration file
      • You can discard any old GeoLiteCity.dat database(s) found in the config/ directory (if they exist).
      • See the "Managing the City Database File" section of SOLR Statistics for more information about using a City Database with DSpace.
    • Or, you can alternatively use/install DB-IP's City Lite database (in MMDB format)
      • This database is also free to use, but does not require an account to download.
      • Once the "dbip-city-lite.mmdb" database file is installed on your system,  you will need to configure its location as the value of usage-statistics.dbfile in your local.cfg configuration file
      • See the "Managing the City Database File" section of SOLR Statistics for more information about using a City Database with DSpace.
  20. 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.

      1. If you wish to skip automatic reindexing, please see the Note above under the "Upgrade your Database" step.
  21. 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).

    2. WINDOWS NOTE: If you are running the Handle Server on a Windows machine, a new [dspace]/bin/start-handle-server.bat script is available to more easily startup your Handle Server.
  22. Migrate to new User Interface. If you have made any local customizations to your DSpace installation they must be re-implemented in the new DSpace, because the old UIs have been replaced

Troubleshooting Upgrade Issues

...