DSpace Administrator Guide

DSpace 8.x → 10.x Migration Guide

Fresh installation + database, assetstore, Solr, metadata, DOI, and frontend migration

DSpace 8.x → 10.xPostgreSQL 16SolrAngular UIUbuntu

⚠ Migration warning: This guide uses a fresh DSpace 10.x installation + data migration, not an in-place upgrade. Before executing commands on a production server, confirm your paths, database names, service users, backup integrity, and custom configuration.

What this guide covers

Back up the DSpace 8.x database, assetstore, configuration, and Solr data.
Create and prepare the DSpace 10.x PostgreSQL database.
Restore the database and migrate the schema.
Restore the assetstore with correct ownership and permissions.
Handle Solr cores safely without copying old cores into configsets/.
Reindex Discovery and import OAI data.
Review DOI metadata and metadata registries.
Merge configuration changes and address Angular UI breaking changes.
Restart services and perform final verification against the old repository.

📚 Table of Contents

Backup the 8.x source
Create the target database
Grant PostgreSQL schema permissions
Restore the database
Point local.cfg to the restored DB
Migrate the schema
Restore the assetstore
Configure and verify Solr
Reindex
Migrate DOI metadata
Load metadata registries
Merge configuration changes
Update the Angular frontend
Verify scheduled tasks
Restart and verify everything
Known migration gotchas

🔄 Migration flow

1. SOURCEBack up DSpace 8.x data and configuration.

2. TARGETPrepare the fresh DSpace 10.x environment.

3. DATABASERestore the 8.x database into PostgreSQL.

4. APPLICATIONRun DSpace database migrations and restore assets.

5. SEARCHKeep fresh Solr cores and rebuild indexes.

6. VERIFYCheck API, UI, search, browse, and sample records.

Environment Reference

Fill in and confirm these values before running commands on a new server.

Component	Reference
Old server	DSpace 8.x — hostname `dspace-8x`
New installation	Fresh DSpace 10.x at `/dspace`
Solr	`/opt/solr` Solr home: `/opt/solr/server/solr`
Target database	`dspace10` — PostgreSQL 16 — role `dspace`
8.x backup	`/home/dspace/Downloads/Dspace_8.X_BKP/Dspace_8X._BKP_July_2026/`

This is the migration approach (fresh 10.x install + move data over), not an in-place upgrade — recommended since you're skipping a major version (9.x) and already had 10.x installed fresh.

Step 1

Backup the 8.x source (if not already done)

# DB dump
pg_dump -U [dspace8-db-user] -f dspace8_backup.sql [dspace8-db-name]

# Assetstore, config, solr
tar czf assetstore_backup.tar.gz -C [dspace8]/assetstore .
tar czf dspace8_config.tar.gz -C [dspace8]/config .
tar czf solr_backup.tar.gz -C [dspace8]/solr .

Purpose: Create a recoverable backup of the source database and the key DSpace data/configuration directories.

↑ Back to top Step 2

Create the target database

sudo -u postgres createuser --username=postgres --no-superuser --pwprompt dspace   # skip if exists
sudo -u postgres createdb --username=postgres --owner=dspace --encoding=UTF8 --locale=en_US.UTF-8 dspace10

Purpose: Create the PostgreSQL role and target database used by DSpace 10.x.

↑ Back to top Step 3

Grant schema permissions (required on Postgres 15+)

sudo -u postgres psql -d dspace10

Purpose: Open the target database as the PostgreSQL administrator.

GRANT ALL PRIVILEGES ON DATABASE dspace10 TO dspace;
GRANT ALL ON SCHEMA public TO dspace;
ALTER SCHEMA public OWNER TO dspace;
\q

Purpose: Grant the DSpace role database/schema access and make it the owner of the public schema.

sudo -u postgres psql -d dspace10 -c "CREATE EXTENSION IF NOT EXISTS pgcrypto;"

Purpose: Ensure the pgcrypto extension is available in the target database.

↑ Back to top Step 4

Restore the DB dump

