Versions Compared

Old Version 1

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Tim Donohue

Saved on

Key

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

...

Release Notes / Significant Changes

DSpace 89.0 features some breaking changes which you may wish to be aware of before beginning your upgrade:

Upgrading the Backend (Server API)

...

Update Backend Prerequisite Software

DSpace 89.x requires the following updated versions of prerequisite software (when compared to DSpace 8.x). 

  • Updated: Java 17 (Oracle or OpenJDK)Updated: Apache Maven 3.8.x or above Apache Solr 9.x
  • Updated: PostgreSQL 1214.x - 1517.x (with pgcrypto installed)
  • Updated: Tomcat is now OPTIONAL.  You may instead choose to use the Runnable JAR approach to deploying the DSpace backend.8

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

...

Info
titleMigration guide also available

If during the upgrade you are migrating your DSpace backend to a new server/machine, see Migrating DSpace to a new server guide for hints/tips. instead. The migration process documented on that page can be used as an alternative to this upgrade procedure.

Note
titleAdditional steps when upgrading from DSpace 6.x or lower
If upgrading from 6.x or below, you will need to follow some additional steps.  These steps have been moved to our guide for Upgrading from DSpace 6.x or lower.
  1. Download the latest DSpace release from the DSpace GitHub Repository. You can choose to either download the zip or tar.gz file provided by GitHub, or you can use "git" to checkout the appropriate tag (e.g. dspace-79.20) or branch.
    1. Unpack it using "unzip" or "gunzip".  If you have an older version of DSpace installed on this same server, you may wish to unpack it to a different location than that release.  This will ensure no files are accidentally overwritten during the unpacking process, and allow you to compare configs side by side.
    2. For ease of reference, we will refer to the location of this unzipped version of the DSpace release as [dspace-source] in the remainder of these instructions.
    If upgrading from 6.x or below, a few extra steps are required before you install DSpace 8.x.  If you are upgrading from 7.x or a prior version of 8.x, skip this and move along.Ensure that your database is compatible: Starting with DSpace 6.x, there are new database requirements for DSpace (refer to the Backend Requirements section of "Installing DSpace"  for full details).
    PostgreSQL databases: The "pgcrypto" extension MUST be installed.
  2. 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")

    3. 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;
  3. Oracle databases: Oracle support no longer exists in DSpace. See https://github.com/DSpace/DSpace/issues/8214 for more details.
    4. Anchordump_solrdump_solr From your old version of DSpace, dump your authority and statistics Solr cores.  (Only necessary if 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-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 were 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.
  4. Move your old Solr cores to a safe location in case of trouble with the upgrade procedure.  If you leave them in place, you will get a mixture of old and new files that the new Solr will refuse to load.

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

    Code Block
    cd [dspace-source]
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

  6. 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.)
    7. Update your DSpace Configurations. Depending on the version of DSpace you are upgrading from, not all steps are required.  If you are upgrading from DSpace 7.x, you will need to perform the following steps.

    As of DSpace 8, the "db.dialect" configuration has changed from "org.hibernate.dialect.PostgreSQL94Dialect" to "org.dspace.util.DSpacePostgreSQLDialect".  Therefore, MAKE SURE that your dspace.cfg or local.cfg has this setting:

    Code Block
    db.dialect = org.dspace.util.DSpacePostgreSQLDialect
  7. You may wish to review the Release Notes for details about new features. There may be new configurations you may wish to tweak to enable/disable those features.
  8. Make sure your existing local.cfg is in the source directory (e.g. [dspace-source]/dspace/config/local.cfg).  That way your existing configuration gets reinstalled alongside the new version of DSpace.
    9. If you are upgrading from DSpace 6.x or below, you will need to perform these steps.
  9. 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.
  10. Remove obsolete configurations.  With the removal of the JSPUI and XMLUI, a large number of server-side (backend) configurations were made obsolete and were therefore removed between the 6.x and 7.0 release. A full list can be found in the Release Notes.
  11. Remove BTE Spring configuration: If it exists, remove the [dspace]/config/spring/api/bte.xml Spring Configuration.  This file is no longer needed as the BTE framework was removed in favor of Live Import from external sources.
    12. M igrate 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

     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
  12. Copy your old (v5 or v6) "item-submission.xml" and "input-forms.xml" into that temporary folder

    13. 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
  13. 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 
  14. 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.
  15. 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. 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).
  16. 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.
  17. Re-configure Solr URLs:  change the value of solr.server to point at your new Solr external service.  It will probably become something like solr.server = https://localhost:8983/solr.  Solr only needs to be accessible to the DSpace backend, and should not be publicly available on the web.  It can either be run on localhost or via a hostname (if run on a separate server from the backend). Also review the values of
    1. discovery.search.server
    2. oai.solr.url
    3. solr.authority.server
    4. solr-statistics.server
  18. Sitemaps are now automatically generated/updated: A new sitemap.cron setting exists in the dspace.cfg which controls when Sitemaps are generated. By default they are enabled to update once per day, for optimal SEO.  See Search Engine Optimization docs for more detail
    1. Because of this change, if you had a system cron job which ran "./dspace generate-sitemaps", this system cron job can be removed in favor of the new sitemap.cron setting.
  19. If you are upgrading from DSpace 5.x or below, there are a few additional configuration changes to be aware of.
    1. Replace your old build.properties file with a local.cfg: 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.  See the Configuration Reference documentation and the local.cfg Configuration File section on that page.
    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).

    20. 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
    Upgrade your database (required for all upgrades). 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).

    (Optional) If desired, you can optionally verify which migrations have not yet been run on your database.  You can use this to double check that DSpace is recognizing your database version appropriately

    Code Block
    [dspace]/bin/dspace database info

