The instructions here will show you how to install DSpace 7 on Ubuntu 18.04. It is important to note that DSpace 7 has not yet been released at the time of writing this guide. One of the main changes in DSpace 7 is that it has been split into a front-end and a back-end. The front-end is the user interface and the back-end is mostly used to serve the REST-APIs and is not user friendly. To have a fully functional dspace 7, you need to install both, preferably on the same system.

These instructions assume that you have already installed Ubuntu and is connected to the internet. The instructions also assume that you have very little understanding of the Linux command-line and advanced users will therefore find some instructions trivial.

In summary the installation shall include the following steps

Update your System

Before starting, ensure that you are logged-in as a non-root user with sudo previleges, i.e., you can use sudo command. Then proceed to update your Ubuntu system with the following two commands.

sudo apt update

The above command ensures that your apt cache is updated with the latest Ubuntu package information, while the following will upgrade all the packages that need updating.

sudo apt upgrade -y

Part One: Install Prerequisites

Install Java OpenJDK 11

The official documentation for DSpace 7 has specified that Java (Oracle JDK or OpenJDK) can be used starting from version 11 or above. However, version 11 is prefered. Older versions are not supported and versions newer than 11 may work but should not be used in production.

In this guide, we shall install OpenJDK 11. OpenJDK 11 is included by default in Ubuntu 18.04’s package repository. Therefore, to install we shall need to run the command below:

sudo apt install openjdk-11-jdk

To confirm the version installed on the system, type the following command on the terminal.

java -version

Install Apache Maven and Ant

DSpace 7 requires maven 3.3.x or above and and 1.8.x or above.

Maven is used to compile the dspace source-code and is also responsible for downloading any depencies that the dspace code requires to run. Ant is used to install the compiled DSpace code. On Ubuntu 18.04, install both maven and ant with with the following single command

sudo apt-get install ant ant-optional maven -y

This will install maven 3.6.0 and ant 1.10.5. To check the versions installed, see the following commands.

mvn -v

ant -version

Install PostgreSQL Database v11

DSpace 7 is developed and tested on PostgreSQL 11. PostgreSQL v11 is available by default in the Ubuntu 18.04 packages repository. To install it, we shall first add its repository signing key

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -

Then add the actual repository contents to Ubuntu 18.04 system

 echo "deb http://apt.postgresql.org/pub/repos/apt/ bionic"-pgdg main | sudo tee  /etc/apt/sources.list.d/pgdg.list

Update the system to read the list of packages for PostgreSQL

sudo apt update

Then install PostgreSQL 11

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

Set up host based access access on PostgreSQL by editing pg_hba.conf file by opening it as shown below

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

Add the following line to the bottom of the file then save and close.

host    dspace       dspace      127.0.0.1/32         md5

This will set up host based type of access on a database called dspace by the database user called dspace on the specified localhost (127.0.0.1) address. We shall create the dspace database user and database at a later stage.

Next, execute the following 3 commands in succession to change database user permissions to “trust” only.

sudo sed -i 's/ident/trust/' /etc/postgresql/11/main/pg_hba.conf
sudo sed -i 's/md5/trust/' /etc/postgresql/11/main/pg_hba.conf
sudo sed -i 's/peer/trust/' /etc/postgresql/11/main/pg_hba.conf

Restart PostgreSQL database for these changes to take effect.

sudo systemctl restart postgresql

We now have to create the dspace database user and the dspace database itself as earlier mentioned. Swicth to the postgres system user first.

sudo su postgres

When installing postgresql database, a default system user by the name postgres is created. In the above command, we have changed the commandline session to use this user’s account. Then create the dspace database user with the following command

createuser dspace

Now create the dspace database with the following commands

createdb dspace -E UNICODE

This will create a database called “dspace” with unicode encoding

Next we need to grant permissions to the database user called dspace to the database we just created, also called dspace. Access the database shell and use the dspace database with the following single command

psql -d dspace

Then start by creating the pgcrypto extension to the dspace database

CREATE EXTENSION pgcrypto;

Create the password

ALTER ROLE dspace WITH PASSWORD 'your-db-password-here';

