DSpace 7.5 Installation Manual

DSpace is an open-source software platform for managing digital assets such as research papers, images, videos, and other types of digital content. It is now maintained by DuraSpace, a not-for-profit organization that supports open-source software projects.

One of the main benefits of DSpace is that it is freely available for download and use, which makes it a cost-effective solution for organizations that want to manage and preserve digital content. Additionally, the software can be modified and adapted to meet an organization’s specific needs because it is open source.

DSpace 7.5 (7x) Installation

The following is a general guide for installing DSpace 7.5. It assumes you have a basic understanding of Linux, Apache, and PostgreSQL.

Step 1: Setup Desktop Environment 

• To complete the DSpace 7.5 installation by following this manual, use Linux Mint. This installation was tested on Linux Mint 21.1 version.
• Complete your Linux installation with the “dspace” username. If another user name is used, you must change the user name on the Installation manual.

Step 2: Create a root user password to complete this installation process on your local Linux server. If not created before, open your terminal, and enter. [Using a single password in the entire setup is recommended for a new user]

sudo -i passwd

Now update the local server.

sudo apt update
sudo apt upgrade -y

Login as a root user

su

Enter your root password.

DSpace 7.5 Backend Installation

Step 3: Install Java JDK:

 sudo apt install default-jdk

To check the Java version we already installed

java -version

Now you need to set Java variables in your local computer:

cd /etc
sudo nano environment

Now add

JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"

Now you need to source this file with the Java Home directory: For this run:

source /etc/environment

Now check if the Java home is properly working or not:

echo $JAVA_HOME

Step 4: Install Apache Maven

DSpace uses Maven to simplify the complex Java-based application’s installation process by managing dependencies, ensuring compatibility, and streamlining the configuration process.

sudo apt install maven

Check Maven version

mvn -v

Step 5: Install Apache ANT

ANT provides a scripting language for defining targets and tasks that can be used to compile the code, create JAR files, run tests, and generate documentation. DSpace uses ANT to build and package the software and perform various other tasks during installation, such as creating and deploying WAR files, generating documentation, and more. ANT simplifies the installation process of DSpace by automating many of the necessary tasks, reducing the potential for errors and inconsistencies.

apt install ant

Step 6. Install PostgreSQL

DSpace uses PostgreSQL as its backend database to store metadata, content, and configuration information. PostgreSQL provides advanced features such as transaction management, high availability, and advanced indexing, making it an ideal choice for managing large, complex data sets common in digital repositories like DSpace. With PostgreSQL, DSpace can store and retrieve data efficiently and reliably, providing a stable and scalable platform for managing digital content.

sudo apt install postgresql postgresql-client postgresql-contrib

Check the installed PostgreSQL version here. I have version 12 installed here. If you have another version installed, change the version in the following command.

After successful installation, you need to start the database server using the following:

sudo pg_ctlcluster 12 main start

Now you can check the status of your PostgreSQL Server

sudo systemctl status postgresql

To exit, type (from the keyboard)

q

Create a new Postgres user:

sudo groups postgres

Add a new password in Postgres

sudo passwd postgres

Enter password

Enter your password here

Login as postgres user:

su postgres

Now check if your server is UTF8 enabled or not:

psql -c "SHOW SERVER_ENCODING"

If yes, then you do not need to configure it. By default, it is automatically enabled. Now exit from the

exit

Now you must allow the  TCP/IP connections to access the database server.

cd /etc/postgresql/12/main
sudo nano postgresql.conf

In this file, find

# - Connection Settings -
#listen_addresses = 'localhost'         # what IP address(es) to listen on;

Delete # Change it to:

listen_addresses = 'localhost'         # what IP address(es) to listen on;

Then tighten up security a bit by editing pg_hba.conf

sudo nano pg_hba.conf

Now add host access IP configuration here

host dspace dspace 127.0.0.1 255.255.255.255 md5

Now save the edited file and restart PostgreSQL

sudo systemctl restart postgresql

Check postgress systemstatus:

systemctl status postgresql

