Dspace Technical Documentation Fredrick Odongo Okite [Odongofredrick@Gmail.Com], David Bukenya [Dbankens@Gmail.Com] Uganda Christian University Library

Home , R (complexity)

DSpace Technical Documentation Fredrick Odongo Okite [[email protected]], David Bukenya [[email protected]] Uganda Christian University Library. Credit to Hilton Gibson, Stellenbosch University.

Table of Contents UCUDIR DSpace System details ...... 4 Preparation Stage ...... 5 Terms to note ...... 5 Essential requirements for DSpace 6.2 to run ...... 5 Installing Postgresql in Ubuntu: ...... 5 Git (code version control) ...... 9 Installing tomcat ...... 9 Setup Tomcat to listen on insecure port 80 ...... 10 For secure Port 443: ...... 10 Step2: Apply for a signed certificate ...... 14 Step 3. Get the intermediate CA certs ...... 15 Intermediate CA certs links ...... 15 Step 4. Configure Tomcat to use the SSL certs ...... 16 Setup Tomcat "server.xml" to use the converted certificate ...... 16 Step 5. Enable secure XMLUI logins ...... 18 Step 6. Enable HTTPS by default (Optional) ...... 18 Java environment settings for Tomcat webapp server ...... 18 Setup user permissions ...... 19 Installing DSpace ...... 19 1. Getting DSpace software ...... 19 2. Unpacking DSpace ...... 19 3. Editing DSpace Configuration ...... 19 4. Building DSpace ...... 23 5. Installing DSpace ...... 24 6. Creating DSpace Super-admin user ...... 24 7. Telling Tomcat where to find Dspace ...... 24 8. Testing DSpace ...... 25 Essential Directory trees ...... 26 Servlet Engine [Tomcat7] Directories for UCUDIR ...... 26 CATALINA_HOME ...... 27 Important directories for backup and restore ...... 28 How to configure the Handle server ...... 29

Prepare an initial handle request ...... 29 Send handle request email ...... 29 Update DSpace config file ...... 31 Rebuild DSpace ...... 31 Checking for correct operation ...... 32 Listening Ports ...... 32 Handle service ...... 32 Handle config ...... 32 Handle log ...... 32 Rebuild config ...... 32 Start service manually ...... 32 DSpace security policy ...... 33 Create new thumbnails ...... 38 Setting up usage config file ...... 39 Re-indexing statistics ...... 40 Step 2 - Enable the DSpace authority control event listener ...... 41 Step 3 - Configure the ORCID authority control plugin ...... 41 Step 3.1 ...... 41 Step 3.2 ...... 42 Step 4 - Rebuild DSpace ...... 43 Step 5 - Create an ORCID authority index cache ...... 43 Tomcat Security ...... 43 Folder and file permissions/ownership ...... 43 WARNING: ...... 43 Step 6 - Maintain ORCID authority index cache...... 43 Step 6.1 - Ad-hoc update ...... 43 Step 6.2 - Regular update...... 43 Step 6.3 - Export authority records ...... 43 Upgrading DSpace...... 44 Upgrading an existing Dspace ...... 44 Migrating to a new installation...... 46

UCUDIR DSpace System details Server IP: e.g 196.43.140.182

Server OS: Ubuntu 16.04.3 LTS (GNU/Linux 4.4.0-87-generic x86_64)

UCUDIR Version: Dspace 6.2

Servlet Container: Apache-Tomcat7

JDK: java-7-openjdk-amd64

$JAVA_HOME: /usr/lib/jvm/java-7-openjdk-amd64

Tomcat home: /var/lib/tomcat7

Tomcat config: /etc/tomcat7/Catalina/localhost/

CATALINA_HOME: /usr/share/tomcat7

Builder: 4.4.0-101-generic

Installer: Apache Ant(TM) version 1.9.3

[dspace-source]: /home/dspace/dspace-6.2-release

[dspace] : /dspace

Preparation Stage

Terms to note [dspace-source]: Location of source code (where DSpace download has been unpacked) for DSpace see table above;

[dspace]: location where DSpace is installed and running from owned by tomcat and dspace users see table above; You can change installation directory by changing the value of “dspace.dir” found in the dspace-6.2-release/dspace/config/dspace.cfg file. Then rebuild and reinstall.

[dspace-web deployment]: location where the web-app is running, see below [dspace]/webapps/ Essential requirements for DSpace 6.2 to run Operating System

o Linux o Windows o Macintosh

Java services

● JDK 7 or 8 (OpenJDK or Oracle JDK) or Jetty, Caucho Resin or equivalent ● Java servlet container ● Maven for installer construction ● Ant for deployment

RDMS

● Postgresql 9.4 or above (DSpace 6 requires Postgres 9.4+ with the pgcrypto extension enabled)

Oracle RDMS Installing Postgresql in Ubuntu: Increase the kernel shared memory for PostgreSQL server client connections:

Edit the "/etc/sysctl.conf" file: sudo nano /etc/sysctl.conf

Copy and paste the following to the end of the file: # For PostgreSQL server client connections

5 kernel.shmmax = 500000000 kernel.shmall = 500000000

Save and exit the file. Type: sudo sysctl -p

Should display the settings added above

Install PostgreSQL server software using the following commands

Note: examples below are based on PostgreSQL version 9.5) sudo apt-get install postgresql-9.5 postgresql-contrib-9.5 libpg-java

Setup the PostgreSQL server host based access permissions by editing the "pg_hba.conf" file. sudo sed -i 's/ident/trust/' /etc/postgresql/9.5/main/pg_hba.conf

sudo sed -i 's/md5/trust/' /etc/postgresql/9.5/main/pg_hba.conf

sudo sed -i 's/peer/trust/' /etc/postgresql/9.5/main/pg_hba.conf

See example below. # DO NOT DISABLE!

# If you change this first entry you will need to make sure that the

# database superuser can access the database using some other method.

# Noninteractive access to all databases is required during automatic

# maintenance (custom daily cronjobs, replication, and similar tasks).

# Database administrative login by Unix domain socket local all postgres trust

# TYPE DATABASE USER ADDRESS METHOD

# "local" is for Unix domain socket connections only local all all trust

# IPv4 local connections: host all all 127.0.0.1/32 trust

# IPv6 local connections: host all all ::1/128 trust

# Allow replication connections from localhost, by a user with the

# replication privilege.

#local replication postgres trust

#host replication postgres 127.0.0.1/32 trust

#host replication postgres ::1/128 trust

Restart database server. sudo service postgresql restart

Create the PostgreSQL "dspace" DB user

Create the "dspace" DB user with full privileges. sudo createuser -U postgres -d -A -P dspace

Answer "y" for yes, for any of the user creation questions. Create the PostgreSQL "dspace" database

