Dspace migration steps

 Restore and migrate Dspace 6.3 to 8

Because DSpace 7+ introduced a completely re-engineered architecture—splitting into an Angular UI frontend and a REST API backend—you cannot simply "overwrite" an old installation. Instead, the standard process is to perform a fresh installation of DSpace 8 or 9 backend, restore your DSpace 6.3 data onto it, and let DSpace’s built-in migration tools auto-upgrade your database schema.

Here is the step-by-step guide to accomplishing this migration.

Phase 1: Prepare the New Server Environment

DSpace 8/9 has stricter environment prerequisites than version 6.3. Set up your new server with the following:

  • Java: OpenJDK 17 (for DSpace 8) or OpenJDK 21 (recommended for DSpace 9).

  • Database: PostgreSQL (Versions 12 to 15 are ideal).

  • Build Tools: Apache Maven 3.8+ and Apache Ant 1.10+.

  • Servlet Container: Apache Tomcat 9.

  • Solr: Apache Solr 9.x (DSpace 7+ no longer runs Solr embedded inside Tomcat; it must run as a standalone service).

Phase 2: Install a Clean DSpace 8/9 Backend

Before touching your backup files, you need to compile and install a fresh DSpace instance to generate the directory structure.

  1. Download the DSpace 8 or 9 source code and extract it.

  2. Setup your local.cfg file in the source directory ([dspace-source]/dspace/config/local.cfg) with your new database credentials, URL settings, and file paths.

  3. Build the package using Maven:

    Bash
    mvn package

  4. Navigate to the build directory and install it via Ant:

    Bash
    cd dspace/target/dspace-installer
ant fresh_install

    Note: This creates a clean /dspace directory (or your custom installation path), but the database is still empty.

Phase 3: Restore Your 6.3 Backup Files

Now, you will inject your DSpace 6.3 data into the freshly installed DSpace 8/9 backend framework.

1. Restore the Assetstore

Delete the empty assetstore folder created by the fresh install, and replace it with your backed-up files.

Bash
rm -rf /dspace/assetstore
cp -r /path/to/your/backup/assetstore /dspace/

Ensure that the tomcat user (or whichever user runs your application) has full ownership permissions over the restored assetstore:

Bash
chown -R tomcat:tomcat /dspace/assetstore

2. Restore the Database

Log into PostgreSQL as a superuser, drop the blank database created during the fresh installation, recreate it, and apply the pgcrypto extension required by modern DSpace versions.

Bash
sudo -u postgres psql

# Run these SQL commands:
DROP DATABASE dspace;
CREATE DATABASE dspace;
\c dspace;
CREATE EXTENSION pgcrypto;
\q

Now, import your DSpace 6.3 SQL backup into the empty database:

Bash
# If your backup is a plain text .sql file:
psql -U dspace -d dspace -f /path/to/your/dspacebackup.sql

# If it was a custom binary backup (.bak / .sql formatted via pg_dump -Fc):
pg_restore -U dspace -d dspace /path/to/your/dspacebackup.sql

Phase 4: Upgrade the Database Schema

At this point, your assetstore is in place, but your database schema is still formatted for v6.3. DSpace has built-in database migration tools using Flyway that will detect this and automatically upgrade the database sequentially up to v8/v9.

Run the following command from your new DSpace directory:

Bash
/dspace/bin/dspace database migrate ignored

What about the log file? You generally do not need to restore old logs to the production folder for the system to work. You can safely keep them archived externally for auditing purposes.

Phase 5: Create Administrator & Initialize Indexes

Because DSpace 7+ handles authentication and discovery differently, you need to clean up and re-index your metadata.

  1. Verify Database Status:

    Bash
    /dspace/bin/dspace database info

    (Ensure all migration steps read "Success")

  2. Re-index Solr (Crucial step): Your old Lucene/Solr indexes from 6.3 are incompatible. You must force DSpace to read your newly migrated database and rebuild the search indexes entirely:

    Bash
    /dspace/bin/dspace index-discovery -b

  3. Create a New Admin account (If login fails): Sometimes old password hashes from v6 legacy systems conflict during initial boot. Create a fresh CLI administrator account to guarantee backend entry:

    Bash
    /dspace/bin/dspace create-administrator

Phase 6: Install the User Interface (UI)

Remember, your backend is now working, but you cannot log into it via a browser yet. You must now install the DSpace User Interface (Node.js/Angular-based frontend application) on the same server or a companion server.

Follow the offical DSpace documentation to install Node.js (v18 or v20), download the DSpace UI source code, configure it to point to your backend API, and run it via a process manager like pm2.

Once the frontend UI connects to your newly updated backend, all of your items, collections, handles, and metadata from version 6.3 will be live!

Comments

Post a Comment