# If you are upgrading from 5.x or later, then this will list all migrations 
#    which were previously run, along with any which are "PENDING" or "IGNORED" 
#    that need to be run to upgrade your database.
# If you are upgrading from 4.x or earlier, this will attempt to detect which
#    version of DSpace you are upgrading from. Look for a line at the bottom 
#    that says something like: 
#    "Your database looks to be compatible with DSpace version ___"

    (Optional) 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
    # This command only works if upgrading from DSpace 7.0 or later
[dspace]/bin/dspace database update-sequences

# If upgrading from DSpace 6 or below, this script had to be run via psql from [dspace]/etc/postgres/update-sequences.sql
# For example: 
# psql -U [database-user] -f [dspace]/etc/postgres/update-sequences.sql [database-name]

# NOTE: It is important to run the "update-sequences" script which came with the OLDER version of DSpace (the version you are upgrading from)!  If you've misplaced # this older version of the script, you can download it from our codebase & run it via the "psql" command above.
# DSpace 6.x version of "update-sequences.sql": https://github.com/DSpace/DSpace/blob/dspace-6_x/dspace/etc/postgres/update-sequences.sql
# DSpace 5.x version of "update-sequences.sql": https://github.com/DSpace/DSpace/blob/dspace-5_x/dspace/etc/postgres/update-sequences.sql

  20. (REQUIRED) 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
    # If upgrading from DSpace 6.x or below
[dspace]/bin/dspace database migrate ignored