Enter the Ubuntu server postgres user shell. sudo su - postgres

Create the "dspace" database. createdb -E UNICODE dspace

Setup PostgreSQL dspace DB user password, ownership and privileges

Connect to the PostgreSQL database server and enter a PostgreSQL database server shell. psql -U postgres -d dspace

Set the dspace DB user password:

SECURITY WARNING: Use your unique dspace database password for this on a production system !

ALTER ROLE dspace WITH PASSWORD 'XXXXXX';

Let the dspace DB user own the dspace database

ALTER DATABASE dspace OWNER TO dspace;

Grant all privileges for the dspace database to the dspace DB user

GRANT ALL PRIVILEGES ON DATABASE dspace TO dspace;

Add the "crypto" extension to the "dspace" database.

CREATE EXTENSION pgcrypto;

Quit the database shell.

We exit from PostgreSQL database server postgres user shell and return to the Ubuntu server dspace user shell. exit

Setup the PostgreSQL server host based access permissions to the dspace database

Type the following: sudo -i sudo echo "## DSpace DB user access">> /etc/postgresql/9.3/main/pg_hba.conf sudo echo "host dspace dspace 127.0.0.1/32 md5" >> /etc/postgresql/9.3/main/pg_hba.conf exit

Setup maximum number of PostgreSQL server client connections

Edit the postgresql config file: sudo nano /etc/postgresql/9.5/main/postgresql.conf

Change the number of "max_connections" to 300. Please note: If you get connection errors, then adjust this value! Save and exit the file. Restart the PostgreSQL server Type the following:

8 sudo service postgresql restart Git (code version control) for mirage2 build to be successful

Installing tomcat sudo apt install tomcat7 -y

Allow Tomcat to listen on ports "80" and "443"

Setup "authbind" for Tomcat

To enable Tomcat to listen on a privileged port below 100, we need to enable "authbind". Edit the /etc/default/tomcat7 file as follows: sudo nano /etc/default/tomcat7

Remove the hash sign from in front of the authbind parameter and change authbind to yes as follows # If you run Tomcat on port numbers that are all higher than 1023, then you # do not need authbind. It is used for binding Tomcat to lower port numbers. # NOTE: authbind works only with IPv4. Do not enable it when using IPv6. # (yes/no, default: no) AUTHBIND=yes

Save and exit the file. Now we need to tell "authbind" that Tomcat is allowed to use lower port numbers. Type the following commands: sudo touch /etc/authbind/byport/80 sudo touch /etc/authbind/byport/443 sudo chmod 0755 /etc/authbind/byport/80 sudo chmod 0755 /etc/authbind/byport/443 sudo chown tomcat7.tomcat7 /etc/authbind/byport/80 sudo chown tomcat7.tomcat7 /etc/authbind/byport/443 cd /etc/authbind/byport ls -l

Now Tomcat has permission to use ports 80 and 443. See below for an example listing of the files in the /etc/authbind/byport folder. dspace@dspace:/etc/authbind/byport# ls -l total 0 -rwxr-xr-x 1 tomcat7 tomcat7 0 2011-06-10 18:33 443

-rwxr-xr-x 1 tomcat7 tomcat7 0 2011-06-10 18:33 80

Setup Tomcat to listen on insecure port 80 Now we tell the Tomcat server to listen on the "authbind" ports. Edit the following file. sudo nano /etc/tomcat7/server.xml

Find the connector for port 8080 and change it to port 80. See example below.

If enabled, comment out the AJP 1.3 connector. It is not needed. Save and exit the file. For secure Port 443: Step 1. Create the SSL certificates Become root as follows: sudo -i

Make the scripts folder: mkdir /root/scripts

Strong Encryption (Browser support varies) - Create DSA with SHA 256 certificate request

Open the script file: nano /root/scripts/make-cert-dsa

Then copy and paste the following into the nano editor. Please read the config notes below carefully. #! /bin/bash

# Check for SSL binaries test -x /usr/bin/openssl || apt-get install openssl

# Setup certificate variables

HOST="XXXXXXXXXXXXXXX"

EMAIL="XXXXXXXXXXXXXX"

BITS="2048"

DAYS="365"

# Set certs path

CERTS="/etc/ssl/certs/"

# Define the config file to be used to create certs

# Fill in your own values for "ST", "L", "O" and "OU"

CONF="\n

[ req ] \n default_bits = $BITS \n encrypt_key = yes \n distinguished_name = req_dn \n x509_extensions = cert_type \n prompt = no \n

[ req_dn ] \n

C=ZA \n

ST=WP \n

L=Stellenbosch \n

O=Universiteit Stellenbosch \n

OU=JS Gericke Library \n

CN=$HOST \n emailAddress=$EMAIL \n

[ cert_type ] \n nsCertType = server \n

" echo -e $CONF > $HOST.cnf

11 sleep 3

# Build path for certificate creation

CPATH="$CERTS$HOST"

# Create a new key openssl dsaparam -noout -out $CPATH.key -genkey $BITS

# Create the new certificate openssl req -new -sha256 -x509 -days $DAYS -nodes -config $HOST.cnf -key $CPATH.key -out $CPATH.crt

# Create a new certficate request openssl req -new -sha256 -key $CPATH.key -config $HOST.cnf > $CPATH.csr

# Create a "pem" file suitable for Apache2 cat $CPATH.key $CPATH.crt > $CPATH.pem

# Clean up rm -f $HOST.rand

Weak Encryption (Browser support good) - Create RSA with SHA256 certificate request

Open the script file: nano /root/scripts/make-cert-rsa

Then copy and paste the following into the nano editor. Please read the config notes below carefully. #! /bin/bash

# Check for SSL binaries test -x /usr/bin/openssl || apt-get install openssl

# Setup certificate variables

HOST="XXXXXXXXXXXXXXXX"

EMAIL="XXXXXXXXXXXXXXX"

# Set certs path

CERTS="/etc/ssl/certs/"

# Define the config file to be used to create certs

# Fill in your own values for "ST", "L", "O" and "OU"

CONF="\n

[ req ] \n default_bits = 2048 \n encrypt_key = yes \n distinguished_name = req_dn \n x509_extensions = cert_type \n prompt = no \n

[ req_dn ] \n

C=ZA \n

ST=WP \n

L=Stellenbosch \n

O=Universiteit Stellenbosch \n

OU=JS Gericke Library \n

CN=$HOST \n emailAddress=$EMAIL \n

[ cert_type ] \n nsCertType = server \n

" echo -e $CONF > $HOST.cnf sleep 3

# Build path for certificate creation

CPATH="$CERTS$HOST"

# Generate the new key and certificate openssl req -new -sha256 -x509 -days 365 -nodes -config $HOST.cnf -out $CPATH.crt -keyout $CPATH.key