Replace the text in quotes above to a secret password of your choice on a production system !

Then give the dspace database user ownership of the dspace database as shown here.

ALTER DATABASE dspace OWNER TO dspace;

Then give all privileges to dspace database user on the dspace database with the command below

GRANT ALL PRIVILEGES ON DATABASE dspace TO dspace;

To view the list of databases existing on the system together with other details like database ownership, issue the following command

\l

Now we have a working database setup and after we install dspace, we will just need to configure our dspace installation to connect to this database with the configured username and password on localhost.

Exit the PostgreSQK shell by the following command

\q

Exit the postgres user session with the following command

exit

Restart PostgreSQL with the following command

sudo systemctl restart postgresql

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 prefered port that is free on your system.

Create a directory to download and install solr. In this guide, we shall use /opt/solr-7.7 to depict the version of solr we shall use. DSpace 7 requires Solr 7.2.1 or later.

sudo mkdir /opt/solr-7.7

Change to the directory we just created

cd /opt/solr-7.7

Change the directory owner to the dspace user

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

Then download solr-7.7.3 from there with the following command

wget -c https://downloads.apache.org/lucene/solr/7.7.3/solr-7.7.3.tgz

Extract the downloaded archive with this command

tar xvf solr-7.7.3.tgz

Move the contents to /opt/dspace-7.7 directory

