All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
Info |
---|
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:
|
...
Note | ||
---|---|---|
| ||
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. |
Note | ||
---|---|---|
| ||
DSpace now requires that Solr be installed separately. The indexes have been reconfigured and must be rebuilt. See below. |
Warning | ||
---|---|---|
| ||
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 subversion or 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. |
...
[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 instance. Backups are easy to recover from; a botched install/upgrade is very difficult if not impossible to recover from. The DSpace specific things to backup are: configs, source code modifications, database, and assetstore. On your server that runs DSpace, you might additionally consider checking on your cron/scheduled tasks, servlet container, and database.
...
DSpace 67.x requires the following versions of prerequisite software:
...
Refer to the Prerequisite Software section of "Installing DSpace" for more details around configuring and installing these prerequisites. If you are building with mirage2.deps.included=false
(more information at https://github.com/DSpace/DSpace/tree/dspace-6_x/dspace-xmlui-mirage2) then the following dependencies may need to be updated as well:
...
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; |
[dspace-source]/dspace/modules/jspui/src/main/webapp/
[dspace-source]/dspace/modules/xmlui/src/main/webapp/
[dspace]/config
For highly customized DSpace instances, note that the format of the following configuration files has changed. If you have customized these configuration files, carefully re-integrate your custom settings.
dspace/config/dspace.cfg
dspace/config/spring/api/discovery.xml
dspace/modules/xmlui/src/main/webapp/sitemap.xmap
Note the presence of new class names in this file. In particular,note the removal of StandardOpenSearchGenerator
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 Block |
---|
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. 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 | ||
---|---|---|
| ||
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: |
Info | ||
---|---|---|
| ||
Mirage 2 is a responsive theme for the XML User Interface, added as a new feature in DSpace 5. It has not yet replaced the Mirage 1 theme as the XMLUI default theme. To enable Mirage 2, add the following to the <theme name="Mirage 2" regex=".*" path="Mirage2/" /> It is important to do this before executing the maven build. Mirage 2 is not yet activated in the default "mvn package" build. To include it as part of the build, run: mvn -U clean package -Dmirage2.on=true The speed of this specific step of the build can be increased by installing local copies of the specific dependencies required for building Mirage 2. The Mirage 2 developer documentation provides detailed instructions for these installations. After the installation of these dependencies, you can choose to run: mvn -U clean package -Dmirage2.on=true -Dmirage2.deps.included=false Warning: The Mirage 2 build process should NOT be run as "root". It must be run as a non-root user. For more information see: Mirage 2 Common Build Issues |
$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.)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 |
The above command will also automatically upgrade all your existing Solr indexes (e.g. for Discovery, Statistics, OAI-PMH) to the latest version. For large instances, this may take some time. But, it is important to ensure that your indexes are usable by the latest version of DSpace.
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.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 DSpace 6. For more information on configurations in DSpace 6 see our updated Configuration Reference.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.local.cfg
file, as described above. Examples of how this might be accomplished are provided in the Configuration Reference.[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
).dspace.cfg
and/or local.cfg
all lines referencing org.dspace.app.mediafilter.WordFilter
and uncomment all lines referencing org.dspace.app.mediafilter.PoiWordFilter
.Back up your authority
and statistics
Solr cores.
Code Block | ||||
---|---|---|---|---|
| ||||
[dspace]/bin/dspace authority -d > authority-dump.xml
[dspace]/bin/dspace solr-export-statistics -i statistics |
The authority backup is in the file authority-dump.xml
and the statistics backup is in the directory [dspace]/solr-export
. If you are sharding your statistics data, TBS.
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.)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 |
The above command will also automatically upgrade all your existing Solr indexes (e.g. for Discovery, Statistics, OAI-PMH) to the latest version. For large instances, this may take some time. But, it is important to ensure that your indexes are usable by the latest version of DSpace.
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.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 DSpace 6. For more information on configurations in DSpace 6 see our updated Configuration Reference.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.local.cfg
file, as described above. Examples of how this might be accomplished are provided in the Configuration Reference.[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
).dspace.cfg
and/or local.cfg
all lines referencing org.dspace.app.mediafilter.WordFilter
and uncomment all lines referencing org.dspace.app.mediafilter.PoiWordFilter
.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):
"xmlui" = This is the XML-based User Interface, based on Apache Cocoon. It comes with a variety of out-of-the-box themes, including Mirage 1 (the default) and Mirage 2 (
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):
"xmlui" = This is the XML-based User Interface, based on Apache Cocoon. It comes with a variety of out-of-the-box themes, including Mirage 1 (the default) and Mirage 2 (based on Bootstrap).Between the "xmlui" and "jspui", you likely only need to choose one.
"jspui" = This is the JSPUI-based User Interface, which is based on Bootstrap. Between the "xmlui" and "jspui", you likely only need to choose one.
"solr" (required) = This is Apache Solr web application, which is used by the "xmlui" and "jspui" (for search & browse functionality), as well as the OAI-PMH interface. It must be installed in support of either UI.
Deploy 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.
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 ___" |
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 occurance, you may choose to run the "update-sequences.sql" script PRIOR to upgrading your database. If your database sequences are inconsistent or incorrect, this "update-sequences.sql" script will auto-correct them (otherwise, it will do nothing). Be aware, if you choose to run this script, please run the "update-sequences.sql" file that corresponds to your current version of DSpace (i.e. the version you are upgrading from), as this script occasionally changes between releases. In the future, we hope to automate this step to avoid any sequence problems:
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 |
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 |
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 |
[dspace-src]/dspace-api/src/main/resources/org/dspace/storage/rdbms/sqlmigration/
)./dspace database migrate
)Note | ||
---|---|---|
| ||
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. Skipping automatic reindexing involves two main steps, both of which must be executed prior to restarting Tomcat (or your servlet container): 1) First, you must manually update your database by running 2) If any database migrations are run, a empty "reindex.flag" file will be created at As you have disabled automatic reindexing, make sure to manually reindex your site by running 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. |
Sites with Oracle database backends (and Configurable Workflow enabled) may need to run a "repair" on your database.
In version 6.3, we fixed an Oracle migration issue related to Configurable (XML) Workflow. See DS-3788.
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.
Simply run the following to repair your Oracle database: [dspace]/bin/dspace database repair
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.
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. Especially pay attention to the Solr Index optimization commands, which ideally should be run regularly (as noted in the previous step).
[dspace]/bin/start-handle-server.bat
script is available to more easily startup your Handle Server.In very rare instances, a Flyway database migration will be "ignored." One known instance of this is documented in DS-3407. If you are upgrading from DSpace 5.x to a later version of DSpace, the migration put in place to address DS-2818 will be "ignored" because it is not necessary. There is a special command you can run which will un-flag this migration as "ignored."
Code Block |
---|
dspace database migrate ignored |
...
title | warning: dangerous command: BACK UP YOUR DATABASE! |
---|
The dspace database migrate ignored
command can be dangerous: it will attempt to re-run all ignored migrations. In the case outlined above, this is safe. However, under other circumstances, re-running ignored migrations can lead to unpredictable results. To be absolutely safe, be sure you have a current backup of your database.
...
If you run into issues with the auto-upgrade of your Solr search/browse indexes (during the final part of the ant update step
), then you may need to manually upgrade your Solr indexes. Depending on the type of failure, there are a few possible fixes.
...
lucene-core-3.5.0.jar
from http://search.maven.org/remotecontent?filepath=org/apache/lucene/lucene-core/3.5.0/lucene-core-3.5.0.jar [dspace-source]/dspace/target/dspace-installer/
directory (i.e. the directory where you ran "ant update" from)ant update
". This time, it should find the lucene-core-3.5.0.jar
locally and re-attempt the upgrade of your Solr indexes....
If you are using an older version of DSpace, you will see errors similar to this one until you manually upgrade your index:
Code Block |
---|
Caused by: org.apache.lucene.index.IndexFormatTooOldException: Format version is not supported (resource: segment _386q in resource ChecksumIndexInput(MMapIndexInput(path="/space/dspace/solr/statistics/data/index/segments_37m6"))): 2.x. This version of Lucene only supports indexes created with release 3.0 and later. |
Manually upgrading your Solr index involves temporarily downloading an older version of Lucene (on which Solr is based), and calling its IndexUpgrader script, e.g.
Code Block |
---|
# Download Lucene 3.5.0, which can upgrade older Solr/Lucene indexes
wget "http://search.maven.org/remotecontent?filepath=org/apache/lucene/lucene-core/3.5.0/lucene-core-3.5.0.jar" -O lucene-core-3.5.0.jar
# Then, actually upgrade the indexes by loading the lucene-core-3.5.0.jar and calling IndexUpgrader
# Upgrade the Usage Statistics index. Run this if you have Solr Usage Statistics enabled in your UI.
java -cp lucene-core-3.5.0.jar org.apache.lucene.index.IndexUpgrader [dspace]/solr/statistics/data/index/
# Upgrade the OAI-PMH indexes. Run this if you use the "oai" webapp.
java -cp lucene-core-3.5.0.jar org.apache.lucene.index.IndexUpgrader [dspace]/solr/oai/data/index/
# NOTE: You do not need to upgrade the Discovery Search and Browse indexes as they will be automatically rebuilt on upgrade (See previous upgrade step) |
...
Upgrading from DSpace 3.x or above: DSpace provides optimization commands for all Solr indexes. Which ones you need to run depend on which features you are using in DSpace.
...
Copy the new, empty Solr cores to your new Solr instance.
Code Block | ||
---|---|---|
| ||
cp -r [dspace]/solr/* [solr]/server/solr/configsets
chown solr:solr [solr]/server/solr/configsets/authority [solr]/server/solr/configsets/oai [solr]/server/solr/configsets/search [solr]/server/solr/configsets/statistics |
Restore authority
and statistics
from backup.
Code Block | ||
---|---|---|
| ||
[dspace]/bin/dspace authority -r < authority-dump.xml
[dspace]/bin/dspace solr-import-statistics -i statistics |
Rebuild the oai
and search
cores.
Code Block | ||
---|---|---|
| ||
[dspace]/bin/dspace oai import
[dspace]/bin/dspace index-discovery |
If you have a great deal of content, this could take a long time.
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.
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. Especially pay attention to the Solr Index optimization commands, which ideally should be run regularly (as noted in the previous step).
[dspace]/bin/start-handle-server.bat
script is available to more easily startup your Handle Server.In very rare instances, a Flyway database migration will be "ignored." One known instance of this is documented in DS-3407. If you are upgrading from DSpace 5.x to a later version of DSpace, the migration put in place to address DS-2818 will be "ignored" because it is not necessary. There is a special command you can run which will un-flag this migration as "ignored."
Code Block |
---|
dspace database migrate ignored |
Info | ||
---|---|---|
| ||
The The presence of |