These instructions are meant as a general guideline to how you can migrate your DSpace site/data to a new server while also Upgrading DSpace to the latest release. Keep in mind that you MUST also review the Installing DSpace and Upgrading DSpace guides when performing a migration (e.g. you must ensure you have correct dependencies installed and you must ensure you perform all upgrade steps). |
There are two main approaches to migrating your DSpace to a new server.
On your new server, follow the Installing DSpace instructions and install a fresh (empty) copy of the latest version of DSpace. BEFORE PROCEEDING, ensure that this fresh copy of DSpace is correctly installed and shows no errors when you startup the site. (The site will obviously appear empty though, and that's OK)
You can also use this time to get your basic configurations setup properly for both the backend (local.cfg) and the frontend (config.prod.yml).
There are three main areas of data you need to migrate in order to ensure no data loss.
Perform these steps on the old server
Update sequences (optional) - When migrating content, sometimes sites will find that database sequences will be outdated or incorrect. This can result in "duplicate key" errors during the database migration to the latest version. To avoid this, before you export your data, run this older copy of the "update-sequences" command on your database. This should ensure your database sequences are updated before you dump your data.
# If upgrading from DSpace 6 or below, run this on your old database psql -U [database-user] -f [dspace]/etc/postgres/update-sequences.sql [database-name] # e.g. psql -U dspace -f [dspace]/etc/postgres/update-sequences.sql dspace |
The database data - Make sure to export the database data from your old DSpace site using a tool like "pg_dump" (for PostgresSQL). If you use "pg_dump", you'll end up with a large SQL file which contains all the data from your old database.
# Example of using pg_dump to export a database to an output file pg_dump -U [db_username] [db_name] > [output_file.sql] |
Copy the data you've prepared in Step 2 over to the new server.
Now, you'll import this data into your new installation of DSpace (created in Step 1).
Perform these steps on the new server.
Delete/Clean the new, empty database (created in step 1) as you will have empty tables created during the installation. The easiest way to achieve this is to run the "./dspace database clean" command. Keep in mind it requires temporarily enabling it via "db.cleanDisabled=false" in your local.cfg. (After the "clean" command succeeds, make sure to remove this configuration.)
# Delete everything in your database # Requires temporarily setting "db.cleanDisabled=false" in your local.cfg ./dspace database clean |
Import the database dump you created in Step 2 (above), which will recreate this database with all your old data in it. For Postgres, you can use the "psql" command.
# Example of using psql to import data from a SQL file into a database psql -U [db_username] [db_name] < [output_file.sql] |
(NOTICE the direction of the angle character... in this command you are telling Postgres to execute all the commands contained in your "output_file.sql", which will cause it to recreate all the database data in your new database.)
[dspace]/assetstore/
folder on the new server.Now that all the data is copied over, you need to ensure it's updated and reindexed properly (for the new version of DSpace).
Perform these steps on the new server.
Migrate/Upgrade the database to the latest version - Now that your old data is migrated, you MUST ensure it's using the latest database updates based on the new DSpace you've installed. Review the database steps in Upgrading DSpace and follow the instructions there.
# Migrate your old data to the latest DSpace version # WARNING: You must review the Upgrading DSpace docs to see if there are any additional database steps listed there! ./dspace database migrate ignored |
Reindex all content - This will ensure all search/browse functionality works in the DSpace site. Optionally, if you use OAI-PMH, you will want to reindex content into there as well.
# Reindex all your content in DSpace ./dspace index-discovery -b # (Optionally) also reindex everything into OAI-PMH endpoint ./dspace oai import |
NOTE: Until this command completes (it may take a while for large sites), you will not be able to fully browse/search the content from the User Interface. To check the progress of the reindex, check your dspace.log file.
If you've changed the version of DSpace you are running, you should review the Upgrading DSpace guide for instructions related to necessary configuration changes or other necessary updates. You should perform any upgrade steps that you have NOT yet performed above (keep in mind you already should have upgraded your database, and reindexed your content).
At this time, you also may wish to review your configurations on your old DSpace site, and see if there are any configurations that you wish to copy over into your new DSpace site. This step is optional, as you can also choose to start "fresh" with a new local.cfg file.
FINALLY, test the new site and verify that all the content, user accounts, etc. have moved over successfully. If you encounter any issues, see our Troubleshoot an error guide for hints/tips on finding the underlying error message & reporting it to Support lists/channels. Also make sure to check our list of Common Installation Issues in the Installing DSpace guide.