# Create a new certficate request openssl req -new -sha256 -key $CPATH.key -config $HOST.cnf > $CPATH.csr

# Create a "pem" file suitable for Apache2

13 cat $CPATH.key $CPATH.crt > $CPATH.pem

# Clean up rm -f $HOST.rand

NOTES: Change the following to suit your organisation:

● $HOST - This is the hostname of the server for which you are creating the SSL certificate. ● $EMAIL - This is the system administrator email address. ● C = This is the country, ZA for South Africa ● ST = This is the state/province, WP for Western Province ● L = This is the locality/town/city, Stellenbosch for us ● O = This is the organisation, Stellenbosch University for us ● OU = This is the organisational unit, JSG Library for us Make the selected script executable Now we make the script executable as follows: chmod 0755 /root/scripts/make-cert-rsa

OR chmod 0755 /root/scripts/make-cert-dsa

Then we execute the script as follows: /root/scripts/make-cert-rsa

OR /root/scripts/make-cert-dsa

Step2: Apply for a signed certificate Application Send the file, %hostname%.csr in the /etc/ssl/certs folder to a recognised certificate authority for signing. Try to shop around for the best prices. See: http://www.sslshopper.com Activation Assuming that the supplied signed certificate from your chosen SSL registrar above, is called verisign.cer and is stored in the /root folder, follow the procedure below as the root user to activate the signed certificate. sudo -i cd /root

14 cp verisign.cer /etc/ssl/certs/%hostname%.crt

Replace %hostname% with the hostname of your server. To extract details of the signed certificate, type the following. openssl x509 -text -in /etc/ssl/certs/%hostname%.crt

Check CSR Click on the following link to check the CSR: https://ssltools.websecurity.symantec.com/checker/views/csrCheck.jsp

Step 3. Get the intermediate CA certs Consult with your SSL certificate provider for instructions on how to get the required intermediate CA certs. Below are some example intermediate certs. Download the certs from the following links by typing as follows: cd /etc/ssl/certs

Get the primary intermediate Symantec CA cert: wget http://web.lib.sun.ac.za/style/sunscholar/certs/PCA-3G3.pem

OR wget http://web.lib.sun.ac.za/style/sunscholar/certs/PCA-3G5.pem

Get the secondary intermediate Symantec CA cert: wget http://web.lib.sun.ac.za/style/sunscholar/certs/ICA-3G3.pem

OR wget http://web.lib.sun.ac.za/style/sunscholar/certs/ICA-3G5.pem

Intermediate CA certs links

For more intermediate CA cert info see the following links: ● http://en.wikipedia.org/wiki/Intermediate_certificate_authorities ● https://en.wikipedia.org/wiki/Certificate_authority ● https://en.wikipedia.org/wiki/Public_key_certificate ● https://en.wikipedia.org/wiki/Web_of_trust Main Links ● https://www.verisign.com/support/verisign-intermediate-ca/secure-site- intermediate/index.html ● http://www.verisign.com/support/roots.html Other Links ● https://knowledge.verisign.com/support/ssl-certificates- support/index?page=content&id=AR1732

● https://knowledge.verisign.com/support/ssl-certificates- support/index?page=content&actp=CROSSLINK&id=AR657

Step 4. Configure Tomcat to use the SSL certs Convert SSL cert to PKCS12 We convert the SSL signed certs, to a PKCS#12 compatible cert. See: http://www.brandonchecketts.com/archives/convert-and-openssl-apache- ssl-certificate-to-a-pkcs12-tomcat See: http://en.wikipedia.org/wiki/PKCS_12 for more info about the PKCS12 file.

To do this become the root user and change to the cert folder, by typing as follows: sudo -i cd /etc/ssl/certs

Type the following to create the PKCS12 security cert that is chained with the Symantec/Verisign intermediate CA certs. openssl pkcs12 -export -certfile PCA-3G5.pem -certfile ICA-3G5.pem -in %hostname%.crt -inkey %hostname%.key -out %hostname%.pkcs12

1. Replace %hostname% with the hostname of the server. 2. You will be asked for a keystore password. 3. Enter it and keep a careful record of it somewhere.

You can check the details of the PKCS12 cert by typing the following: keytool -list -v -storetype pkcs12 -keystore %hostname%.pkcs12

Setup Tomcat "server.xml" to use the converted certificate

Now the Tomcat server has to be told where to find this security key file. Edit the /etc/tomcat7/server.xml file as follows: nano /etc/tomcat7/server.xml

Find the port 8443 connector section. 1. Remove the comments surrounding the section. 2. Change the listening port to 443. 3. Add the following keystore settings. keystoreFile="/etc/ssl/certs/%hostname%.pkcs12" keystoreType="PKCS12" keystorePass="%SecretPassword%" />

1. Replace %SecretPassword% with the password you used when creating the keystore above. 2. And add the %hostname% used when creating the keystore above.

Example "server.xml" secure settings

See full example below using a local PKCS12 keystore cert file with password embedded. Note: Do not replace the connector port settings for insecure port 80 or 8080.

SSL Ciphers Notes:

This is the heart of the secure link, however there is a trade off. Most users do not upgrade browsers regularly therefore if you implement a strong modern cipher suite they will not be able to connect. ● For more details about what cipher suite to use, check the following: ○ https://wiki.mozilla.org/Security/Server_Side_TLS ○ https://wiki.apache.org/tomcat/HowTo/SSLCiphers ○ https://bettercrypto.org ● TLSv1.2 is only available when using JDK 7 and higher. Please see: http://wiki.lib.sun.ac.za/index.php/SUNScholar/Java_Version_7 ● For Tomcat7 change "sslProtocols" to "sslEnabledProtocols". ● To see what ciphers will be used, install sslscan and scan using sslscan --no- failed localhost:443. ● See the links below for more help about Tomcat cipher setup: ○ https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml

○ https://weakdh.org/sysadmin.html ○ https://blog.eveoh.nl/2014/02/tls-ssl-ciphers-pfs-tomcat ○ https://www.sslshopper.com/article-how-to-disable-weak-ciphers-and-ssl-2-in- tomcat.html ○ http://docs.oracle.com/javase/1.5.0/docs/guide/security/jsse/JSSERefGuide.h tml#AppA ○ https://confluence.atlassian.com/display/JIRAKB/Default+SSL+ciphers+too+ weak Step 5. Enable secure XMLUI logins See: https://github.com/DSpace/DSpace/blob/master/dspace/config/dspace.cfg#L1960-L1963 Type the following: su dspace nano $HOME/source/dspace/config/dspace.cfg

Go to the following section of the DSpace config file: # Force all authenticated connections to use SSL, only non-authenticated # connections are allowed over plain http. If set to true, then you need to # ensure that the 'dspace.hostname' parameter is set to the correctly. xmlui.force.ssl = true

