All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
...
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; |
From your old version of DSpace, dump your Anchor dump_solr dump_solr authority
and statistics
Solr cores. (Only necessary when upgrading from DSpace 6 or older & you want to keep both your authority records and/or SOLR Statistics)
Code Block | ||
---|---|---|
| ||
[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.
dspace-7.0
) or branch.Replace your old build.properties file with a local.cfg (ONLY REQUIRED if upgrading from DSpace 5 or previous): As of DSpace 6.0, the build.properties
configuration file has been replaced by an enhanced local.cfg
configuration file. Therefore, any old build.properties
file (or similar [dspace-source]/*.properties
files) WILL BE IGNORED. Instead, you should create a new local.cfg
file, based on the provided [dspace-source]/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 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
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: |
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 |
config
directory, and its subdirectories, concentrating on configurations your previously customized in your local.cfg. See also the Configuration Reference.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 |
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 |
[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. 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
.solr.server
to point at your new Solr external service. It will probably become something like solr.server = https://${dspace.hostname}:8983/solr
. 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.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 occurrence, you may choose to run the "update-sequences" command PRIOR to upgrading your database. If your database sequences are inconsistent or incorrect, this "update-sequences" command will auto-correct them (otherwise, it will do nothing).
Code Block |
---|
# General PostgreSQL example psql -U [database-user] -f [dspace]/etc/postgres/update-sequences.sql [database-name] # Example for a PostgreSQL database named "dspace", and a user account named "dspace" # psql -U dspace -f [dspace]/etc/postgres/update-sequences.sql dspace |
Then, you can upgrade your DSpace database to the latest version of DSpace. (NOTE: check the DSpace log, [dspace]/log/dspace.log.[date]
, for any output from this command)
Code Block |
---|
[dspace]/bin/dspace database migrate |
If you are upgrading from DSpace 6 or earlier, there are database changes which were previously optional but now are mandatory (specifically Configurable Workflow database changes). Instead of (or after) the above command:
Code Block |
---|
[dspace]/bin/dspace database migrate ignored |
to apply these changes.
[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. To disable automatic reindexing, setdiscovery.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 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. |
Note | ||
---|---|---|
| ||
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: |
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.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 |
Anchor | ||||
---|---|---|---|---|
|
authority
and statistics
from the dumps that you made earlier (not the disaster-recovery backup).Code Block | ||
---|---|---|
| ||
[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.
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
Rebuild the oai
and search
cores.
Code Block | ||
---|---|---|
| ||
[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. (Only necessary if 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" |
./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. 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.
[dspace]/bin/start-handle-server.bat
script is available to more easily startup your Handle Server....