To exit, type q from your keyboard

q

Step 7: Apache Solr Installation

DSpace uses Solr to index and search metadata and full-text content, making it easier for users to find and access digital content in the repository. Solr provides advanced features such as faceted search, autocomplete, and relevancy ranking, which make it an ideal choice for managing large and complex digital repositories like DSpace. With Solr, DSpace can provide fast and accurate search results, improving the user experience and making it easier to discover and access digital content.

You can download Apache Solr from: https://solr.apache.org/downloads.html. We recommend using Solr 8.11.2 for DSpace 7.5

Copy link from Binary releases: [PGP]

Now open opt directory, and download Solr

cd /opt
sudo wget https://downloads.apache.org/lucene/solr/8.11.2/solr-8.11.2.tgz

Extract solr

sudo tar xvf solr-8.11.2.tgz

Give the ownership to the dspace user:

sudo chown -R dspace:dspace solr-8.11.2

Now go through the Solr directory

cd  solr-8.11.2
cd bin
cd
pwd
exit

Return to the home directory as a normal user (not a root user) and find the #.profile directory. You need to configure the solr to start automatically every time after starting the server.

To find the #.profile directory

ls -la

Now edit #.profile directory

sudo nano .profile

Past this line & save to start Solr automatically after restarting or starting your server every time.

/opt/solr-8.11.2/bin/solr start

To run Solr (Don’t start Solr as a root user.)

/opt/solr-8.11.2/bin/solr start

Check Solr status on your browser: http://localhost:8983/ , http://local-ip:8983

Step 8. Install Apache Tomcat (tomcat9)

Tomcat 9 is an open-source web server and servlet container that supports the latest Java Servlet and JSP specifications, making it an ideal platform for hosting DSpace. Tomcat 9 provides a lightweight and efficient environment for running web applications, and it is widely used for hosting Java-based web applications and dynamic websites. With Tomcat 9, DSpace can provide a reliable and scalable platform for managing and delivering digital content to users.

We have some configuration here.

Login as a root user

su

Install tomcat9

apt install tomcat9

Check the tomcat9 status on your browser: http://localhost/8080, http://local-ip/8080

On Debian systems, you also need to modify or override the “tomcat.service” file to specify the DSpace installation directory in the list of ReadWritePaths.

cd /lib/systemd/system
sudo nano tomcat9.service

Under the # Security option, add this line and save.

ReadWritePaths=/dspace/

Now create a dspace installation directory

cd
sudo mkdir /dspace

Give the dspace user full read and write permission to /dspace directory

sudo chown -R dspace:dspace /dspace/

You need to ensure that Tomcat9

a) has enough memory to run DSpace, and
b) uses UTF-8 as its default file encoding for international character support.

So ensure in your startup scripts (etc) that the following environment variable is set: JAVA_OPTS=”-Xmx512M -Xms64M -Dfile.encoding=UTF-8″

sudo nano /etc/environment

add

JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

Source it

source /etc/environment
echo $JAVA_OPTS

Next: You also need to alter Tomcat’s default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the <Connector> element in [tomcat]/config/server.xml: URIEncoding=”UTF-8″ e.g. if you’re using the default Tomcat config, it should read.

cd /etc/tomcat9/
sudo nano server.xml

Now add this line between <Connector port=”8080″ protocol=”HTTP/1.1″  /> [Make sure there is no space between the line. Instead of using space, use a tab. Otherwise, the system will fail to restart again.]

<Connector port="8080" protocol="HTTP/1.1"
minSpareThreads="25"
enableLookups="false"
redirectPort="8443"
connectionTimeout="20000"
disableUploadTimeout="true"
URIEncoding="UTF-8"/>

Restart Tomcat9

sudo systemctl daemon-reload
sudo systemctl restart tomcat9.service

Step 9. Install Git

Currently, there is a known bug in DSpace where a third-party Maven Module expects git to be available (in order to support the ./dspace version command-line tool).

sudo apt install git

Step 10: DSpace Backend Installation