Enable logins by changing "xmlui.force.ssl" to true. Step 6. Enable HTTPS by default (Optional) This step is optional, for those who prefer to secure ALL communications with the website. You can enable HTTPS by modifying the "dspace.baseUrl" in the "build.properties" file. Change http to https. See link below. https://github.com/DSpace/DSpace/blob/master/build.properties#L30-L31

Java environment settings for Tomcat webapp server sudo nano /etc/default/tomcat7

After determining how much RAM is installed on your server, it is best practice to use about 50% of the RAM for Java. Check the following for comparison: # You may pass JVM startup parameters to Java here. If unset, the default

# options (-Djava.awt.headless=true -Xmx128m) will be used.

#JAVA_OPTS="-Djava.awt.headless=true -Xmx128m"

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

Setup user permissions sudo adduser tomcat7 dspace sudo adduser dspace tomcat7

Installing DSpace 1. Getting DSpace software DSpace stable release can be got from the DSpace github as below:

The current stable as per the time of this documentation is DSpace 6.3

While in your Linux terminal use the command below

wget https://github.com/DSpace/DSpace/releases/download/dspace-6.3/dspace-6.3-src- release.tar.gz

This will download the DSpace source file into your computer/Server.

2. Unpacking DSpace

tar –xzvf dspace-XXX-src-release.tar.gz the output should be the Dspace-source folder refered to in the terms to note as [dspace-source]

3. Editing DSpace Configuration You are required to create a [dspace-source]/dspace/config/local.cfg file from the provided [dspace-source]/dspace/config/local.cfg.example file

Use the command below please replace [dspace-source] with your source folder true name

Sudo cp [dspace-source]/dspace/config/local.cfg.example [dspace- source]/dspace/config/local.cfg

Edit the file providing the necessary details and do not comment out any value

Note: I am using nano but you could use a text editor of your choice.

Sudo nano [dspace-source]/dspace/config/local.cfg

Sample example below:

# EXAMPLE "local.cfg" for DSpace. # # Any configurations added to this file will automatically OVERRIDE configurations # of the same name in any of the DSpace *.cfg files. This includes overriding # settings in any of these files: # * [dspace]/config/dspace.cfg # * Or any configuration file that is included in 'dspace.cfg' # (See "include = [filepath]" settings near the end of dspace.cfg. # By default, it includes all [dspace]/config/modules/*.cfg files) # # By default, this EXAMPLE file includes a number of commonly overridden configurations. # * ADD configurations by simply copying them into this file from any existing *.cfg file. # * REMOVE configurations by simply commenting them out or deleting them below. # # Any commented out settings in this file are simply ignored. A configuration # will only override another configuration if it has the EXACT SAME key/name. # For example, including "dspace.dir" in this local.cfg will override the # default value of "dspace.dir" in the dspace.cfg file. # Similarly, including "oai.solr.url" in this local.cfg will override the # default value of "oai.solr.url" in the modules/oai.cfg file. #

########################## # SERVER CONFIGURATION # ##########################

# DSpace installation directory. # This is the location where you want to install DSpace. # Windows note: Please remember to use forward slashes for all paths (e.g. C:/dspace) dspace.dir=/dspace

# DSpace host name - should match base URL. Do not include port number dspace.hostname = localhost

# DSpace base host URL. Include port number etc. dspace.baseUrl = http://localhost:8080

# The user interface you will be using for DSpace. Common usage is either xmlui or jspui # Full link your end users will use to access DSpace. In most cases, this will be the baseurl followed by # the context path to the UI you are using. # # Alternatively, you can use a url redirect or deploy the web application under the servlet container root. # In this case, make sure to remove the /${dspace.ui} from the dspace.url property. #dspace.url = ${dspace.baseUrl}/${dspace.ui}

# Name of the site dspace.name = UCU Institutional Repository

# assetstore.dir, look at DSPACE/config/spring/api/bitstore.xml for more options # default is ${dspace.dir}/assetstore, uncomment and modify if you need to use a different path #assetstore.dir = ${dspace.dir}/assetstore assetstore.dir = ${dspace.dir}/assetstore

# Default language for metadata values #default.language = en_US

# Solr server/webapp. # DSpace uses Solr for all search/browse capability (and for usage statistics by default). # The included 'solr' webapp MUST be deployed to Tomcat for DSpace to function. # Usually it will be available via port 8080 and the 'solr' context path. But, # But, you may need to modify this if you are running DSpace on a custom port, etc. solr.server = http://localhost:8080/solr ########################## # DATABASE CONFIGURATION # ########################## # DSpace only supports two database types: PostgreSQL or Oracle

# URL for connecting to database # * Postgres template: jdbc:postgresql://localhost:5432/dspace # * Oracle template: jdbc:oracle:thin:@//localhost:1521/xe db.url = jdbc:postgresql://localhost:5432/dspace

# JDBC Driver # * For Postgres: org.postgresql.Driver # * For Oracle: oracle.jdbc.OracleDriver db.driver = org.postgresql.Driver

# Database Dialect (for Hibernate) # * For Postgres: org.dspace.storage.rdbms.hibernate.postgres.DSpacePostgreSQL82Dialect # * For Oracle: org.hibernate.dialect.Oracle10gDialect db.dialect = org.dspace.storage.rdbms.hibernate.postgres.DSpacePostgreSQL82Dialect

# Database username and password db.username = dspace db.password = *******

# Database Schema name # * For Postgres, this is often "public" (default schema) # * For Oracle, schema is equivalent to the username of your database account, # so this may be set to ${db.username} in most scenarios. db.schema = public

## Connection pool parameters

# Maximum number of DB connections in pool (default = 30) # Maximum time to wait before giving up if all connections in pool are busy (milliseconds) # (default = 5000ms or 5 seconds) #db.maxwait = 5000

# Maximum number of idle connections in pool (-1 = unlimited) # (default = 10) #db.maxidle = 10

####################### # EMAIL CONFIGURATION # #######################

# SMTP mail server (allows DSpace to send email notifications) #mail.server = smtp.example.com

# SMTP mail server authentication username and password (if required) #mail.server.username = myusername #mail.server.password = mypassword

# SMTP mail server alternate port (defaults to 25) #mail.server.port = 25

# From address for mail # All mail from the DSpace site will use this 'from' address #mail.from.address = [email protected]

# When feedback is submitted via the Feedback form, it is sent to this address # Currently limited to one recipient! #feedback.recipient = [email protected]

# General site administration (Webmaster) e-mail #mail.admin = [email protected]

# Recipient for server errors and alerts (defaults to mail.admin) #alert.recipient = ${mail.admin}

# Recipient for new user registration emails (defaults to unspecified)