PostgreSQL authentication: Peer authentication can fail if you are not logged in as the matching OS user. The guide therefore forces TCP with -h 127.0.0.1.

psql -U dspace -h 127.0.0.1 -d dspace10 -f /path/to/dspace8_backup.sql

Purpose: Restore the DSpace 8.x database dump into the DSpace 10.x target database.

Verify the restored database:

psql -U dspace -h 127.0.0.1 -d dspace10 -c "\dt" | head -20
psql -U dspace -h 127.0.0.1 -d dspace10 -c "SELECT count(*) FROM item;"
psql -U dspace -h 127.0.0.1 -d dspace10 -c "SELECT count(*) FROM eperson;"

Purpose: Check that tables exist and compare basic item/eperson counts.

↑ Back to top Step 5

Point local.cfg at the restored DB

nano /dspace/config/local.cfg

Purpose: Open the DSpace 10.x local configuration file.

db.url = jdbc:postgresql://127.0.0.1:5432/dspace10
db.username = dspace
db.password = [password]
db.dialect = org.dspace.util.DSpacePostgreSQLDialect

Purpose: Configure DSpace to connect to the restored PostgreSQL database.

↑ Back to top Step 6

Migrate the schema

/dspace/bin/dspace database info      # check pending/ignored migrations first
/dspace/bin/dspace database migrate ignored
/dspace/bin/dspace database info      # confirm all Success, no Pending/Ignored

Purpose: Review migration status, apply the required ignored migrations, and verify the final migration state.

Why migrate ignored? The guide requires it specifically when coming from 8.x because it also picks up legacy migrations flagged “Ignored” in the older database history. An “Out of Order” status on old entries after this is described as expected/harmless.

↑ Back to top Step 7

Restore the assetstore

Check the source versus the backup archive for freshness first, then restore the assetstore:

rsync -av [8x-backup]/dspace/assetstore/ /dspace/assetstore/
chown -R tomcat:tomcat /dspace/assetstore     # match your actual service user
chmod -R 750 /dspace/assetstore

Purpose: Copy the source assetstore into DSpace 10.x and apply ownership/permissions appropriate to the actual service account.

Verify:

du -sh /dspace/assetstore
find /dspace/assetstore -type f | wc -l
psql -U dspace -h 127.0.0.1 -d dspace10 -c "SELECT count(*) FROM bitstream WHERE deleted=false;"
grep -r "assetstore" /dspace/config/local.cfg /dspace/config/spring/api/bitstore.xml 2>/dev/null

Purpose: Compare assetstore size/file count with the database bitstream count and confirm the configured assetstore location.

↑ Back to top Step 8

Solr — do NOT copy old core folders into configsets/

