Install DSPACE 7.5 on Ubuntu 22.04 LTS

Since you found this link somewhere and clicked on it, I would assume that you are familiar with the Dspace Repository system, and if you are not, let me tell you in brief that Dspace is an Open Source software that provides a standardized system within a library or an Institute to provide services for the dissemination of digital contents to the users. It has been a leading repository software and is the first choice of librarians and information keepers in making digital repositories; it is built on Java and uses PostgreSQL as a database engine. It uses Apache Tomcat to serve webpages over the web, making usability and administration very easy. Till 6.X it had two wonderful interfaces, JSPUI and XMLUI, which were very flexible and highly customizable.

But now that DSpace Version 7.x has been released, the DSpace code has been completely rewritten and has gone under tremendous change. The backend and the GUI interface are now two different things and can be installed on independent machines, for security and performance concerns. The backend interface, which is purely a REST-based API interface does the preservation of content, it is basically at the storage layer and the Web UI or as we call it now, the Frontend is Angular based Web interface, Where all the appearance and cosmetics are to be seen. However, both these interfaces can be installed on the same machine, or even on different machines, and still talk to each other in order for the repository to work. To keep things simple, In This documentation, I have installed these on the same server.

As the Dspace Wiki page says, DSpace 7.5 Release of the Backend / REST API only. You can see the Release Notes for all details. The DSpace Backend consists of a Server API (“server” web app) built on Spring Boot. It is more of a headless version, which we can use if there we want our repository to be configured with a REST API-based application. It is a Java web application, like its predecessors. The backend provides all machine-based interfaces, like REST API, OAI-PMH, SWORD (v1 and v2) and RDF. 

The DSpace Frontend is a beautiful user Interface built on Angular.io. It is a Node.js web application, and once it is compiled, it just requires Node.js to run. It can be installed on a separate machine, but still would need a valid DSpace Backend with REST API access to function. The front end provides all user-facing functionality. 

So that’s the Intro; lets now begin with the installation, I have done this exercise on an Ubuntu Server 22.04.2 machine, with the following configurations 

Hardware: Proxmox virtual machine

RAM : 8 GB,

HDD : 120 GB

Computer Name: Dspace

Username: Jesse

IP Address: 10.2.3.104

So you keep in mind, that you will have to use your system settings, username, IP address etc in the commands, or config file directives, wherever these appear.

To start with Let us perform a system update and upgrade with the following commands

sudo apt update 
sudo apt upgrade

Install Open JDK

The JDK is a development environment for building applications, applets, and components using the Java programming language. JDK prepares an environment to run Java-based applications on the machine. DSpace requires installing the full JDK (Java Development Kit), rather than just the JRE (Java Runtime Environment).  So, please ensure you are installing the full JDK and not just the JRE.

Newer versions of Java may work (e.g. JDK v12-16), but it is not recommended to run them in Production. It is highly recommended to run only Java LTS (Long Term Support) releases in Production, as non-LTS releases may not receive ongoing security fixes. As of this DSpace release, JDK11 and JDK 17 are the most recent Java LTS releases. JDK 17 had a bug which makes it incompatible with tomcat 9, so I preferred to go with JDK 11

sudo apt-get install openjdk-11-jdk openjdk-11-jre openjdk-11-source

After this is installed let’s set the JAVA_HOME Environment Variable so the system knows where the java files are. DSpace requires the Java installation location. Open the following file to add the java environment variable,

sudo nano /etc/environment

Add the following two lines to the file,

JAVA_HOME="/usr/lib/jvm/java-11-openjdk-amd64"
JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8"

By default, this is a location where JDK gets installed on Debian-based systems. so save and close the file. We can check if the environments are configured successfully, with the following commands. The first issue the Source command, to load the environment in the current bash session.

source /etc/environment
echo $JAVA_HOME
echo $JAVA_OPTS

if it’s configured correctly, it should show the location of the java installation directory, and the memory config we defined.

Install Maven and Ant

Apache Maven requires for the build process during the Dspace installation. Maven helps to download the dependencies. Maven is used to build the installer. Ant used to install/deploy DSpace to the installation directory. They are used only once while installing DSpace, we don’t need them after to run the software.

sudo apt install maven
sudo apt install ant

After both packages are installed we can check their version by issuing

