All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
These instructions are valid for any of the following upgrade paths:
For more information about new features or major changes in previous releases of DSpace, please refer to following:
Upgrading database structure/data is now automated!
The underlying DSpace database structure changes and data migrations are now AUTOMATED (using FlywayDB). This means that you no longer need to manually run SQL scripts. Instead, the first time you run DSpace, it will auto-update your database structure (as needed) and migrate all your data to be compatible with the installed version of DSpace. This allows you to concentrate your upgrade efforts on customizing your site without having to worry about migrating your data!
For example, if you were running DSpace 1.4, and you wish to upgrade to DSpace 5, you can follow the simplified instructions below. As soon as you point your DSpace 5 installation against the older DSpace 1.4-compatible database, your database tables (and data) will automatically be migrated to be compatible with DSpace 5.
See below for a specific note on troubleshooting "ignored" migrations (a rare circumstance, but known to happen if you upgrade from DSpace 5 to a later version of DSpace).
Please refrain from customizing the DSpace database tables. It will complicate your next upgrade!
With the addition of our automated database upgrades, we highly recommend AGAINST customizing the DSpace database tables/structure or backporting any features that change the DSpace tables/structure. Doing so will often cause the automated database upgrade process to fail (and therefore will complicate your next upgrade).
If you must add features requiring new database tables/structure, we recommend creating new tables (instead of modifying existing ones), as that is usually much less disruptive to our automated database upgrade.
Test Your Upgrade Process
In order to minimize downtime, it is always recommended to first perform a DSpace upgrade using a Development or Test server. You should note any problems you may have encountered (and also how to resolve them) before attempting to upgrade your Production server. It also gives you a chance to "practice" at the upgrade. Practice makes perfect, and minimizes problems and downtime. Additionally, if you are using a version control system, such as git, to manage your locally developed features or modifications, then you can do all of your upgrades in your local version control system on your Development server and commit the changes. That way your Production server can just checkout your well tested and upgraded code.
In the notes below [dspace]
refers to the install directory for your existing DSpace installation, and [dspace-source]
to the source directory for DSpace. Whenever you see these path references, be sure to replace them with the actual path names on your local system.
DSpace 7.5 added some new features and many improvements and bug fixes. See the Release Notes for all the details. These major features are most likely to impact your upgrade:
DSpace 7.4 added some new features and many improvements and bug fixes. See the Release Notes for all the details. These major features are most likely to impact your upgrade:
DSpace 7.3 added many new features and improvements. See the Release Notes for all the details. These major features are most likely to impact your upgrade:
DSpace 7.2 made some major changes to the User Interface build process, including a new configuration file format. See the Release Notes for all the details. These major features are most likely to impact your upgrade:
New Configuration for User Interface to support Runtime Configuration: In the User Interface, the "environment.*.ts" configuration files have been replaced with a new "config.*.yml" file. A migration script is provided which can migrate your UI configurations from the old format to the new one. More information on that migration is available in the User Interface Configuration documentation.
DSpace 7.1 primarily added new features and bug fixes on top of 7.0. See the Release Notes for all the details. A few key changes to be aware of:
DSpace 7.0 features some significant changes which you may wish to be aware of before beginning your upgrade:
GeoIP location database must be installed separately due to changes in Maxmind's terms and conditions. MaxMind has changed the terms and procedure for obtaining and using its GeoLite2 location database. Consequently, DSpace no longer automatically downloads the database during installation or update, and the DSpace-specific database update tool has been removed. If you wish to (continue to) record client location data in SOLR Statistics, you will need to make new arrangements. See below.
[dspace]/config/config-definition.xml
(DSpace's Apache Commons Configuration settings), you will need to ensure those modifications are compatible with Apache Commons Configuration version 2. See the Apache Commons Configuration's configuration definition file reference for more details. Before you start your upgrade, it is strongly recommended that you create a backup of your DSpace content. 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]
[dspace]/assetstore
by default, and any other assetstores configured in [dspace]/config/spring/api/bitstore.xml
)[dspace]/config
. [dspace]/solr/statistics
. A simple copy of the logs or the Solr core directory tree 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.[dspace]/solr/authority
. As with the statistics data, making a copy of the directory tree should enable recovery from errors.DSpace 7.x requires the following versions of prerequisite software:
Refer to the Backend Requirements section of "Installing DSpace" for more details around configuring and installing these prerequisites.
Migration 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.
dspace-7.2
) or branch.Enabling pgcrypto on your DSpace database. (Additional options/notes in the Installation Documentation)
# Login to your "dspace" database as a superuser psql --username=postgres dspace # Enable the pgcrypto extension on this database CREATE EXTENSION pgcrypto;
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)
[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.
Unfortunately, the "solr-export-statistics" script was not created until DSpace 5.x. Therefore, you will not be able to upgrade statistics from 4.x or below unless you first upgrade to either 5.x or 6.x. This upgrade could be done in a test environment, just to allow you to export your statistics (so they can be reimported into 7.x below). But, there's unfortunately no direct way to migrate 4.x (or 3.x or 1.x.x) Solr Statistics into 7.x.
(If upgrading from 5.x or below) 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. 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.
cd [dspace-source] cp dspace/config/local.cfg.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.
Build DSpace Backend. Run the following commands to compile DSpace :
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
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
Stop Tomcat (or servlet container). Take down your servlet container.
$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.)As of DSpace 7.3, the "db.dialect" configuration has changed from "org.dspace.storage.rdbms.hibernate.postgres.DSpacePostgreSQL82Dialect" to "org.hibernate.dialect.PostgreSQL94Dialect". Therefore, MAKE SURE that your dspace.cfg or local.cfg has this setting:
db.dialect = org.hibernate.dialect.PostgreSQL94Dialect
[dspace-source]/dspace/config/local.cfg
). That way your existing 7.x configuration gets reinstalled alongside the new version of DSpace.config
directory, and its subdirectories, concentrating on configurations your previously customized in your local.cfg. See also the Configuration Reference.[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.First, create a temporary folder to copy your old v6 configurations into
# 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
Run the command-line migration script to migrate them to v7 configuration files
# 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
[dspace]/config/item-submission.xml.migrated
[dspace]/config/submission-forms.xml.migrated
[dspace]/config/
folder, therefore retaining the inline comments in those default files.[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
).dspace.cfg
and/or local.cfg
all lines referencing org.dspace.app.mediafilter.WordFilter
and uncomment all lines referencing org.dspace.app.mediafilter.PoiWordFilter
.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 ofdiscovery.search.server
oai.solr.url
solr.authority.server
solr-statistics.server
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./dspace generate-sitemaps
", this system cron job can be removed in favor of the new sitemap.cron
setting.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
(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
[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).
[dspace]/bin/dspace database update-sequences # NOTE: In 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] # # If you still have this script under [dspace]/etc/, you can remove that entire [dspace]/etc/ folder, as it's no longer needed in DSpace 7 or above.
(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)
# If upgrading from DSpace 6.x or below [dspace]/bin/dspace database migrate ignored # If upgrading from an earlier version of DSpace 7.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).
By 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.
Deploy Server web application: The DSpace backend consists of a single "server" webapp (in [dspace]/webapps/server
). You need to deploy this webapp 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
[dspace]/webapps/rest
). It is NOT used by the DSpace UI/frontend. So, most users should skip this step.If you are upgrading from 7.0 to a later version of 7.x, you will need to update your 'search' Solr schema definition with the new version (in 7.1 a new "search.entitytype" field was added to this schema).
Copy the updated schema.xml to your Solr 'search' core, e.g.
# The destination directory may differ per OS. # Just replace the existing 'search' core "schema.xml" with the new one. cp [dspace]/solr/search/conf/schema.xml /var/solr/data/search/conf/
Restart Solr
[solr]/bin/solr restart
Reindex your site
[dspace]/bin/dspace index-discovery -b
Copy the new, empty Solr cores to your new Solr instance.
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.
[solr]/bin/solr restart
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.
${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. Load authority
and statistics
from the dumps that you made earlier (not the disaster-recovery backup).
[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
.
For Statistics shards only, upgrade legacy DSpace Object Identifiers (pre-6.4 statistics) to UUID Identifiers.
[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
Rebuild the oai
and search
cores.
[dspace]/bin/dspace oai import [dspace]/bin/dspace index-discovery -b
If you have a great deal of content, this could take a long time.
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)
"case_sensitive" = "no" "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin" "enable_txn_queue" = "no"
./dspace make-handle-config
script, which is in charge of updating this config.dct
file.geoipupdate
tool directly via their package manager. You will still need to configure your license key prior to usage.usage-statistics.dbfile
in your local.cfg
configuration file . config/
directory (if they exist).usage-statistics.dbfile
in your local.cfg
configuration file . Check your cron / Task Scheduler jobs. In recent versions of DSpace, some of the scripts names have changed.
Check the Scheduled Tasks via Cron documentation for details. If you have been using the dspace stats-util --optimize
tool, it is no longer recommended and you should stop.
[dspace]/bin/start-handle-server.bat
script is available to more easily startup your Handle Server.Restart Tomcat (servlet container). Now restart your servlet container (Tomcat/Jetty/Resin) and test out the upgrade.
[dspace]/log/dspace.log.[date]
) for information on its status.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.
When upgrading from 7.0/7.1/7.2 to 7.3, it is REQUIRED to reindex your content. If reindexing does not occur automatically, or you disabled it, then run "./dspace index-discovery -b" to reindex your site.
# Manually reindex all content ./dspace index-discovery -b
dspace-7.2
) or branch.[dspace-angular].
Install any updated local dependencies using Yarn in the [dspace-angular]
source code directory:
# 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
yarn build:prod
[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:[dspace-ui-deploy]
location as described in the Installation documentation.[dspace-angular]/dist
folder to that location, as described in the Installation documentation.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 the older ./src/environment/environment.*.ts
configuration files have all been replaced by corresponding ./config/config.*.yml
configuration files (e.g. environment.prod.ts → config.prod.yml).
In 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":
import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module'; ... @NgModule({ imports: [ MyThemeEagerThemeModule, ], })
Using a tool like "git diff" from the commandline is often an easy way to see changes that occurred only in that directory.
# Example which will show all the changes to "src/themes/dspace" (and all subfolders) # between dspace-7.1 (tag) and dspace-7.2 (tag) git diff dspace-7.1 dspace-7.2 -- src/themes/dspace/
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!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!If you are using PM2 as described in the Installing DSpace instructions, you'd stop it and then start it back up as follows
# 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
If you are using a different approach, you simply need to stop the running UI, and re-run:
# 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
At times the upgrade process may involve configuration changes which could result in one of our "Common Installation Issue" error messages. So, make sure to check that section of the Installing DSpace documentation, especially if you find your UI is no longer connecting to your REST API.
If you are upgrading to DSpace 7.x and receive either of the two following errors after running "./dspace database migrate ignored":
Migration V5.7_2017.04.11__DS-3563_Index_metadatavalue_resource_type_id_column.sql failed [or] Migration V5.7_2017.05.05__DS-3431.sqln failed
This just means your database never ran those older migrations during a past upgrade from 5.x→6.x (or similar).
Luckily, though, these migrations are both obsolete in DSpace 7.x (and later). This means you can skip these migration safely.
As of DSpace 7.5, a new "./dspace database skip" command is provided to easily skip one (or both) of these failing migrations as follows:
# If you need to skip "V5.7_2017.04.11__DS-3563_Index_metadatavalue_resource_type_id_column.sql", run this: ./dspace database skip "5.7.2017.04.11" # If you need to skip "V5.7_2017.05.05__DS-3431.sql", run this: ./dspace database skip "5.7.2017.05.05"
For more information on the "./dspace database skip" command see Database Utilities.
If you have modified your database structure directly (or installed custom plugins which do so), then it is possible a "./dspace database migrate" will fail if it encounters an unexpected database structure. 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:
[dspace-src]/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/
)./dspace database migrate
)During some upgrades, a Flyway database migration will be "ignored." One known instance of this is documented in https://github.com/DSpace/DSpace/issues/6762. If you are upgrading from DSpace 5.x to a later version of DSpace, the migration put in place to address https://github.com/DSpace/DSpace/pull/1128 will be "ignored" because it is not necessary. There is a special command you can run which will un-flag this migration as "ignored."
dspace database migrate ignored
The database migration (./dspace database migrate) should 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:
cd [dspace]/bin/ ./dspace registry-loader -metadata ../config/registries/dcterms-types.xml ./dspace registry-loader -metadata ../config/registries/dublin-core-types.xml ./dspace registry-loader -metadata ../config/registries/eperson-types.xml ./dspace registry-loader -metadata ../config/registries/local-types.xml ./dspace registry-loader -metadata ../config/registries/sword-metadata.xml ./dspace registry-loader -metadata ../config/registries/workflow-types.xml