# Recipient for new user registration emails (defaults to unspecified) #registration.notify =

######################## # HANDLE CONFIGURATION # ######################## # # Canonical Handle URL prefix

# # Items in DSpace receive a unique URL, stored in dc.identifier.uri # after it is generated during the submission process. # # If you register with CNRI's handle service at http://www.handle.net/, # these links can be generated as permalinks using http://hdl.handle.net/ # as canonical prefix. Please make sure to change handle.canonical.prefix # after registering with handle.net by uncommenting one of the following # lines, depending if you prefer to use http or https: # handle.canonical.prefix = http://hdl.handle.net/ # handle.canonical.prefix = https://hdl.handle.net/ # # Note that this will not alter dc.identifer.uri metadata for existing # items (only for subsequent submissions), but it will alter the URL # in JSPUI's 'identifier' message on item record pages for existing items.

# CNRI Handle prefix # (Defaults to a dummy/fake prefix of 123456789) #handle.prefix = 123456789

4. Building DSpace Create the [dspace] installation folder e.g /dspace

Give ownership of [dspace] to the dspace user

sudo chown –R dspace:dspace [dspace]

Give read/write permissions to [dspace] to all users

sudo chmod –R 0777 [dspace]

Open [dspace-source] folder

cd [dspace-source]

While inside [dspace-source] run the command below to build Dspace

Note: don’t build while you are root user mvn -U clean package Time of build completion will depend on your internet speed

5. Installing DSpace After a successful build, you will install using the steps below

Change directory to

cd [dspace-source]/dspace/target/dspace-installer

Then run

sudo ant fresh_install

6. Creating DSpace Super-admin user Stop tomcat sudo service tomcat7 stop

sudo [dspace]/bin/dspace create-administrator Fill in all the details when prompted and keep the credentials a secret. See example activation below. Creating an initial administrator account E-mail address: [email protected] First name: Fredrick Last name: Odongo WARNING: Password will appear on-screen. Password: XXXXXXXX Again to confirm: XXXXXXXX Is the above data correct? (y or n): y Administrator account created

When you are finished fill the form, please start tomcat sudo service tomcat7 start 7. Telling Tomcat where to find Dspace Edit the file /etc/tomcat7/server.xml

Look for this section:

appBase to have the location of [dspace]/webapps

see example below: for dspace installed in /dspace

Restart Tomcat: sudo service tomcat7 restart

8. Testing DSpace In your web browser address bar type:

[your-server-ip]/xmlui or [your-server-ip]/jspui

Replace [your-server-ip] with your Dspace server IP or domain name.

After deciding which theme you want to use between xmlui and jspui

Set it as default using the steps below: cd [dspace]/webapps then for XMLUI sudo ln –s [dspace]/webapps/xmlui ROOT for JSPUI sudo ln –s [dspace]/webapps/jspui ROOT

Essential Directory trees Servlet Engine [Tomcat7] Directories for UCUDIR Tomcat home Tomcat config (Catalina Base)

CATALINA_HOME

[dspace-source] [dspace]

Important directories for backup and restore ● Assetstore – directory will have all the Bitstreams and licenses

− Location: [dspace]/assetstore

● Bin - commands to be used at command line, can always be generated from dspace-source files

Location: [dspace]/bin

● Config – stores configurations for dspace

Location: [dspace]/config

● Handle-server – handle server settings and configurations Location: [dspace]/handle-server  Solr statistics Location: [dspace]/solr

How to configure the Handle server

Registered as handle server

Instructions are available on the following sites

● http://www.handle.net ● http://www.handle.net/prefix.html

Prepare an initial handle request /dspace/bin/dspace make-handle-config /dspace/handle-server Send handle request email Email the file dspace/handle-server/sitebndl.zip to [email protected]

After receiving a reply to go ahead with the configuration from admin, do the following

Edit /dspace/handle-server/config.dct Replaced all mention of 300:0.NA/123456789 or 300:0.NA/YOUR_NAMING_AUTHORITY with the handle of your server.

For example

300:0.NA/123456789

300:0.NA/20.500.11951

Included the following lines in the server_config clause:

"storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin"

File looks like this:

{

"hdl_http_config" = { "bind_address" = "196.43.140.182" "num_threads" = "15" "bind_port" = "8000" "backlog" = "5" "log_accesses" = "no" }

"server_type" = "server" "hdl_udp_config" = { "bind_address" = "196.43.140.182" "num_threads" = "15" "bind_port" = "2641" "log_accesses" = "no" }

"hdl_tcp_config" = { "bind_address" = "196.43.140.182" "num_threads" = "15" "bind_port" = "2641" "backlog" = "5" "log_accesses" = "no" }

"log_save_config" = { "log_save_interval" = "Weekly" }

"no_udp_resolution" = "n" "interfaces" = ( "hdl_udp" "hdl_tcp" "hdl_http" )

"server_config" = { "storage_type" = "CUSTOM" "storage_class" = "org.dspace.handle.HandlePlugin" "server_admins" = ( "300:0.NA/20.500.11951" )

"replication_admins" = ( "300:0.NA/20.500.11951" )

"max_session_time" = "86400000" "this_server_id" = "1" "max_auth_time" = "60000" "backup_admins" = ( "300:0.NA/20.500.11951" )

"case_sensitive" = "no" }

} Update DSpace config file nano /home/dspace/dspace-source/build.properties changed handle.prefix = XXXXXX to handle.prefix = 20.500.11951

Rebuild DSpace Update old handle prefixes to new registered prefixes Using the command below:

/dspace/bin/dspace update-handle-prefix

In case you would like to change a single handle use the command below /dspace/bin/dspace update-handle-prefix 123456789 20.500.11951

Security settings for the handle server

Firewall Ports (mandatory)

Open ports 8000 and 2641 for internet access by the handle server on local server AND on the campus firewall

Ports 8000 and 2641 must be opened to listen via UDP AND TCP to the handle server

To test local handle server is running http://ucudir.ucu.ac.ug:8000/

Configure the Java environment variables for handle server Use the following commands sudo nano /etc/environment Copy and paste the following to the bottom of the file. JAVA_HOME="/usr/lib/jvm/default-java" JAVA_OPTS="-Djava.awt.headless=true -Xmx2048m -Xms1024m -Dfile.encoding=UTF-8"

Increased number of open files available

Opened the following file as follows: sudo nano /etc/security/limits.conf Added the following to the bottom of the file: * hard nofile 65536 * soft nofile 65536

To check the files open parameter use the command below ulimit -n Setup file creation permissions

Sudo nano /dspace/.bashrc

Add the following to the bottom umask 002 Configure handle server to start automatically sudo nano /etc/rc.local Copy and paste the following into a blank space in the file before the "exit" statement: /home/dspace/bin/start-handle-server Checking for correct operation Listening Ports sudo netstat -tlnp | grep 2641 sudo netstat -tlnp | grep 8000