ant -version

command and

mvn -version

upon checking the version, I found that my Apache Ant(TM) version 1.10.12 was compiled on January 17 1970 and my Maven Version is Apache Maven 3.6.3. and OpenJDK version “17.0.6” 2023-01-17, Java version: 17.0.6, vendor: Private Build, runtime: /usr/lib/jvm/java-17-openjdk-amd64. After these underlying elements, let’s install the packages we will be directly interacting with.

Install Apache Tomcat

Tomcat provides a “pure Java” HTTP web server environment where Java code can run. As of now, only Tomcat 9 is recommended as Tomcat 10 is a bit buggy, and acts fishy with dspace. so let’s go with tomcat9.

sudo apt-get install tomcat9 tomcat9-admin tomcat9-common -y

Specify the DSpace installation path to Tomcat. Open the following file,

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

Find the category, #Security,

Add the following line at the last portion,

ReadWritePaths=/dspace

Save and close the file.

Pro Tip: I suggest you create a folder named ‘dspace’, at the root of your file system, before doing all of this, otherwise, the tomcat service will keep looking for it, as we have defined it in the tomcat9 service config.

Alter Tomcat’s default configuration to support searching and browsing of multi-byte UTF-8, by opening the server.xml file in tomcat9 folder

sudo nano /etc/tomcat9/server.xml

Find the below-mentioned lines in the file, and comment out. Add  <!– in the first line and –> in the last line, (<!– is used to comment out lines of code)

<Connector port=”8080″ protocol=”HTTP/1.1″
            connectionTimeout=”20000″
            redirectPort=”8443″ />

It will look like this after commented out,

<!– <Connector port=”8080″ protocol=”HTTP/1.1″
            connectionTimeout=”20000″
            redirectPort=”8443″ /> –>

Add the following lines below the commented-out lines,

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

Save and close the file.
Reload the Tomcat daemon and restart the tomcat service to make all changes take effect

sudo systemctl daemon-reload
sudo systemctl restart tomcat9.service

Install Apache Solr

Apache Solr is the search engine used by DSpace. In DSpace 7, apache solr has been decoupled from the rest of the DSpace code, and you have to install and run it separately on port 8983 or another preferred port that is free on your system. Solr 9 is not yet fully supported but can be used provided that you make minor modifications to the out-of-the-box “search/conf/solrconfig.xml” that comes with DSpace 7. so in my Installation, I have used Apache Solr 8.11.2

Create a directory to download and install solar; I have done it in /opt/solr directory 

chance the working directory to /opt with the following command

cd /opt/

then download the solar code from the official website with wget command

sudo wget https://dlcdn.apache.org/lucene/solr/8.11.2/solr-8.11.2.zip

After the download is complete unzip it using the following command

sudo unzip solr-8.11.2.zip

Apply the following command to install Solr as a system service,

sudo bash solr-8.11.2/bin/install_solr_service.sh solr-8.11.2.zip

Apply the following commands one by one to start automatically upon system boot.

sudo systemctl enable solr
sudo systemctl start solr

After the successful installation and configuration, your solr should work on port 8983, the default port of solr. you can also check it by visiting http://localhost:8983

Install PostgreSQL

PostgreSQL, also known as Postgres, is a free and open-source relational database management system. Dspace makes use of PostgreSQL as a Relational Database System. At the time of writing this documentation, PostgreSQL 14 was the latest working version, and that is what I have used. Apply the following command to install PostgreSQL and related packages;

sudo apt-get install postgresql postgresql-client postgresql-contrib libpostgresql-jdbc-java -y

Apply the following command to check the PostgreSQL version number. 

psql -V psql

PostgreSQL 14 is available with Ubuntu 22.04. To check whether the installation of PostgreSQL is successful or not, I get psql (PostgreSQL) 14.7 (Ubuntu 14.7-0ubuntu0.22.04.1) as output which shows that I have installed PostgreSQL 14.7.

Then start the PostgreSQL service by using the following commands.

sudo pg_ctlcluster 14 main start
sudo systemctl status postgresql

Apply the key, CTRL + C, to exit from the screen.

For added security, I decided to Create a password for the PostgreSQL system account, you can skip this step if you are only in development mode, but it is recommended on a production server.

sudo passwd postgres

Try to login into PostgreSQL using the password created.