DSpace Backend installation involves setting up the core components of the DSpace repository, including the backend database (PostgreSQL), the search platform (Apache Solr), and the Java web application (DSpace). The backend installation process typically involves configuring and installing these components on a dedicated server or virtual machine and ensuring they are appropriately integrated and configured to work together. The backend installation is a crucial step in setting up a DSpace repository, as it provides the foundation for storing, indexing, and searching digital content and the web interface for managing and accessing that content.

Create a new directory called build.

cd
sudo mkdir /build

Give the directory full control to dspace user.

sudo chown -R dspace:dspace /build 
cd /build

Download Dspace7.5

sudo wget https://github.com/DSpace/DSpace/archive/refs/tags/dspace-7.5.zip

Unzip downloaded files

sudo unzip dspace-7.5.zip

Go to unzipped folder

cd DSpace-dspace-7.5/

It’s time for Postgres database setup

Give the Postgres user a new password

su postgres
Enter password.****** (Password should be same as the root user.....)

Create a dspace database user (this user can have any name, but we’ll assume you name it “dspace”). This is entirely separate from the dspace operating-system user created above.

createuser --username=postgres --no-superuser --pwprompt dspace
Enter Password......

Create a dspace database owned by the dspace PostgreSQL user. Similar to the previous step, this can only be done by a “superuser” account in PostgreSQL (e.g. postgres)

createdb --username=postgres --owner=dspace --encoding=UNICODE dspace

Finally, you MUST enable the pgcrypto extension on your new dspace database. Again, this can only be enabled by a “superuser” account (e.g. postgres)

psql dspace -c "CREATE EXTENSION pgcrypto;"

Exit from the PostgreSQL user

exit

Initial Configuration (local.cfg): Create your own [dspace-source]/dspace/config/local.cfg configuration file.  You may wish to copy the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE. This local.cfg file can be used to store any configuration changes you wish to make that are local to your installation.

Go to the dspace build directory

cd /build/DSpace-dspace-7.5/dspace/config

Copy the local.cfg.Example file to local.cfg

cp local.cfg.EXAMPLE local.cfg

Edit the local.cfg file

sudo nano local.cfg

Change this following settings

dspace.dir=/dspace

# Name of the site
dspace.name = <Enter the name of your Repository here>

>>> Remove # from
default.language = en_US

>>> Remove # from
solr.server = http://localhost:8983/solr

>>> Change your database password here.
db.username = dspace
db.password = [Your Password/smae as PostgreSQL db]

Build the Installation Package

Open DSpace source directory and build the installation packages

cd /build/DSpace-dspace-7.5
mvn package

This will take 10-30 min to complete the build process of the DSpace installation.

Install DSpace Backend

Go to the dspace installer directory &  install DSpace to /dspace directory.

cd /build/DSpace-dspace-7.5/dspace/target/dspace-installer/
ant fresh_install

If it failed, please check your database password and re-run ant fresh installation.

Dspace Installation files will be saved at

cd /dspace/
ls

Initialize your Database: While this step is optional (as the DSpace database should auto-initialize itself on the first startup), it’s always good to verify one last time that your database connection is working correctly. To initialize the database run the following:

cd /dspace/bin/
./dspace database migrate

This process will take a few moments.

Step 11: Deploy Server web application

Copy all the web applications to Tomcat9