Handle service sudo ps ax | grep handle Handle config sudo ls -l /root/.handle/root_info Handle log nano /dspace/handle-server/error.log Rebuild config /dspace/bin/dspace make-handle-config $HOME/handle-server Start service manually sudo /dspace/bin/start-handle-server

DSpace security policy Setting are found in the file /etc/tomcat7/policy.d/05dspace.policy Policy is set as below: grant codeBase "file:/home/dspace/-" { permission java.security.AllPermission; }; grant codeBase "file:/tmp/-" { permission java.security.AllPermission; };

Detailed steps to Allow Tomcat to listen on ports "80" and "443"

Setup "authbind" for Tomcat enabling "authbind": sudo nano /etc/default/tomcat7 Look for AUTHBIND variable and set it to yes. Should look like below; AUTHBIND=yes Exit the file telling "authbind" the ports that tomcat should listen to sudo touch /etc/authbind/byport/80 sudo touch /etc/authbind/byport/443 sudo chmod 0755 /etc/authbind/byport/80 sudo chmod 0755 /etc/authbind/byport/443 sudo chown tomcat7.tomcat7 /etc/authbind/byport/80 sudo chown tomcat7.tomcat7 /etc/authbind/byport/443

We are not yet finished please continue through the steps below.

To check or confirm the port use the command below cd /etc/authbind/byport ls -l sample output total 0 -rwxr-xr-x 1 tomcat7 tomcat7 0 2011-06-10 18:33 443 -rwxr-xr-x 1 tomcat7 tomcat7 0 2011-06-10 18:33 80

Setup Tomcat to listen on insecure port 80

Now we tell the Tomcat server to listen on the "authbind" ports. Edit the following file. sudo nano /etc/tomcat7/server.xml Find the connector for port 8080 and change it to port 80.

Make sure it looks like the one below

enableLookups="false"

maxConnections="-1"

maxThreads="450"

maxHttpHeaderSize="16384"

connectionTimeout="20000"

URIEncoding="UTF-8"

redirectPort="443" />

If enabled, comment out the AJP 1.3 connector. It is not needed

Save and exit the file.

Themes

Dspace has two xmlui themes to choose from and UCUDIR is using the mirage2 theme which is responsive.

For this documentation, the following steps have been taken to enable Mirage2

Install required Ubuntu software for it to run, see command below; sudo apt-get install git curl maven ruby-compass default-jdk default-jre Enable Github Downloads git config --global url."https://".insteadOf git://

Installing Non-Ubuntu Packaged Software node.js

Use command below: sudo curl -sL https://deb.nodesource.com/setup | sudo bash -

Install nod version manager sudo curl https://raw.githubusercontent.com/creationix/nvm/v0.24.0/install.sh | bash

Install the ruby version manager (rvm) software, by typing the following:

34 sudo curl -sSL https://get.rvm.io | bash -s stable

Install Theme Build Software

Commands below were used sudo -i npm install --no-check-certificate -g bower npm install --no-check-certificate -g grunt npm install --no-check-certificate -g grunt-cli exit

Built Mirage2 Theme using the command below cd /home/dspace/dspace-source then mvn -U clean package -Dmirage2.on=true

Affter installation, the theme is activated by editing the xmlui.xconf The script below was added

Always make sure that the Mirage2 theme is the only active theme and not commented out.

It looks like the sample below:

Get information on customization here: http://wiki.lib.sun.ac.za/index.php?title=SUNScholar/XMLUI_Theme/M2/Customisation

Media Filters (Thumbnails)

Install pre-required Ubuntu software packages using the command below sudo apt-get install imagemagick ghostscript

Edite the dspace.cfg file nano /home/dspace/dspace-source/dspace/config/dspace.cfg

Enable Media filters

Search for following and change to true: webui.browse.thumbnail.show = true webui.item.thumbnail.show = true webui.preview.enabled = true

Configure Dimensions of the thumbnails to # maximum width and height of generated thumbnails thumbnail.maxwidth = 160 thumbnail.maxheight = 160

Filters

Enable filters as follows:

#Names of the enabled MediaFilter or FormatFilter plugins filter.plugins = PDF Text Extractor, HTML Text Extractor, Word Text Extractor, \ PowerPoint Text Extractor, \ Branded Preview JPEG, \ ImageMagick Image Thumbnail, ImageMagick PDF Thumbnail

Names

Assign names for filters as follows:

#Assigned 'human-understandable' names to each filter plugin.named.org.dspace.app.mediafilter.FormatFilter = \ org.dspace.app.mediafilter.PDFFilter = PDF Text Extractor, \ org.dspace.app.mediafilter.HTMLFilter = HTML Text Extractor, \ org.dspace.app.mediafilter.WordFilter = Word Text Extractor, \ org.dspace.app.mediafilter.PowerPointFilter = PowerPoint Text Extractor, \ org.dspace.app.mediafilter.BrandedPreviewJPEGFilter = Branded Preview JPEG, \ org.dspace.app.mediafilter.ImageMagickImageThumbnailFilter = ImageMagick Image Thumbnail, \ org.dspace.app.mediafilter.ImageMagickPdfThumbnailFilter = ImageMagick PDF Thumbnail

Input Formats

Assign MIME file types to media filters as follows:

#Configure each filter's input format(s) filter.org.dspace.app.mediafilter.PDFFilter.inputFormats = Adobe PDF filter.org.dspace.app.mediafilter.HTMLFilter.inputFormats = HTML, Text filter.org.dspace.app.mediafilter.WordFilter.inputFormats = Microsoft Word filter.org.dspace.app.mediafilter.PowerPointFilter.inputFormats = Microsoft Powerpoint, Microsoft Powerpoint XML filter.org.dspace.app.mediafilter.BrandedPreviewJPEGFilter.inputFormats = BMP, GIF, JPEG, image/png filter.org.dspace.app.mediafilter.ImageMagickImageThumbnailFilter.inputFormat s = BMP, GIF, image/png, JPG, TIFF, JPEG, JPEG 2000 filter.org.dspace.app.mediafilter.ImageMagickPdfThumbnailFilter.inputFormats = Adobe PDF

Permissions

Configure media filter permissions. Search for "filter.org.dspace.app.mediafilter.publicPermission" and modify as follows:

#Publicly accessible thumbnails of restricted content. #List the MediaFilter name's that would get publicly accessible permissions #Any media filters not listed will instead inherit the permissions of the parent bitstream filter.org.dspace.app.mediafilter.publicPermission = BrandedPreviewJPEGFilter, ImageMagickImageThumbnailFilter, ImageMagickPdfThumbnailFilter

List Emphasis