su postgres

The command prompt looks like this postgres@user: if you login successfully.

Now, in the next step, let’s create a user named dspace, which will have privileges to our dspace database, so we won’t have to use root users to interact with dspace code and the database. Enter the password when it asks. This is the connection password for the DSpace database; note it down. 

createuser --username=postgres --no-superuser --pwprompt dspace

This will also ask to set a new password for the newly created role space. set your desired password.

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

Enable pgcrypto extension. 

The pgcrypto module provides cryptographic functions for PostgreSQL. It secures data from the security breach, and it is a must for dspace to run.

psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;"

Exit from the Postgres terminal,

exit

Now Let’s tweak some Postgres security settings to align with our goal.

Open the PostgreSQL conf file with the following command,

sudo nano /etc/postgresql/14/main/postgresql.conf

Uncomment the line (remove #) listen_addresses = ‘localhost’ under the connection settings option, this will enable the PostgreSQL server to listen to all requests originating from localhost. we can also change it to network, but for now, let’s play it safe.

Save and exit

We need to tighten the security of PostgreSQL in pg_hba file. Open this file here,

sudo nano /etc/postgresql/14/main/pg_hba.conf

Now here we need to define a Database administrative login by TCP/IP socket, so just Add the following lines at the end of the file,

#DSpace configuration
host dspace dspace 127.0.0.1/32 md5

Restart Postresql

sudo systemctl restart postgresql

That’s it for now here.

Dspace Installation

It is a most common misconception among the dspace user community that you need a separate dspace system user to set folder permissions and compile the code. This is understood because the system user ‘dspace’, being the non-root user, is safe for tomcat to work. As per Dspace wiki, Tomcat (or Jetty, etc.) must run as an operating system user account that has full read/write access to the DSpace installation directory (i.e. [dspace]).  Either you must ensure the Tomcat owner also owns [dspace], OR you can create a new “dspace” user account and ensure that Tomcat also runs as that account:

But let me tell you, this is completely unnecessary and makes things utterly complicated. Instead of doing this, I chose to run everything on my user (for me, it’s ‘jesse’, you can have anything you like on your system). I have installed tomcat and solr, with appropriate permissions on this user, and will compile the dspace code using this user only so that everything will run smoothly.

Before we download and compile the space source code, let us create our dspace working directory with the following command.

Note: I recommend creating this directory in the beginning, before even installing the Tomcat, so we can define the dspace folder location in the tomcat service config.

  sudo mkdir /dspace

for now, we can make the current user the directory’s owner so it has full permissions.

sudo chown -R jesse:jesse /dspace

As you can see I have created a dspace working directory at the root of the file system, but you can choose to make it anywhere you like; just make sure it has the right permissions. This is where your dspace code will be compiled, and this is where it will run from.

Downloading the Dspace 7.5 backend source code

Because we will keep the source code in a temporary directory, I downloaded it in my user folder. you may switch to your user on the command line and download the code there. Once you are in the directory you want to download the code to, execute the following wget command. switch to your user home folder by giving the following command.

cd ~

now on this location, we can download the dspace source code without worry.

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

extract the downloaded file with unzip command

unzip dspace-7.5.zip

Go to the unzipped dspace source code folder at

~/DSpace-dspace-7.5/dspace/config$

and make a copy of the local.cfg file, from the already existing local.cfg.Example file,

cp local.cfg.EXAMPLE local.cfg

then Edit the local.cfg file ,

nano local.cfg

and make appropriate changes to this file as per your server environment, as I already mentioned, my server IP is 10.2.3.104, you may want to use yours, or you can simply use localhost, if you’re running it in development mode. 

DSpace server URL
dspace.server.url = http://10.2.3.104:8080/server

DSpace frontend URL
dspace.ui.url = http://10.2.3.104:4000

Now below this line, you may also want to add

rest.cors.allowed-origins = ${dspace.ui.url}

This string will resolve all possible errors you may encounter while accessing the frontend UI with IP over the network. This is a major issue that most people face when they install Dspace 7.X, Because on localhost, dspace works well but starts to play shenanigans when requested over the network.

# Name of the site
dspace.name = DSpace at Central University of Punjab
# Database username and password
db.username = dspace
db.password = (This will be your Dspace database password)

Uncomment the following line in the local.cfg file,

solr.server = http://localhost:8983/solr

Save and close the file.

Now you need to get out of the config folder and come back to our extracted dspace folder

 cd ~/DSpace-dspace-7.5/

and run the maven downloader command in this folder. Remember, our user has full permissions to this folder so we are not using sudo anywhere here.

mvn package

This may take some time, depending on your internet speed.

Apache ant is now used to copy/install the compiled dspace code into the deployment directory, test if our code can connect to the database and then create necessary tables for us. To do this, run these commands

cd dspace/target/dspace-installer

ant fresh_install

If you follow these steps precisely, you should be able to see “BUILD SUCCESSFUL” after both of these commands.

Copy Solr cores: 

With this, the Webapps field and Solr cores have been already created by the installer, we just need to place them in the right place. 

Copy the Solr Cores from [dspace]/solr to the place where your Solr instance will discover them.

sudo cp -R /dspace/solr/* /var/solr/data
sudo chown -R solr:solr /var/solr/data

Copy the DSpace web apps folder to the Tomcat server,

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

Create DSpace Administrator Account

sudo /dspace/bin/./dspace create-administrator

This will prompt you with some basic information for creating an admin account.

Creating an initial administrator account
E-mail address: e.g. admin@cup.edu.in
First name: Rupinder
Last name: Singh
Is the above data correct? (y or n): y
Password will not display on the screen.
Password: type your desired dspace admin password here
Again to confirm: just type in carefully, it will not show any input on the terminal screen
Administrator account created

DSpace Administrator Account Creation

Since we have been doing everything with user permissions, we need to grant appropriate permissions to the tomcat user, so it can discover dspace code and make submissions.

sudo chown -R tomcat:tomcat /dspace/
sudo systemctl restart tomcat9.service

After this, you can access the backend via its web interface by opening the following REST and OAI URLs.

http://10.2.3.104:8080/server

Try to open OAI-PMH Interface,

http://10.2.3.104:8080/server/oai/request?verb=Identify

Now you will be able to see the HAL browser of the Dspace Backend, it has nothing much to show, but it will be used for the frontend to interact with the dspace repository. That is it for the backend, your dspace server is set up. Now let’s move to give it a pretty face.

Install the Front End

To install the front required to install Node.js, Yarn, and DSpace-Angular packages.

Install Node.js

It’s a powerful tool that helps you create fast and efficient web applications with ease. open-source, trimmed-down version of JavaScript. It is flexible, and cross-platform which is why it is good at handling large amount of data and real time transactions.

sudo apt install nodejs  npm -y

Install NVM

Node Version Manager (NVM) is a life saver when it comes to managing multiple Node.Js versions, because, otherwise it’s just a pain in the wrong place, so it is highly recommended to install NVM to keep things simple and neat. NVM works by allowing you to install multiple versions of Node.js side by side on your machine, and then easily switch between them as needed. this can be downloaded from GitHub repository, you can pull it from git, or just use wget it .

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

source ~/.bashrc

This will download the latest Node Version Manager to your system and will load the environment into the current user bash. Then you can use the nvm list-remote command to view the versions of Node.js available on the internet.

nvm list-remote

I found v18.14.2 (Latest LTS: Hydrogen) as the latest LTS release, and the DSpace wiki also acknowledges that, so I installed this.

nvm install 18.14.2

Now let us install Yarn. Yarn is also a package manager for Node.js and other programming languages. Yarn offers many advantages like improved caching and offline mode and more consistent and deterministic package installations. Additionally, Yarn offers a simpler and more user-friendly command-line interface, as well as more robust security features.

npm install --global yarn

With this let’s also install PM2, PM2 (Process Manager 2) is a popular and powerful process manager for Node.js applications. It allows developers to manage their Node.js processes in a production environment, ensuring that they are running smoothly and efficiently. We will have to use it for the production server because it helps in automating the startup of the angular frontend interface.

npm install --global pm2

That’s all the prerequisites for DSpace angular front end, now we are ready to download the source code and install it.

Front end installation

DSpace user interfaces build on Angular. Angular is a TypeScript-based free and open-source web application framework. Follow the steps to install Dspace-Angular.

We are going to place the DSpace-angular package into your user home folder. Enter it into the folder;

cd ~

Download the dspace-angular package,

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

Extract the package,

unzip dspace-7.5.zip

Remove the dspace zip package,

rm dspace-7.5.zip

rename the dspace extracted folder to ‘dspace-angular’ just to keep things understandably easy.

mv dspace-angular-dspace-7.5/ dspace-angular

Enter into the dspace-angular folder, 

cd ~/dspace-angular-dspace-7.5

Install all dependencies,

yarn install

Enter into the /dspace-angular/config folder,

cd config

Copy and rename the following file,

cp config.example.yml config.prod.yml

Open the config file

nano config.prod.yml

Find the block of information and find the lines.  Make changes like this,

ssl: true -> false
host:  10.2.3.104
Port: Change to 8080
# The REST API server settings
# NOTE: these must be ‘synced’ with the ‘dspace.server.url’ setting in your backend’s local.cfg.
rest:
ssl: false
host: 10.2.3.104
port: 8080

we are running it on the local network, so SSL is not required, or I can say, It’s difficult to set up, up because SSL certificates are issued to URLs not IP addresses, so, for now, we will turn this to false, but when you want to publish your repository to the internet, I recommend to get an SSL certificate and configure it accordingly with your web server. that will be a much more secure thing to do. anyway, for now, let’s just Save and close the file.

Run the following command, this will compile the dspace angular code and build it as per the directives we mentioned in the config.prod.yml file.

yarn run build:prod

If in future, you decide to change anything in the config.prod.yml file you may have to run this build: prod command again, to recompile the code.

Now with this, your Dspace frontend interface is ready, and you can start it using the following command directly

yarn start

After this, your Dspace Web User Interface should be accessible via

http://10.2.3.104:4000

(10.2.3.104 is my server IP address, you may want to change it to yours, or you can use localhost if you are running it locally on a development server)

But, this is for lazy people who want to see their space working and not planning to take it on the production server. Because each time you close the terminal or kill the command, the yarn will stop working too, and so will your Dspace front-end web UI. This is why we involved PM2 here. This will help us run it as a background service and help set up a scheduled task to start it automatically.

Startup the User Interface

Create a PM2 JSON configuration file. 
Create the file,

sudo nano /home/jesse/dspace-angular/dspace-ui.json

Copy the following content into this newly created dspace-ui.jason file,

{
“apps”: [
{
“name”: “dspace-ui”,
“cwd”: “/home/jesse/dspace-angular/”,
“script”: “dist/server/main.js”,
“instances”: “max”,
“exec_mode”: “cluster”,
“env”: {
“NODE_ENV”: “production”,
“DSPACE_REST_SSL”: “true”,
“DSPACE_REST_HOST”: “localhost”,
“DSPACE_REST_PORT”: “8080”,
“DSPACE_REST_NAMESPACE”: “/server”
}
}
]
}

Press Cltr X to save the file and exit the nano editor.

while you are in the Dspace-angular folder type in the following command to start the application using PM2.

pm2 start dspace-ui.json

Automating the frontend Startup

This will work just fine for most of us working on development, but when this is on production, we can’t ssh to the server each time to start the dspace-ui, so it is best to create a scheduled job autostart dspace-ui.json whenever the server machine starts. To make it so, we open the crontab and create a cronjob entry, and we’d do it as root users so :

sudo crontab -e

Add the following line

#Auto start dspace-angular

@reboot pm2 start /home/jesse/dspace-angular/dspace-ui.json 
#Autostart the Dspace Angular User Interface

Save and exit the nano editor using CTRL + X.

Congratulations, you now have a perfectly working Dspace 7.5 Repository server. You can explore, tweak, build, and use it as you, please.

I would love to hear from you about your experience with Dspace 7.5, and I will be happy to help with the problems. However, I don’t claim to be an expert on it; there are so many wise souls from whom I took guidance; and this is where I would like to thank them too. Here are a few mentions.

Installing DSpace – Confluence Mobile – LYRASIS Wiki

Install DSpace 7 Backend and Frontend on a VirtualBox Debian 11 Server – YouTube

Using DSpace 7.4 – YouTube

Install DSpace 7 on Ubuntu 18.04 – Hyperlink Data Solutions

Dspace Geek: Install DSpace 7 on Debian 11 / Ubuntu 22.04 LTS