cp -rf /opt/solr-7.7/solr-7.7.3/* /opt/solr-7.7/

Remove redundant directory and the archive we already extracted

rm -rf solr-7.7.3 solr-7.7.3.tgz

Start solr with the following command

/opt/solr-7.7/bin/solr start &

Confirm solr is running with

/opt/solr-7.7/bin/solr status

If you access http://server-url:8983/solr in your browser, solr admin dashboard should load. If it doesn’t, review the steps followed again

Install tomcat8 servlet

DSpace 7 can function with tomcat 8 or 9. Install tomcat 8 with the following command

sudo apt install tomcat8 -y

Edit /etc/default/tomcat8 and define JAVA_HOME

sudo nano /etc/default/tomcat8

The value JAVA_HOME basically indicates to the system where your java is installed and this will depend on how you installed java and your operating system. An example of JAVA_HOME is shown below

JAVA_HOME=/usr/lib/jvm/java-1.11.0-openjdk-amd64

Locate the setting JAVA_OPTS and adjust maximum and minimum memory settings accordingly depending on how much RAM your system has. Tomcat8 requires at least 1GB memory to function normally. The following setting is good for a system with 4GB RAM

JAVA_OPTS="-Djava.awt.headless=true -Xmx2048m -Xms1024m -XX:MaxPermSize=1024m"

Save and close the file.

Alter Tomcat’s default configuration to support searching and browsing of multi-byte UTF-8 correctly. Edit the file server.xml by editing as shown

sudo nano /etc/tomcat8/server.xml

Ensure that the active connector element in the file is similar to the one below. You can comment out the existing element and paste in the one below:

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

Save and close the file, then restart tomcat8 as shown below

sudo systemctl restart tomcat8

Now, when you access the ip address of your system via the browser at port 8080 i.e., http://ip-address:8080, you should see the default tomcat page, It works ! . If not, you need to review the process.

Part Two: Install the Backend

Download the source code

Get the latest DSpace release from Github and download as shown below

wget -c https://github.com/DSpace/dspace-angular/archive/dspace-7.0-beta3.tar.gz

Extract the downloaded archive

tar zxvf dspace-7.0-beta3.tar.gz

This will result in a directory named DSpace-dspace-7.0-beta3. Rename this directory to make it shorter and easy to type.

mv DSpace-dspace-7.0-beta3 dspace-7

Change to the source code directory

cd dspace-7

Initial configuration

Create the installation directory

sudo mkdir /opt/dspace-7

Set permissions for the dspace user on the installation directory

sudo chown dspace:dspace -R /opt/dspace-7

Create a configuration local.cfg file by copying the existing example file.

cp dspace/config/local.cfg.EXAMPLE dspace/config/local.cfg

Edit the file and set some common required settings such as the database connection and the installation directory

nano dspace/config/local.cfg

For now, search for and configure the following settings accordingly

dspace.dir=/opt/dspace-7
solr.server = http://localhost:8983/solr
db.url = jdbc:postgresql://localhost:5432/dspace
db.driver = org.postgresql.Driver
db.username = dspace
db.password = dspace

Build DSpace

Ensure you are in the source code directory then run the command

mvn package

The output of the command if successful, will look as the image below

Install DSpace

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

cd dspace/target/dspace-installer

ant fresh_install

If successful, you should see output similar to the following

Deploy the server web app

The dspace 7 backend comprises only one web app which in our case will be located in /opt/dspace-7/webapps/server . This needs to be deployed to tomcat’s webapps directory. Use the following commands to achieve this.

Change to tomcat8’s webapps’ directory

cd /var/lib/tomcat8/webapps

Create a symbolic link to the server webapp

sudo ln -s /opt/dspace/webapps/server server

Then restart tomcat as shown in one of the previous steps. If you access http://server-ip:8080/server, you should be able to see the backend interface as shown below

Copy over solr cores

cp -r /opt/dspace-7/solr/* /opt/solr-7.7/server/solr/configsets

Then restart solr as shown here

/opt/solr-7.7/bin/solr restart &

Part Three: Install the Front End

Install node

Download and install the node version manager with the command below:

Before proceeding, go to this link https://github.com/creationix/nvm/releases to check the current stable release and update the command below accordingly.

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

Before proceeding, open a different terminal session and type the command below just to ensure that nvm installed correctly. If you used the above installation command without changing the version bit, it should output 0.35.3. You must exit the shell session you used to install and reopen a different one before proceeding.

nvm --version

Finally let’s install node v12 LTS itself with the command below

nvm install 12.18.3

Install Yarn

You can install Yarn on Ubuntu via the Debian package repository. First configure the repository:

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Then update the system and install yarn with

sudo apt update && sudo apt install yarn

Confirm that yarn is installed with the command

yarn --version

If the version is older than v1.x, upgrade yarn with the following command

curl --compressed -o- -L https://yarnpkg.com/install.sh | bash

This will download and install the latest version of yarn

Download DSpace 7 front-end

Download the latest dspace 7 front end release from this page on github https://github.com/DSpace/dspace-angular/releases

It is preferable that you download it from the dspace user’s home directory i.e., /home/dspace/

wget -c https://github.com/DSpace/dspace-angular/archive/dspace-7.0-beta3.tar.gz

Then extract the downloaded archive

tar zxvf dspace-7.0-beta3.tar.gz

You will have a directory named dspace-angular-dspace-7.0-beta3 or similar. Rename this file to shorten the name

mv dspace-angular-dspace-7.0-beta3 dspace-7-angular

Change to the directory

cd dspace-7-angular

And then build the front-end dependencies using yarn

yarn install

Modify the front-end to connect to your DSpace back-end by editing the following file

nano src/environments/environment.common.ts

Look for the section on The REST API server settings and modify it accordingly, for example

rest: {
   ssl: false,
   host: 'localhost',
   port: 8080,
   // NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
   nameSpace: '/server/api'
}

Move the front-end files to the /opt directory change ownership to dspace system user

sudo cp -r dspace-7-angular /opt/

sudo chown dspace:dspace -R /opt/dspace-7-angular

Change to the front-end directory

cd /opt/dspace-7-angular

Build and run the front-end application

yarn start

If you encounter the error Command failed with exit code 137 it is most likely that node consumed more memory that your system can handle. Edit the file package.json with the following command

nano package.json

Then look for --max_old_space_size and edit it to ensure that the memory allocation does not exceed that which your system can handle. For instance, if you have 4GB memory on your system, you can assign it the value 3072

The command will take some time to start. When finished, you will see output similar to the following

When done, access the front-end at http://server-ip:4000

To stop the application, press Ctrl + C. To restart the server without having to rebuild run node dist/server from the same directory. To run the command in the background, use the command

nohup node dist/server > nohup.out &