sudo cp -R /dspace/webapps/* /var/lib/tomcat9/webapps*

Check if the files are copied or not

ls -la /var/lib/tomcat9/webapps

Now give the tomcat-users full permission to dspace backend directory

sudo chown -R tomcat:tomcat /dspace/

Restart tomcat9 again

sudo systemctl restart tomcat9.service

Now visit tomcat URL localhost:8080/server/; It will show

Copy Solr cores: DSpace installation creates a set of four empty Solr cores already configured. We need to copy those on the Solr configsets directory.

cp -R /dspace/solr/* /opt/solr-8.11.2/server/solr/configsets

Give the dspace users ownership to the Solr directory

sudo chown -R dspace:dspace /opt/solr-8.11.2

Restart Solr as a normal dspace user (not as a root user)

cd
exit
/opt/solr-8.11.2/bin/solr restart

The new 4 core modules will be available at the Solr directory: (Authority, oai, search, and statistics)

Solr URL: http://localhost:8983/

12. Create an Administrator Account: Create an initial administrator account from the command line.

Login as a root user and run this command to create a new dspace administration account

su
/dspace/bin/dspace create-administrator 
Enter email:
First name:
Last Name:
Password: [Any Password]

Restart Tomcat9

sudo systemctl restart tomcat9.service

Now run http://localhost:8080/server/, localhost:8080/server/oai/request?verb=Identify to see if the backend server works perfectly.

---

Installing the Frontend (User Interface)

DSpace Frontend installation involves setting up the user-facing components of the DSpace repository, including the web interface and customization of the theme and user interface. The frontend installation process typically involves configuring and installing the Java web application (DSpace) on a web server (Apache Tomcat), and customizing the interface using various tools such as Angular. The frontend installation is a crucial step in setting up a DSpace repository, as it provides the interface for users to access and interact with the digital content stored in the backend.

Step 1: Installing Node

Open the home directory

su
cd
pwd
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash

Now close and restart your terminal and run this command as a root user

exit
>>> exit from the root user
exit
>>> exit from the terminal
>>> Open new terminal and login as a root user
su
>>> See the list of NVM versions available
nvm ls-remote
>>> Install NVM 16 (Dspace Anguler not support node v.17-v.19)
nvm install 16
>>> use node v-16.20.0
nvm use 16.20.0
>>> Check the version installed
node -v

Step 2: Install yarn

npm install --global yarn
npm install --global pm2

Step 3: Frontend Installation

Go: https://github.com/DSpace/dspace-angular/releases

Copy the source link as a zip file.

>>> Open build directory
cd /build

>>> Download DSpace Angular Frontend
wget https://github.com/DSpace/dspace-angular/archive/refs/tags/dspace-7.5.zip

>>> Unzip DSpace Angular
unzip dspace-7.5.zip

>>> Remove dspace-7.5.zip from build directory
rm dspace-7.5.zip

>>> Open DSpace Angular directory:
cd dspace-angular-dspace-7.5/

>>> Install the local dependencies
yarn install

>>> It will take a few minuts (5-10 Min. Based on your internet speed)

Step 4: Build/Compile: Build the User Interface for Production. This builds source code (under [dspace-angular]/src/) to create a compiled version of the User Interface in the [dspace-angular]/dist folder. This /dist folder is what we will deploy & run to start the UI.

cd config/

>>> Copy config.example.yml as config.prod.yml
cp config.example.yml config.prod.yml

>>> Edit the config.prod.yml
nano config.prod.yml

>>> Change the # "rest:" settings as followings, and save
   ssl : false 
   host : localhost 
   port: 8080

>>> Now run this command to buld your DSpace Frontend for production
yarn run build:prod

Step 5: Start up the User Interface

You must create a PM2 JSON configuration file to run the User Interface. This file can be named anything & placed where ever you like, but we recommend you save it to your deployment directory (e.g. [dspace-ui-deploy]/dspace-ui.json).

cd /build/dspace-angular-dspace-7.5/

>>> Create dspace-ui.json file
nano dspace-ui.json

>>> Copy and past this configration settings, and save it.

{     "apps": [         {            "name": "dspace-ui",            "cwd": "/build/dspace-angular-dspace-7.5",            "script": "dist/server/main.js",            "instances": "max",            "exec_mode": "cluster",            "env": {               "NODE_ENV": "production"            }         }     ] }

Now, start the application (dspace-ui.json) using PM2 using the configuration file you created in the previous step.

pm2 restart /build/dspace-angular-dspace-7.5/dspace-ui.json

Now you can access the DSpace Angular user interface at http://localhost:4000

Happy Browsing!

---

This Installation Manual was created by

Md. Ashikuzzaman
Officer, North South University Library, Dhaka, Bangladesh