Search for xmlui.theme.mirage.item-list.emphasis. There are two options available namely "metadata" or "file", select "file".

See example below.

### Settings for Item lists in Mirage theme ### # What should the emphasis be in the display of item lists? # Possible values : 'file', 'metadata'. If your repository is # used mainly for scientific papers 'metadata' is probably the # best way. If you have a lot of images and other files 'file' # will be the best starting point # (metdata is the default value if this option is not specified) xmlui.theme.mirage.item-list.emphasis = file

Rebuild DSpace Test the media filters /dspace/bin/dspace filter-media -v -i 123456789/29097

Create new thumbnails /dspace/bin/dspace filter-media -v -f -m 1000 -p "ImageMagick PDF Thumbnail" /dspace/bin/dspace filter-media -v -f -m 1000 -p "ImageMagick Image Thumbnail"

SOLR Configuration

Edite the following file:

38 nano /home/dspace/dspace-source/dspace/config/modules/solr-statistics.cfg See example below. #------# #------SOLR STATISTICS CONFIGURATIONS------# #------# # These configs are only used by the SOLR interface/webapp to # # track usage statistics. # #------#

##### Usage Logging ##### # set this to be the port you run the dspace "solr" webapp # on, by default, we are assuming a test configuration with # tomcat still running on port 8080 server = ${solr.server}/statistics

# A comma-separated list that contains the bundles for which the bitstreams will be displayed query.filter.bundles=ORIGINAL

# control solr statistics querying to filter out spider IPs # false by default #query.filter.spiderIp = false

# control solr statistics querying to look at "isBot" field to determine # if record is a bot. true by default. #query.filter.isBot = true

# URLs to download IP addresses of search engine spiders from spiderips.urls = http://iplists.com/google.txt, \ http://iplists.com/inktomi.txt, \ http://iplists.com/lycos.txt, \ http://iplists.com/infoseek.txt, \ http://iplists.com/altavista.txt, \ http://iplists.com/excite.txt, \ http://iplists.com/misc.txt, \ http://iplists.com/non_engines.txt Setting up usage config file Edite the following file: nano /home/dspace/dspace-source/dspace/config/modules/usage-statistics.cfg See example below. # The location for the Geo Database retrieved on update/installation dbfile = ${dspace.dir}/config/GeoLiteCity.dat

# Timeout for the resolver in the DNS lookup # Time in milliseconds, defaults to 200 for backward compatibility # Your system's default is usually set in /etc/resolv.conf and varies # between 2 to 5 seconds, too high a value might result in Solr exhausting # your connection pool resolver.timeout = 1000

# Control if the statistics pages should be only shown to authorized users # If enabled, only the administrators for the DSpaceObject will be able to # view the statistics. # If disabled, anyone with READ permissions on the DSpaceObject will be able # to view the statistics. #View/download statistics authorization.admin.usage=false #Search/search result statistics authorization.admin.search=false #Workflow result statistics authorization.admin.workflow=false

# Enable/disable logging of spiders in solr statistics. # If false, and IP matches an address in spiderips.urls, event is not logged. # If true, event will be logged with the 'isBot' field set to true # (see query.filter.* for query filter options) # Default value is true. logBots = false

Rebuild DSpace Re-indexing statistics

Prepare the "temp" folder. mkdir /dspace/temp chmod 0777 -R dspace/temp

Then run the following script: sudo /dspace/bin/dspace solr-reindex-statistics

Finally enable daily task optimization using cron jobs.

Find sample cron job here and how to setup one here: http://wiki.lib.sun.ac.za/index.php?title=SUNScholar/Daily_Admin/5.X Researcher Identification [ORCID]

ORCID feature in DSpace needs to consult an external database when doing identity lookups ensured that repository server has unrestricted access via ports 80 and 443 to the following web sites: http://pub.orcid.org (For public read access, essential for DSpace to do identification lookups!) https://api.orcid.org (For member read/write access, not needed yet for DSpace, but good to have)

Step 1 - Enable the ORCID authority control plugin

The ORCID authority control plugin is called the SolrAuthorAuthority plugin, perhaps it should have been called ORCIDContributorAuthority.

Edited the dspace.cfg file nano dspace-source/dspace/config/dspace.cfg

Search for ORCID authority control and remove comments to enable. See example below. plugin.named.org.dspace.content.authority.ChoiceAuthority = \ org.dspace.content.authority.SolrAuthority = SolrAuthorAuthority

Step 2 - Enable the DSpace authority control event listener Edited the following file: nano dpsace-source/dspace/config/dspace.cfg Searched for event.dispatcher.default.consumers and ensured the "default" listener also includes "authority". See example below. event.dispatcher.default.consumers = authority, versioning, discovery, eperson, harvester Step 3 - Configure the ORCID authority control plugin Please note: The ORCID authority control plugin is called the SolrAuthorAuthority plugin, perhaps it should have been called ORCIDContributorAuthority. Step 3.1 Edit the following file: nano dspace-source/dspace/config/dspace.cfg

Searche for ORCID based authority control then uncomment the hashes and modify as needed. See example below. solr.authority.server = ${solr.server}/authority choices.plugin.dc.contributor.author = SolrAuthorAuthority choices.presentation.dc.contributor.author = authorLookup authority.controlled.dc.contributor.author = true authority.author.indexer.field.1 = dc.contributor.author choices.plugin.dc.contributor.advisor = SolrAuthorAuthority choices.presentation.dc.contributor.advisor = authorLookup authority.controlled.dc.contributor.advisor = true authority.author.indexer.field.2 = dc.contributor.advisor choices.plugin.dc.contributor.editor = SolrAuthorAuthority choices.presentation.dc.contributor.editor = authorLookup authority.controlled.dc.contributor.editor = true authority.author.indexer.field.3 = dc.contributor.editor

Step 3.2 Update the orcid-authority-services.xml file to add an "advisor" "fieldDefaults" lookup by typing the following: nano dspace-source/dspace/config/spring/api/orcid-authority-services.xml Searche for the fieldDefaults section and add the advisor entry key. See example below.

Step 4 - Rebuild DSpace

Step 5 - Create an ORCID authority index cache After the rebuild, create an authority index cache by running the following script: /dspace/bin/dspace index-authority Note: This may take a long time if there are many authors in the DSpace metadata! Tomcat Security If you have problems running this script, please check if Tomcat security is enabled in /etc/default/tomcat7. Disable security to be able to run the script and then re-enabled security after the script ran. The next step is to see if new items with new authors get an author authority record with Tomcat security enabled. Folder and file permissions/ownership In addition the script requires full permission to the /dspace/dspace/solr folder. To ensure file permissions are adequate, type the following: sudo chmod 0777 -R /home/dspace/solr WARNING: Please consult the following before creating an index cache:

● https://wiki.duraspace.org/display/DSDOC5x/ORCID+Integration#ORCIDIntegration- DifferentpossibleusecasesforIndex-authorityscript for official DSpace notes. ● https://wiki.duraspace.org/display/DSPACE/Authority+Control+of+Metadata+Values for a discussion of the metadata authority control framework.

Step 6 - Maintain ORCID authority index cache The data in a researchers ORCID profile on the ORCID web site may change, for example, if someone marries and changes their surname in their ORCID profile, this information needs to be updated in the local DSpace database. Follow the procedures below to do this on an ad-hoc or regular basis. Step 6.1 - Ad-hoc update Type the following to do an ad-hoc update: sudo [dspace]/bin/dspace dsrun org.dspace.authority.UpdateAuthorities Step 6.2 - Regular update Add the command in the step above to your daily admin routine. Step 6.3 - Export authority records Type the following to export the authority records as a backup. sudo [dspace]/bin/dspace dsrun org.dspace.util.SolrImportExport -a export -- index-name authority

The exported files are in [dspace]/solr-export. Upgrading DSpace. There are two methods: 1. Upgrade and existing Dspace 2. Move data from an old version to a newinstallation Upgrading an existing Dspace Backup your DSpace

Database: pg_dump -U [database-user] -f [backup-file-location] [database-name]

Assetstore:

Backup the directory ([dspace]/assetstore by default, and any other assetstores configured in the [dspace]/config/dspace.cfg "assetstore.dir" and "assetstore.dir.#" settings

Configuration: Backup the entire directory content of [dspace]/config.

Customizations: If you have custom code, such as themes, modifications, or custom scripts, you will want to back them up to a safe location.

Statistics data: what to back up depends on what you were using before: the options are the default SOLR Statistics, deprecated Elasticsearch Usage Statistics, or the legacy statistics. Legacy stats utilizes the dspace.log files, Elasticsearch stats stores data in [dspace]/elasticsearch, SOLR Statistics stores data in [dspace]/solr/statistics. A simple copy of the data directory should give you a point of recovery, should something go wrong in the update process. We can't stress this enough, your users depend on these statistics more than you realize. You need a backup. Update Prerequisite Software (as necessary)

DSpace 6.x requires the following versions of prerequisite software:

● Java 7 or 8 (Oracle or OpenJDK) ● Apache Maven 3.0.5 or above ● Apache Ant 1.8 or above ● Database o PostgreSQL 9.4 or above (with pgcrypto installed), OR o Oracle 10g or above ● Tomcat 7 or above

Upgrade Steps

1. Ensure your database is compatible 2. Download DSpace 3. XMLUI modifications: [dspace-source]/dspace/modules/xmlui/src/main/webapp/

Config modifications: [dspace]/config

4. Build DSpace cd [dspace-source]/dspace/ mvn -U clean package note: for Mirage2 use- mvn -U clean package -Dmirage2.on=true 5. Replace your old build.properties file with a local.cfg 6. Stop Tomcat (or servlet container) 7. Update DSpace Installation cd [dspace-source]/dspace/target/dspace-installer ant update 8. Update your DSpace Configurations and/or move them to local.cfg

9. Decide which DSpace Web Applications you want to install. DSpace comes with a variety of web applications (in [dspace]/webapps), each of which provides a different "interface" to your DSpace. Which ones you install is up to you, but there are a few that we highly recommend (see below): 1. "xmlui" = This is the XML-based User Interface, based on Apache Cocoon. It comes with a variety of out-of-the-box themes, including Mirage 1 (the default) and Mirage 2 (based on Bootstrap).Between the "xmlui" and "jspui", you likely only need to choose one. 2. "jspui" = This is the JSPUI-based User Interface, which is based on Bootstrap. Between the "xmlui" and "jspui", you likely only need to choose one. 3. "solr" (required) = This is Apache Solr web application, which is used by the "xmlui" and "jspui" (for search & browse functionality), as well as the OAI-PMH interface. It must be installed in support of either UI. 4. "oai" = This is the DSpace OAI interface. It allows for metadata and bitstream (content-file) harvesting, supporting OAI-PMH (Protocol for Metadata Harvest) and OAI-ORE (Object Reuse and Exchange) protocols 5. "rest" = This is the DSpace REST API 6. "sword" = This is the DSpace SWORDv1 interface. More info on SWORD protocol and its usage. 7. "swordv2" = this is the DSpace SWORDv2 interface. More info on SWORD protocol and its usage. 8. "rdf" = This is the DSpace RDF interface supporting Linked (Open) Data.

10. Deploy DSpace Web Applications

If necessary, copy the web applications from your [dspace]/webapps directory to the subdirectory of your servlet container (e.g. Tomcat): cp -R [dspace]/webapps/* [tomcat]/webapps/

11. Upgrade your database Check database compatibility

[dspace]/bin/dspace database info # Look for a line at the bottom that says something like: # "Your database looks to be compatible with DSpace version ___" Advisable Run database sequence # Example for a PostgreSQL database named "dspace", and a user account n amed "dspace" # psql -U dspace -f [dspace]/etc/postgres/update-sequences.sql dspace

Then, you can upgrade your DSpace database to the latest version of DSpace [dspace]/bin/dspace database migrate

Manually run these registry updates (they will not harm existing registry contents) as follows: [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/dcterms-types.xml [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/dublin-core-types.xml [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/eperson-types.xml [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/local-types.xml [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/sword-metadata.xml [dspace]/bin/dspace registry-loader -metadata [dspace]/config/registries/workflow-types.xml

12. Reindex your solr stats /dspace/bin/dspace index-discovery –b Migrating to a new installation. BACKUP YOUR CONTENT of the old dspace and do a databse dump For contents to backup refar to the upgrading an exisiting DSpace step1 Log onto to the new dspace server backup and do the following: 1. Delete the new dspace database [DROP DATABASE yourDB]

incase DB fails to delete, follow this: query the pg_stat_activity view to find what activities are taking place against the database: SELECT * FROM pg_stat_activity WHERE datname = 'yourDB'; Then terminate the connection to the Database by using the following statement: SELECT pg_terminate_backend (pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'testdb1'; Then DROP DATABASE yourDB 2. Create DB dspace createdb --username=postgres --owner=dspace --encoding=UNICODE dspace; psql --username=postgres dspace -c "CREATE EXTENSION pgcrypto;" 3. push dump into dspace database psql -U dspace dspace < dspace.dump 4. upgrade your DSpace database to the latest version of DSpace [dspace]/bin/dspace database migrate 5. optionally verify whether DSpace correctly detects the version of your DSpace database [dspace]/bin/dspace database info 6. Turn on tomcat service 7. Reindex /dspace/bin/dspace index-discovery -b