🚨 Critical Solr warning: /dspace/solr/* contains full core directories, including core.properties and data/. They are not bare configsets. Do not copy them into /opt/solr/server/solr/configsets/. Doing so can create duplicate core-name conflicts and crash the CoreContainer.

Your fresh DSpace 10.x installation already creates the correct live cores under /opt/solr/server/solr/<corename>/. Leave those cores alone and confirm Solr starts cleanly:

systemctl restart solr
systemctl status solr
tail -30 /opt/solr/server/logs/solr.log

Purpose: Restart Solr and inspect the service status and recent log output.

Look for:

Cores are: [statistics, qaevent, authority, audit, oai, suggestion, search]

There should be no duplicate cores and no CoreContainerProvider error.

If the configsets mistake was previously made:

cd /opt/solr/server/solr/configsets
rm -rf statistics qaevent authority audit oai suggestion search
systemctl restart solr

Purpose: Remove the duplicated core directories from configsets and restart Solr.

Verify the search and statistics cores:

curl http://localhost:8983/solr/search/select?q=*:*
curl http://localhost:8983/solr/statistics/select?q=*:*

Purpose: Confirm the Solr cores respond to requests.

Optional: To carry over old statistics/authority history, stop Solr and copy only the data/index contents from the corresponding 8.x cores into the already-created DSpace 10.x core data directories. Never route these through configsets/.

↑ Back to top Step 9

Reindex

/dspace/bin/dspace index-discovery -b
/dspace/bin/dspace oai import

Purpose: Rebuild the Discovery index and import OAI data after the migration.

↑ Back to top Step 10

DOI metadata migration (DSpace 10 changed the DOI field/format)

Before production use: Check the DSpace 10.x wiki section titled “Standardizing the format and location of DOI metadata” and run the DOI migrator script referenced there before relying on DOIs.

↑ Back to top Step 11

Metadata registries (usually auto-triggered by step 6, run manually if not)

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

Purpose: Load the metadata registry definitions manually if they were not loaded automatically by the database migration.

↑ Back to top Step 12

Config diff — don’t overwrite, merge selectively

diff -rq [8x-backup]/dspace/config /dspace/config

Purpose: Compare the old and new configuration trees before making changes.

Do not blindly overwrite the DSpace 10.x configuration. Pull over only the old local.cfg values that remain valid, custom modules/*.cfg overrides, and any customized config/spring/api/bitstore.xml. Check DSpace 10.x release notes for renamed or removed keys.

↑ Back to top Step 13

Frontend (Angular UI) — breaking changes inherited from 9.x AND 10.x

Bootstrap 5 (introduced 9.0): migrate custom theme CSS/SASS using the Bootstrap 5 migration guide.
Angular control-flow syntax (required as of 10.0): convert ngIf/ngFor to @if/@for in *.component.html:

cd [dspace-angular]
npx @angular/cli generate @angular/core:control-flow --path src/themes/[your-theme]

Purpose: Run Angular’s control-flow migration against the custom theme.

Theme configuration was also simplified in 10.0. Check the “Upgrading from 9.x to 10.x” guidance on the User Interface Customization wiki before editing theme.config.ts.

Build the frontend:

cd [dspace-angular]
npm run clean
npm install
npm run build:prod

Purpose: Clean, install dependencies, and build the production Angular UI.

↑ Back to top Step 14

Cron / scheduled tasks

Scheduled task check: Confirm subscription-send is present in crontab. It replaces the old sub-daily task and is required since 7.5.

↑ Back to top Step 15

Restart everything and verify

# Backend (PM2/runnable JAR)
pm2 stop dspace-ui.json
pm2 start dspace-ui.json

# or Tomcat
$CATALINA_HOME/bin/shutdown.sh && $CATALINA_HOME/bin/startup.sh

Purpose: Restart the backend using the deployment method used by your installation.

tail -100 /dspace/log/dspace.log.$(date +%Y-%m-%d)

Purpose: Review the current DSpace log for errors after restart.

Final verification: Open the REST API at /server/api and the UI. Confirm that items, search, and browse are populated, then spot-check several records against the old DSpace 8.x site.

↑ Back to top

Known Migration Gotchas

1. PostgreSQL peer authentication
Connecting as root or the wrong OS user through the local socket can fail even with -U dspace. Use -h 127.0.0.1 to force password authentication, or use sudo -u dspace psql.

2. Public schema ownership
PostgreSQL 15+ does not grant CREATE on public to all roles by default. The target schema therefore needs to be explicitly owned by dspace.

3. Solr configsets vs. cores
/dspace/solr/* contains full cores, not configsets. Copying them into configsets/ can create duplicate-core-name failures during Solr startup.

✅ Post-migration checklist

Database restored and item/eperson counts checked.
All required database migrations show the expected status.
Assetstore restored with correct ownership and permissions.
Solr starts without duplicate-core or CoreContainer errors.
Discovery reindex completed.
OAI import completed.
DOI metadata migration reviewed before production DOI use.
Metadata registries verified.
Custom configuration merged selectively.
Angular UI built successfully.
Scheduled tasks verified.
REST API, UI, search, browse, and sample records checked against DSpace 8.x.

Documentation note: This article follows the supplied DSpace 8.x → 10.x migration procedure. Replace bracketed placeholders such as [8x-backup], [password], [dspace-angular], and database names with values from your own environment before executing commands.

Search This Blog

Library Trends Insights

How to Install Java 21 and Set Java Environment Variables System-Wide on Ubuntu