# If upgrading from DSpace 7.x or an earlier version of 8.x
[dspace]/bin/dspace database migrate

    If you are upgrading from DSpace 6.x or below be sure you include the "ignored" parameter! There are database changes which were previously optional but now are mandatory (specifically Configurable Workflow database changes).

  21. If the database upgrade process fails or throws errors, then look at the "Troubleshooting Upgrade Issues" section below for possible tips/hints.
  22. More information on the "database" command can be found in Database Utilities documentation.
    23. 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 index-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.

  23. Deploy Server web application: Two deployment options are now available for the DSpace backend.

    1. WAR Deployment via Tomcat (traditional approach):  In this approach, you must  have Tomcat (or a different servlet container) installed locally.  You will need to deploy the "server" webapp (in  [dspace]/webapps/server ) into your Servlet Container (e.g. Tomcat).  Generally, there are two options (or techniques) which you could use...either configure Tomcat to find the DSpace "server" webapp, or copy the "server" webapp into Tomcat's own webapps folder.  For more information & example commands, see the Installation Guide

    2. Runnable JAR deployment (NEW in v8):  In this approach, you can remove any existing Tomcat installation. Instead you would run the DSpace backend from the "server-boot" JAR as described in the Installation Guide.
      Code Block
      languagebash
      titleServer-boot execution
      java -jar [dspace]/webapps/server-boot.jar
    24. Anchornew_solr_coresnew_solr_cores Update/Install the Solr cores and rebuild your indexes. This may be done after starting the backend (e.g. via Tomcat), but is required for some features to function properly.

    Copy the new, empty Solr cores to your new Solr instance.

    Code Block
    cp -R [dspace]/solr/* [solr]/server/solr/configsets
chown -R solr:solr [solr]/server/solr/configsets

    Start Solr, or restart it if it is running, so that these new cores are loaded.

    Code Block
    [solr]/bin/solr restart

  24. You can check the status of Solr and your new DSpace cores by using its administrative web interface.  Browse to ${solr.server} (e.g. http://localhost:8983/solr/) to see if Solr is running well, then look at the cores by selecting (on the left) Core Admin or using the Core Selector drop list.

    1. For example, to test that your "search" core is setup properly, try accessing the URL  ${solr.server}/search/select. It should run an empty query against the "search" core, returning an empty JSON result. If it returns an error, then that means your "search" core is missing or not installed properly.
    25. If upgrading from 6.x or below, a few extra steps are required to before starting Tomcat.Reload Solr Statistics Anchorreload_solrreload_solr Load authority and statistics from the CSV dumps that you made earlier in Step 2 above.
    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 into the "statistics" core. DSpace 7 does not support Solr shards at this time.  Unfortunately, this will involve renaming all CSV export files to remove the year (e.g. rename "statistics-2012_export_2013-12_5.csv" to "statistics_export_2013-12_5.csv") and rerunning "[dspace]/bin/dspace solr-import-statistics -i statistics".  More advice on this process can be found in this dspace-tech mailing list thread.

  25. For the Statistics core(s) 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

    26. Update Handle Server Configuration. (Required when upgrading from 6.x or below) Because we've updated to Handle Server v9, if you are using the built-in Handle server (most installations do), you'll need to add the follow to the end of the server_config section of your [dspace]/handle-server/config.dct file (the only new line is the "enable_txn_queue" line)

    Code Block
    "case_sensitive" = "no"
"storage_type" = "CUSTOM"
"storage_class" = "org.dspace.handle.HandlePlugin"
"enable_txn_queue" = "no"
    1. Alternatively, you could re-run the ./dspace make-handle-config script, which is in charge of updating this config.dct file.
    Anchorip_to_city_databaseip_to_city_database(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 regularly update) one of the following:
    1. 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.
    2. 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.

  26. Restart Tomcat (servlet container) or Runnable JAR. Now restart your servlet container (Tomcat/Jetty/Resin) or Runnable JAR 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.

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

    1. To reindex manually, just run:
      Code Block
      [dspace]/bin/dspace index-discovery -b
    2. You may also wish to reindex OAI-PMH content at this time:
      Code Block
      [dspace]/bin/dspace oai import
  28. Review / Update your scheduled tasks (e.g. cron jobs). For all features of DSpace to work properly, there are some scheduled tasks you MUST setup to run on a regular basis. Some examples are tasks that help create thumbnails (for images), do full-text indexing (of textual content) and send out subscription emails.  See the  Scheduled Tasks via Cron  for more details.
    1. If upgrading from 7.4 (or earlier) , you will want to make sure the new "subscription-send" task is added to your existing scheduled tasks (in cron or similar).  This new task is in charge of sending Email Subscriptions for any users who have subscribed to updates. (NOTE: "subscription-send" replaces the older "sub-daily" task from 6.x or below).  See the  Scheduled Tasks via Cron  for more details.
  29. Install or Upgrade the new User Interface (see below)

Upgrading the Frontend (User Interface)

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

    Code Block
    cd [dspace-source]
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

  2. 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.)
  3. Update your DSpace Configurations. Depending on the version of DSpace you are upgrading from, not all steps are required.  
    1. If you haven't already, please review the Release Notes for details about new features or configuration changes. There may be new configuration you wish to configure, or similar.
    2. Make sure your existing local.cfg is in the source directory (e.g. [dspace-source]/dspace/config/local.cfg).  That way your existing configuration gets reinstalled alongside the new version of DSpace.
    3. If you are upgrading from DSpace 7.x, you will need to perform the following steps. If you are upgrading from 8.x or a prior version of 9.x, skip this and move along.

      1. As of DSpace 8, the "db.dialect" configuration has changed from "org.hibernate.dialect.PostgreSQL94Dialect" to "org.dspace.util.DSpacePostgreSQLDialect".  Therefore, MAKE SURE that your dspace.cfg or local.cfg has this setting:

        Code Block
        db.dialect = org.dspace.util.DSpacePostgreSQLDialect

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


  5. Upgrade your database. 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. (Optional) If desired, you can optionally verify which migrations have not yet been run on your database.  You can use this to double check that DSpace is recognizing your database version appropriately

      Code Block
      [dspace]/bin/dspace database info

# The response will be a list all migrations which were previously run,
# along with any which are "PENDING" or "IGNORED" 
# that need to be run to upgrade your database.


    2. (Optional) 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
      # This command only works if upgrading from DSpace 7.x or later
[dspace]/bin/dspace database update-sequences

# If upgrading from DSpace 6 or below, this script had to be run via psql from [dspace]/etc/postgres/update-sequences.sql
# For example: 
# psql -U [database-user] -f [dspace]/etc/postgres/update-sequences.sql [database-name]

# NOTE: It is important to run the "update-sequences" script which came with the OLDER version of DSpace (the version you are upgrading from)!  If you've misplaced 
# this older version of the script, you can download it from our codebase & run it via the "psql" command above.
# DSpace 6.x version of "update-sequences.sql": https://github.com/DSpace/DSpace/blob/dspace-6_x/dspace/etc/postgres/update-sequences.sql
# DSpace 5.x version of "update-sequences.sql": https://github.com/DSpace/DSpace/blob/dspace-5_x/dspace/etc/postgres/update-sequences.sql


    3. (REQUIRED) 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
      # If upgrading from DSpace 6.x or below
[dspace]/bin/dspace database migrate ignored

# If upgrading from DSpace 7.x, 8.x or an earlier version of 9.x
[dspace]/bin/dspace database migrate


    4. If the database upgrade process fails or throws errors, then look at the "Troubleshooting Upgrade Issues" section below for possible tips/hints.
    5. 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 index-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.


  6. Deploy Server web application: Two deployment options are now available for the DSpace backend.

    1. WAR Deployment via Tomcat (traditional approach):  In this approach, you must  have Tomcat (or a different servlet container) installed locally.  You will need to deploy the "server" webapp (in  [dspace]/webapps/server ) into your Servlet Container (e.g. Tomcat).  Generally, there are two options (or techniques) which you could use...either configure Tomcat to find the DSpace "server" webapp, or copy the "server" webapp into Tomcat's own webapps folder.  For more information & example commands, see the Installation Guide

    2. Runnable JAR deployment (NEW in v8):  In this approach, you can remove any existing Tomcat installation. Instead you would run the DSpace backend from the "server-boot" JAR as described in the Installation Guide.
      Code Block
      languagebash
      titleServer-boot execution
      java -jar [dspace]/webapps/server-boot.jar
  7. Anchor
    new_solr_cores
    new_solr_cores
    Update/Install the Solr cores and rebuild your indexes. This may be done after starting the backend (e.g. via Tomcat), but is required for some features to function properly.

    1. Copy the new, empty Solr cores to your new Solr instance.

      Code Block
      cp -R [dspace]/solr/* [solr]/server/solr/configsets
chown -R solr:solr [solr]/server/solr/configsets


    2. Start Solr, or restart it if it is running, so that these new cores are loaded.

      Code Block
      [solr]/bin/solr restart


    3. You can check the status of Solr and your new DSpace cores by using its administrative web interface.  Browse to ${solr.server} (e.g. http://localhost:8983/solr/) to see if Solr is running well, then look at the cores by selecting (on the left) Core Admin or using the Core Selector drop list.

      1. For example, to test that your "search" core is setup properly, try accessing the URL  ${solr.server}/search/select. It should run an empty query against the "search" core, returning an empty JSON result. If it returns an error, then that means your "search" core is missing or not installed properly.

  8. Restart Tomcat (servlet container) or Runnable JAR. Now restart your servlet container (Tomcat/Jetty/Resin) or Runnable JAR 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.

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

    1. To reindex manually, just run:
      Code Block
      [dspace]/bin/dspace index-discovery -b
    2. You may also wish to reindex OAI-PMH content at this time:
      Code Block
      [dspace]/bin/dspace oai import
  10. Review / Update your scheduled tasks (e.g. cron jobs). For all features of DSpace to work properly, there are some scheduled tasks you MUST setup to run on a regular basis. Some examples are tasks that help create thumbnails (for images), do full-text indexing (of textual content) and send out subscription emails.  See the  Scheduled Tasks via Cron  for more details.
    1. If upgrading from 7.4 (or earlier) , you will want to make sure the new "subscription-send" task is added to your existing scheduled tasks (in cron or similar).  This new task is in charge of sending Email Subscriptions for any users who have subscribed to updates. (NOTE: "subscription-send" replaces the older "sub-daily" task from 6.x or below).  See the  Scheduled Tasks via Cron  for more details.
  11. Install or Upgrade the new User Interface (see below)

Upgrading the Frontend (User Interface)

  1. Upgrade Node.js if necessary based on the version of Node.js listed in the Installing the Frontend (User Interface) documentation
  2. Download the latest dspace-angular release from the DSpace GitHub repository. You can choose to either download the zip or tar.gz file provided by GitHub, or you can use "git" to checkout the appropriate tag (e.g.  dspace-9.0) or branch.
    1. If you've cloned or copied this code into your own GitHub or GitLab repository, you may wish to simply pull the latest tagged code into your codebase using Git. That will allow you to more easily address any "code conflicts" between your local changes and the new version of DSpace (if any are found).
    2. NOTE: For the rest of these instructions, we'll refer to the source code location as  [dspace-angular].

  3. Install any updated local dependencies using NPM in the [dspace-angular] source code directory:

    Code Block
    # change directory to our repo
cd [dspace-angular]
 
# install/update the local dependencies
npm install


  4. Build the latest User Interface code for Production:  This rebuilds the latest code into the [dspace-angular]/dist directory

    Code Block
    npm run build:prod


  5. (Optional) Review Configuration changes to see if you wish to update any new configurations
    1. See the Release Notes
  6. Update your theme (if necessary), if you've created a custom theme in "src/themes" (or modified the existing "custom" or "dspace" themes in that location).  Pay close attention to the following...

    1. If you are upgrading from 7.0, 7.1 or 7.2, a new "eager-theme.module.ts" and "lazy-theme.module.ts" has been added to both the "custom" and "dspace" themes to improve performance. Make sure to copy those to your custom theme.  Additionally, this new "eager-theme.module.ts" for your theme MUST be imported/enabled in "src/themes/eager-themes.module.ts". For example, for a local theme under "src/theme/my-theme":

      Code Block
      titlesrc/themes/eager-themes.module.ts
      import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module';
...
@NgModule({
  imports: [
    MyThemeEagerThemeModule,
  ],
})


    2. If you are upgrading from 7.x, you must migrate to standalone components.  To migrate your theme, you need to convert its components to the standalone architecture. To do so, simply follow the following steps:
      1. Fix any errors in all "<...>.module.ts" files in your theme folder. These errors may be mostly caused by importing old modules that are now deleted: simply delete any lines that refer to such modules;
      2. Run the command "ng generate @angular/core:standalone --path src/themes/<theme-folder>" to migrate the theme components to the standalone architecture, replacing <theme-folder> as necessary. WARNING: running the command while there are still errors on any <...>.module.ts will not produce the correct result, so make sure you have remedied those errors as mentioned in the previous step.
    3. If you are upgrading from 8.x, you must migrate to using Angular Control Flow syntax in all HTML templates (*.component.html file). This means that all usages of "ngIf" and "ngFor" are now replaced with their equivalent "control flow" syntax (e.g. "@if" and "@for"). If your theme has any custom HTML templates, they may require updates. Angular provides an automated migration tool which can be used to perform this migration (this is the same tool that was used to migrate all DSpace code in #3997).
    4. As of 9.0, all SASS/CSS styles use Bootstrap 5. This means that some CSS and SASS styles have changed slightly.  This may also impact your themes, as they may need to migrate Bootstrap 4 styles into Bootstrap 5 styles.  See the Bootstrap 5 migration guide for details.  For additional examples, see #3506 which updated DSpace to use Bootstrap 5
  7. If upgrading from 6.x or below, install the new User Interface per the Installing DSpace guide. The JSPUI and XMLUI are no longer supported and cannot work with the DSpace 7 backend. You will need to install the new (Angular.io) User Interface.
    1. JSPUI or XMLUI based themes cannot be migrated.  That said, since the new Angular UI also uses Bootstrap, you may be able to borrow some basic CSS from your old themes.  But any HTML-level changes will need to be reimplemented in the new UI.
  8. If upgrading from 7.x or a prior version of 8.x, upgrading requires installing the latest version of the User Interface code
    1. Upgrade Node.js if necessary
    2. Download the latest dspace-angular release from the DSpace GitHub repository. You can choose to either download the zip or tar.gz file provided by GitHub, or you can use "git" to checkout the appropriate tag (e.g.  dspace-8.0) or branch.
      1. If you've cloned or copied this code into your own GitHub or GitLab repository, you may wish to simply pull the latest tagged code into your codebase using Git. That will allow you to more easily address any "code conflicts" between your local changes and the new version of DSpace (if any are found).
      2. NOTE: For the rest of these instructions, we'll refer to the source code location as  [dspace-angular].

      3. Install any updated local dependencies using Yarn in the [dspace-angular] source code directory:

      Code Block
      # change directory to our repo
cd [dspace-angular]
 
# install/update the local dependencies
yarn install

      Build the latest User Interface code for Production:  This rebuilds the latest code into the [dspace-angular]/dist directory

      Code Block
      yarn build:prod
      If upgrading from 7.0 or 7.1, read the updated version 7 Installation documentation. We now recommend deploying the compiled User Interface (in [dspace-angular]/dist) to a different directory (which we refer to as [dspace-ui-deploy]) in order to keep your running UI separate from the source code.  While it's still possible to run the UI using "yarn start" or "yarn run serve:ssr" (both of which use [dspace-angular]/dist),that older approach will mean that your site goes down / becomes unavailable anytime you rebuild (yarn build:prod).  To solve this issue:
      1. Create a separate [dspace-ui-deploy] location as described in the Installation documentation.
      2. Copy the [dspace-angular]/dist folder to that location, as described in the Installation documentation.
      3. Update your PM2 configuration or local startup scripts to use Node.js instead of Yarn.  Again, see the Installation documentation.

    3. If upgrading from 7.0 or 7.1, migrate your UI Configurations to YAML. In 7.2, the format of the UI configuration file changed from Typescript to YAML to support runtime configuration.  This means that customization of the older ./src/environment/environment.*.ts build-time configuration files has been superseded by corresponding ./config/config.*.yml configuration files (e.g. environment.prod.ts → config.prod.yml). 

      1. Either, manually convert your "environment.prod.ts" configurations to a new "./config/config.prod.yml" file, using the "./config/config.example.yml" as a guide, along with the User Interface Configuration documentation.
      2. OR, you can migrate your configurations using the provided "yarn env:yaml" migration script.  For detailed instructions, see the Migrate environment file to YAML second of the User Interface Configuration documentation.
    4. (Optional) Review Configuration changes to see if you wish to update any new configurations
      1. See the Release Notes
    5. Update your theme (if necessary), if you've created a custom theme in "src/themes" (or modified the existing "custom" or "dspace" themes in that location).  Pay close attention to the following...

      As of 7.3, a new "eager-theme.module.ts" and "lazy-theme.module.ts" has been added to both the "custom" and "dspace" themes to improve performance. Make sure to copy those to your custom theme.  Additionally, this new "eager-theme.module.ts" for your theme MUST be imported/enabled in "src/themes/eager-themes.module.ts". For example, for a local theme under "src/theme/my-theme":

      Code Block
      titlesrc/themes/eager-themes.module.ts
      import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module';
...
@NgModule({
  imports: [
    MyThemeEagerThemeModule,
  ],
})
      As of 8.0, you must migrate to standalone components.  To migrate your theme to DSpace 8, you need to convert its components to the standalone architecture. To do so, simply follow the following steps:
    6. Fix any errors in all "<...>.module.ts" files in your theme folder. These errors may be mostly caused by importing old modules that are now deleted: simply delete any lines that refer to such modules;
      7. Run the command "ng generate @angular/core:standalone --path src/themes/<theme-folder>" to migrate the theme components to the standalone architecture, replacing <theme-folder> as necessary. WARNING: running the command while there are still errors on any <...>.module.ts will not produce the correct result, so make sure you have remedied those errors as mentioned in the previous step.
    7. Additional minor changes may have been made. It's usually best to look for changes to whichever theme you started from.  If you started your theme from the "custom" theme, look for any new changes made under "/src/themes/custom".  If you started your theme from the "dspace" theme, look for any new changes made under "/src/themes/dspace". 

      1. Using a tool like "git diff" from the commandline is often an easy way to see changes that occurred only in that directory.

        Code Block
        # Example which will show all the changes to "src/themes/dspace" (and all subfolders)
# between dspace-
        7
        8.
        4
        1 (tag) and dspace-
        8
        9.0 (tag)
git diff dspace-
        7
        8.
        4
        1 dspace-
        8
        9.0 -- src/themes/dspace/


    8. For the "custom" theme, the largest changes are often:
      1. New themeable components (subdirectories) may be added under "src/themes/custom/app", allowing you the ability to now change the look & feel of those components.
      2. The "src/themes/custom/theme.module.ts" file will likely have minor updates. This file registers any new themeable components (in the "const DECLARATIONS" section), and also registers new Modules, i.e. new UI features, (in the "@NgModule" → "imports" section).  Make sure those sections are updated in your copy of this file!
      3. Sometimes, new styles may be added in the "styles" folder, or new imports to "styles/theme.scss"
      4. If you have locally customized the styles or look & feel of any component, you should also verify that the component itself (in src/app) hasn't had updates.
    9. For the "dspace" theme, the largest changes are often:
      1. Existing customized components (subdirectories) under "src/themes/dspace/app/" may have minor updates, if improvements were made to that component.
      2. The "src/themes/custom/theme.module.ts" file will likely have minor updates. This file registers any new themeable components (in the "const DECLARATIONS" section), and also registers new Modules, i.e. new UI features, (in the "@NgModule" → "imports" section).  Make sure those sections are updated in your copy of this file!
      3. Sometimes, new styles may be added in the "styles" folder, or new imports to "styles/theme.scss"
      4. If you have locally customized the styles or look & feel of any additional component, you should also verify that the component itself (in src/app) hasn't had updates.
  9. Restart the User Interface.   

    1. If you are using PM2 as described in the Installing DSpace instructions, you'd stop it and then start it back up as follows

      Code Block
      # Stop the running UI
pm2 stop dspace-ui.json

# If you had to update your PM2 configs, you may need to delete your old configuration from PM2
# pm2 delete dspace-ui.json

# Start it back up
pm2 start dspace-ui.json


    2. If you are using a different approach, you simply need to stop the running UI, and re-run:

      Code Block
      # First stop the running UI process by killing it (or similar)

# You MUST restart the UI from within the deployment directory
# See Installation Instructions for more info on this directory
cd [dspace-ui-deploy]
 
# Then restart the UI via Node.js
node ./dist/server/main.js


  10. Verify the UI and REST API are both working properly. 
    1. If you hit errors, see the "Troubleshooting Upgrade Issues" section below.  Additionally, check the "Common Installation Issues" section of the Installing DSpace documentation for other common misconfiguration or setup issues.

Troubleshooting Upgrade Issues

...