Installing DSpace from Scratch

This tutorial provides a step-by-step guide to installing DSpace from scratch in a simplified way.

1. Set Up the Environment

Make sure the following software is installed on the server where DSpace will run:

JDK 17

Maven 3.8+

Ant 1.10+

PostgreSQL 12+

Solr 9.x

Node.js 22+

PM2 (for managing the Angular frontend in production)

2. Set Up the Database

After installing PostgreSQL, create the database and user for DSpace.

2.1 Access PostgreSQL as the administrator:

sudo -u postgres psql

2.2 Create a user (replace 'dspace#pass' with a strong password):

CREATE USER dspace WITH PASSWORD 'dspace#pass';

2.3 Create the DSpace database and assign ownership:

CREATE DATABASE dspace OWNER dspace;

2.4 Grant all privileges to the user:

GRANT ALL PRIVILEGES ON DATABASE dspace TO dspace;

2.5 Enable the pgcrypto extension:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

2.6 Exit the PostgreSQL prompt:

\q

3. Install the DSpace Backend (REST API)

Download the latest DSpace Backend from the official site and unzip it. We will refer to the extracted folder as [DSpace Source].

3.1 Create the installation directory (we’ll use /dspace):

cd /
mkdir dspace
chown [execution-user] dspace

In this post, we will use the following conventions:

[dspace] → Installation directory for DSpace (/dspace)

[DSpace Source] → Folder containing the DSpace source code

3.2 Copy and edit the configuration file:

cp [DSpace Source]/dspace/config/local.cfg.EXAMPLE [DSpace Source]/dspace/config/local.cfg

Minimum configuration:

dspace.dir=/dspace
dspace.server.url=http://[host]/server
dspace.ui.url=https://[host]
solr.server=http://localhost:8983/solr
db.url=jdbc:postgresql://localhost:5432/dspace
db.username=dspace
db.password=<DB Password>

Explanation:

dspace.dir: Installation directory for DSpace

dspace.server.url: Public URL of the backend (REST API)

dspace.ui.url: Public URL of the Angular frontend

solr.server: Solr server URL

db.url: Database connection URL

db.username / db.password: Database credentials

3.3 Build the backend:

mvn package

3.4 Install it using Ant:

cd [DSpace Source]/dspace/target/dspace-installer
ant fresh_install

3.5 Update the database schema:

[dspace]/bin/dspace database migrate

3.6 Configure Solr:

cp -R [dspace]/solr/* [solr]/server/solr/configsets

3.7 Restart Solr:

[solr]/bin/solr stop
[solr]/bin/solr start -Dsolr.config.lib.enabled=true

3.8 Start the DSpace backend:

java -jar /dspace/webapps/server-boot.jar

Access the API at: http://[host]:8080/server

Recommendation (production): Configure server-boot.jar as a Linux service (via systemd or another service manager) so it runs automatically and restarts if it fails.

4. Install the Angular Frontend

Download the latest DSpace UI from the official site and unzip it.

4.1 Install dependencies:

npm install

4.2 Copy and configure the production config file:

cp config/config.example.yml config/config.prod.yml

Example configuration:

ui:
ssl: false
host: [host-front]
port: 4000
nameSpace: /

rest:
ssl: false
host: [host-server]
port: 8080
nameSpace: /server
ssrBaseUrl: http://localhost:8080/server

This connects the Angular frontend to the DSpace REST API.

4.3 Start the UI manually:

npm start

4.4 To run Angular with PM2 (recommended for production), create a dspace-ui.json file:

{
"apps": [
{
"name": "dspace-ui",
"cwd": "/full/path/[dspace-angular]",
"script": "dist/server/main.js",
"env": {
"NODE_ENV": "production"
}
}
]
}

Start with:

pm2 start dspace-ui.json

5. Create the Administrator User

Run the following command to create an administrator account:

[dspace]/bin/dspace create-administrator