DSpace 8.0 marks a significant milestone in the evolution of the widely used open-source repository platform, introducing a host of new features, technical enhancements, and updates aimed at improving performance, usability, and adaptability. This release emphasizes major upgrades, such as adopting Java 17 and Tomcat 10 to support Jakarta EE 9+, ensuring that the platform remains at the cutting edge of technology standards. Notably, DSpace 8.0 introduces the ability to configure item submission processes at the community level, a beta version of Administrator Reports, and an embedded Tomcat option for running the DSpace backend, enhancing its flexibility and ease of deployment.
The release rolls out substantial changes to its REST API and backend infrastructure, including implementing the COAR Notify protocol, which significantly enhances data quality through improved data correction services. Breaking changes, such as the requirement for newer versions of Java and Node and the migration of custom code to “Jakarta.*” dependencies, also form a crucial part of this update, requiring attention during upgrades.
Designed to enhance user experience and streamline repository management, DSpace 8.0 offers robust solutions for academic institutions, libraries, and researchers looking to manage and disseminate digital content effectively. For those looking to upgrade or install the new version, detailed guidance is provided through DSpace’s comprehensive documentation and community support channels.
DSpace 8.0 (8x) Installation Manual
Welcome to the comprehensive installation manual for DSpace 8.0, designed to guide you through the setup and configuration of one of the most advanced open-source repository platforms available today. This manual aims to provide clear and detailed steps to ensure a smooth and successful installation of DSpace 8.0, whether upgrading from a previous version or setting it up for the first time.
DSpace 8.0 introduces new features and updates, including enhanced performance capabilities, improved user interface options, and significant backend advancements. With support for the latest Java and Tomcat versions, this release ensures compatibility with current technology standards. This manual covers all the essential components and procedures, from configuring item submission processes at the community level to utilizing the new embedded Tomcat feature.
Step 1: Configure the Desktop Environment
- It is recommended that Ubuntu be used for a successful installation of DSpace 8.0. This guide is based on tests conducted with Ubuntu 23.04.
- Ensure that you install Linux using the username “dspace”. If a different username is utilized, necessary adjustments should be made to the username specified in this manual.
Step 2: Establish Root User Credentials- To proceed with the installation on your local Linux server, establish a root user password if you haven’t set one up already. Open your terminal and execute the following command to create or update the root password (new users should maintain a consistent password throughout the setup):
sudo -i passwd #Enter your password >>> Now update the local server. sudo apt update sudo apt upgrade -y >>> Now login as a root user su #Input your root password when prompted.
DSpace 8.0 Backend Installation
The installation of the DSpace 8.0 backend represents a pivotal step for institutions aiming to manage and disseminate digital content effectively using this advanced repository platform. This release includes significant upgrades, such as support for Jakarta EE 9+ and the latest versions of Java and Tomcat, which are crucial for ensuring compatibility and performance. The backend installation process is streamlined to accommodate various configurations, including standalone setups with an embedded Tomcat server. This guide will walk you through the necessary steps to establish a robust DSpace 8.0 backend, ensuring your repository’s technical foundation is solid and future-proof.
Step 3: Install Java JDK (v.17):
sudo apt install default-jdk #To check the Java version we already installed java -version #Now you need to set Java variables in your local computer: cd /etc sudo nano environment # Now add JAVA_HOME="/usr/lib/jvm/java-17-openjdk-amd64" >>> Save this #Now you need to source this file with the Java Home directory: For this run: source /etc/environment # Now check if the Java home is properly working or not: echo $JAVA_HOME
Step 4: Install Apache Maven (3.8.x or above)
DSpace uses Maven to simplify the complex Java-based application’s installation process by managing dependencies, ensuring compatibility, and streamlining the configuration process.
sudo apt install maven #Check Maven version mvn -v
Step 5: Install Apache ANT
Apache Ant is integral to deploying and managing DSpace 8.0, a powerful and versatile build automation tool. It facilitates the compilation of Java sources, resolution of dependencies, and packaging of deployable artifacts. Ant’s XML-based configuration approach allows for precise control over the build process, ensuring that all components of DSpace are compiled and configured correctly. This makes Apache Ant essential for the seamless assembly and maintenance of the DSpace 8.0 backend, accommodating the platform’s updated requirements, such as compatibility with Jakarta EE 9+ and the latest Java environments. For administrators and developers working with DSpace, understanding and utilizing Apache Ant can significantly streamline their digital repository systems’ setup and update processes.
apt install ant
Step 6. Install PostgreSQL
PostgreSQL is the recommended database management system for DSpace 8.0, offering robust support for complex queries, full-text search, and transactional integrity essential for managing large volumes of digital assets efficiently. As an open-source RDBMS, PostgreSQL ensures that DSpace installations are scalable, reliable, and capable of handling extensive metadata and user loads. Integrating PostgreSQL with DSpace 8.0 facilitates advanced features like detailed logging, sophisticated access controls, and the ability to handle multiple concurrent sessions effectively. This compatibility not only enhances the performance and stability of the repository but also provides administrators with powerful tools for data management and retrieval. For those setting up DSpace 8.0, configuring PostgreSQL properly is a crucial step that involves setting up schemas, roles, and permissions to align with the security and operational requirements of the institution.
sudo apt install postgresql postgresql-client postgresql-contrib
Check the installed PostgreSQL version here. I have version 15 installed here. If you have another version installed, change the version using the following command.
>>>After successful installation, you need to start the database server using the following: sudo pg_ctlcluster 15 main start >>>Now you can check the status of your PostgreSQL Server sudo systemctl status postgresql >>>To exit, type (from the keyboard) q >>>Create a new Postgres user: sudo groups postgres >>>Add a new password in Postgres sudo passwd postgres >>>Enter password >>>Enter your password here >>>Login as postgres user: su postgres >>>Now check if your server is UTF8 enabled or not: psql -c "SHOW SERVER_ENCODING" >>>If yes, then you do not need to configure it. By default, it is automatically enabled. Now exit from the exit >>>Now you must allow the TCP/IP connections to access the database server. cd /etc/postgresql/15/main sudo nano postgresql.conf
In this file, find:
# - Connection Settings - #listen_addresses = 'localhost' # what IP address(es) to listen on;
Delete # Change it to:
listen_addresses = 'localhost' # what IP address(es) to listen on;
>>>Then, tighten up security a bit by editing pg_hba.conf sudo nano pg_hba.conf >>>Now add host access IP configuration here host dspace dspace 127.0.0.1 255.255.255.255 md5
>>>Now save the edited file and restart PostgreSQL sudo systemctl restart postgresql >>>Check postgress systemstatus: systemctl status postgresql >>>To exit, type q from your keyboard q
Step 7: Apache Solr Installation
Installing Apache Solr for DSpace 8.0 is a critical step to enhance the platform’s search capabilities, allowing for robust indexing and fast retrieval of repository content. Solr serves as the search engine layer in DSpace, indexing metadata and full-text content to facilitate complex search functionalities across the repository. The installation involves setting up Solr on a servlet container like Tomcat, which DSpace uses to run the search service. This setup includes configuring the Solr cores according to DSpace requirements predefined in the DSpace installation files. Proper configuration ensures that Solr can efficiently handle the search operations required by DSpace, including faceted search, full-text search, and filtering. It is important for administrators to follow the specific guidelines provided in the DSpace documentation to integrate Solr seamlessly with DSpace 8.0, ensuring optimal performance and reliability of the search functions.
You can download Apache Solr from: https://solr.apache.org/downloads.html. We recommend using Solr 8.11.3 for DSpace 8.0
Copy link from Binary releases: [PGP]
>>>Now open the opt directory, and download Solr cd /opt sudo wget https://www.apache.org/dyn/closer.lua/lucene/solr/8.11.3/solr-8.11.3.tgz >>>Extract solr sudo tar xvf solr-8.11.3.tgz >>>Give the ownership to the dspace user: sudo chown -R dspace:dspace solr-8.11.3 >>>Now go through the Solr directory cd solr-8.11.3 cd bin cd pwd exit
Return to the home directory as a normal user (not a root user) and find the #.profile directory. You need to configure the solr to start automatically every time after starting the server.
>>>To find the #.profile directory ls -la >>>Now edit #.profile directory sudo nano .profile >>>Past this line & save to start Solr automatically after restarting or starting your server every time. /opt/solr-8.11.3/bin/solr start
To run Solr (Don’t start Solr as a root user.)
/opt/solr-8.6.1/bin/solr start
Check Solr status on your browser: http://localhost:8983/ , http://local-ip:8983
Step 8. Install Apache Tomcat (tomcat10)
Installing Apache Tomcat (specifically Tomcat 10) for DSpace 8.0 is essential in setting up a reliable server environment for your digital repository. Apache Tomcat acts as a servlet container that hosts the Java servlets and JSPs comprising the DSpace web layer. Tomcat 10, compatible with Jakarta EE 9 and above, is crucial due to its support for the latest Java technologies, which DSpace 8.0 utilizes. During installation, careful attention must be paid to configuration settings such as memory allocation, security settings, and the management of Tomcat users, which are critical for DSpace’s optimal performance and security. Setting up Tomcat involves downloading the correct version, installing it on your server, and configuring it to work with DSpace by setting environment variables and modifying XML configuration files as specified in the DSpace installation guide. Proper installation ensures that DSpace can efficiently handle user requests and operate securely under various load conditions.
We have some configuration here.
>>>Login as a root user su Install tomcat10 apt install tomcat10
Check the tomcat10 status on your browser: http://localhost/8080, http://local-ip/8080
On Debian systems, you also need to modify or override the “tomcat.service” file to specify the DSpace installation directory in the list of ReadWritePaths.
cd /lib/systemd/system sudo nano tomcat10.service >>>Under the # Security option, add this line and save. ReadWritePaths=/dspace/
>>>Now create a dspace installation directory cd sudo mkdir /dspace >>>Give the dspace user full read and write permission to /dspace directory sudo chown -R dspace:dspace /dspace/
You need to ensure that Tomcat10
- a) has enough memory to run DSpace, and
- b) uses UTF-8 as its default file encoding for international character support.
So ensure in your startup scripts (etc) that the following environment variable is set: JAVA_OPTS=”-Xmx512M -Xms64M -Dfile.encoding=UTF-8″
sudo nano /etc/environment >>>add JAVA_OPTS="-Xmx512M -Xms64M -Dfile.encoding=UTF-8" >>>Source it source /etc/environment echo $JAVA_OPTS
Next: You also need to alter Tomcat’s default configuration to support searching and browsing of multi-byte UTF-8 correctly. You need to add a configuration option to the <Connector> element in [tomcat]/config/server.xml: URIEncoding=”UTF-8″ e.g. if you’re using the default Tomcat config, it should read.
cd /etc/tomcat10/ sudo nano server.xml
Now add this line between <Connector port=”8080″ protocol=”HTTP/1.1″ /> [Make sure there is no space between the line. Instead of using space, use a tab. Otherwise, the system will fail to restart again.]
<Connector port="8080" protocol="HTTP/1.1" minSpareThreads="25" enableLookups="false" redirectPort="8443" connectionTimeout="20000" disableUploadTimeout="true" URIEncoding="UTF-8"/>
Restart Tomcat10
sudo systemctl daemon-reload sudo systemctl restart tomcat10.service
Step 9. Install Git
Currently, there is a known bug in DSpace where a third-party Maven Module expects git to be available (in order to support the ./dspace version command-line tool).
sudo apt install git
Step 10: DSpace 8.0 Backend Installation
Installing the DSpace 8.0 backend is a comprehensive process that involves setting up the essential components necessary for the repository’s operation. This includes the installation of PostgreSQL for database management, Apache Solr for search functionality, and the DSpace application itself which handles the core repository functions. This step is performed on a dedicated server or virtual machine, where these components must be correctly integrated and configured to ensure they function together seamlessly. The successful installation of the backend is fundamental to the repository, supporting the storage, indexing, and retrieval of digital content, as well as providing a web interface for administrative and user access.
>>>Create a new directory called build. cd sudo mkdir /build >>>Give the directory full control to dspace user. sudo chown -R dspace:dspace /build cd /build >>>Download Dspace 8.0 sudo wget https://github.com/Dspace/Dspace/archive/refs/tags/dspace-8.0.zip >>>Unzip downloaded files sudo unzip dspace-8.0.zip >>>Go to unzipped folder cd DSpace-dspace-8.0/
It’s time for the Postgres database setup.
Give the Postgres user a new password.
su postgres >Enter password.****** (Password should be same as the root user.....)
Create a dspace database user (this user can have any name, but we’ll assume you name it “dspace”). This is entirely separate from the dspace operating-system user created above.
createuser --username=postgres --no-superuser --pwprompt dspace >Enter Password......
Create a dspace database owned by the dspace PostgreSQL user. Similar to the previous step, this can only be done by a “superuser” account in PostgreSQL (e.g. postgres)
createdb --username=postgres --owner=dspace --encoding=UNICODE dspace
Finally, you MUST enable the pgcrypto extension on your new dspace database. Again, this can only be enabled by a “superuser” account (e.g. postgres)
psql dspace -c "CREATE EXTENSION pgcrypto;"
Exit from the PostgreSQL user
exit
Initial Configuration (local.cfg): Create your own [dspace-source]/dspace/config/local.cfg configuration file. You may wish to copy the provided [dspace-source]/dspace/config/local.cfg.EXAMPLE. This local.cfg file can be used to store any configuration changes you wish to make that are local to your installation.
>>>Go to the dspace build directory cd /build/DSpace-dspace-8.0/dspace/config >>>Copy the local.cfg.Example file to local.cfg cp local.cfg.EXAMPLE local.cfg >>>Edit the local.cfg file sudo nano local.cfg >>>Change this following settings dspace.dir=/dspace >>>Name of the site dspace.name = <Enter the name of your Repository here> >>> Remove # from default.language = en_US >>> Remove # from solr.server = http://localhost:8983/solr >>> Change your database password here. db.username = dspace db.password = [Your Password/smae as PostgreSQL db]
Build the Installation Package
Open DSpace source directory and build the installation packages
cd /build/DSpace-dspace-8.0 mvn package
Completing the DSpace installation build process will take 10-30 minutes.
Install DSpace Backend:
Go to the dspace installer directory & install DSpace to /dspace directory.
cd /build/DSpace-dspace-8.0/dspace/target/dspace-installer/ ant fresh_install
If it failed, please check your database password and re-run ant fresh installation.
Dspace Installation files will be saved at
cd /dspace/ ls
Initialize your Database: While this step is optional (as the DSpace database should auto-initialize itself on the first startup), it’s always good to verify one last time that your database connection is working correctly. To initialize the database, run the following:
cd /dspace/bin/ ./dspace database migrate
This process will take a few moments.
Step 11: Deploy Server web application
Copy all the web applications to Tomcat10
sudo cp -R /dspace/webapps/* /var/lib/tomcat10/webapps* >>>Check if the files are copied or not ls -la /var/lib/tomcat10/webapps >>>Now give the tomcat-users full permission to dspace backend directory sudo chown -R tomcat:tomcat /dspace/ sudo chown -R tomcat:tomcat /dspace/webapp
Restart tomcat10 again
sudo systemctl restart tomcat10.service sudo systemctl daemon-reload
Now visit tomcat URL localhost:8080/server/; It will show
If not working:
>>>Give the dspace user full read and write permission to /dspace directory sudo chown -R dspace:dspace /dspace/ >>>Restart tomcat10 again sudo systemctl restart tomcat10.service sudo systemctl daemon-reload
Now visit tomcat URL localhost:8080/server/; It will show
Copy Solr cores: DSpace installation creates a set of four empty Solr cores already configured. We need to copy those on the Solr configsets directory.
cp -R /dspace/solr/* /opt/solr-8.11.3/server/solr/configsets >>>Give the dspace users ownership to the Solr directory sudo chown -R dspace:dspace /opt/solr-8.11.3 >>>Restart Solr as a normal dspace user (not as a root user) cd exit /opt/solr-8.11.3/bin/solr restart
The new 4 core modules will be available at the Solr directory: (Authority, oai, search, and statistics)
Solr URL: http://localhost:8983/
Step12: Create an Administrator Account:Create an initial administrator account from the command line.
Login as a root user and run this command to create a new dspace administration account
su /dspace/bin/dspace create-administrator >Enter email: >First name: >Last Name: >Password: [Any Password] >>>Restart Tomcat10 sudo systemctl restart tomcat10.service
Now run http://localhost:8080/server/, localhost:8080/server/oai/request?verb=Identify to see if the backend server works perfectly.
Installing the DSpace 8 Frontend (User Interface)
Installing the DSpace 8.0 Frontend, or the User Interface (UI), is a pivotal step in creating an accessible and interactive environment for users of the DSpace repository system. The frontend installation involves deploying the DSpace user interface, typically developed using Angular, which communicates with the backend server via RESTful APIs. This setup ensures users have a responsive and intuitive interface for accessing and managing digital content. To install the frontend, administrators must ensure that their server meets the required software prerequisites, including specific versions of Node.js and Angular. The process involves downloading the latest frontend release, configuring environment settings, and compiling the UI components. It’s crucial to carefully follow the official DSpace installation guide to align the frontend with the backend configurations, ensuring seamless integration and optimal performance of the entire system.
Step 1: Installing Node
Open the home directory
su cd pwd wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
Now close and restart your terminal and run this command as a root user ((v18.x or v20.x)
exit >>> exit from the root user exit >>> exit from the terminal >>> Open new terminal and login as a root user su >>> See the list of NVM versions available nvm ls-remote >>> Install NVM 18 nvm install 18 >>> Check the version installed node -v
Step 2: Install yarn
Installing Yarn is an important step in setting up the DSpace 8.0 frontend, particularly if the user interface leverages technologies such as Node.js and Angular, which Yarn helps manage more efficiently. Yarn is a fast, reliable, and secure dependency management tool that facilitates the installation, upgrading, and configuration of software packages required for developing and maintaining the DSpace UI. To install Yarn, ensure Node.js is already installed on your system, as Yarn depends on it. The installation typically involves downloading Yarn from its official website or via package managers like npm. Once installed, Yarn can manage project dependencies specified in the package.json DSpace project file, streamlining the build process and ensuring consistency across development environments. Proper installation and configuration of Yarn can significantly enhance the performance and reliability of the DSpace frontend development process.
npm install --global yarn npm install --global pm2
Step 3: Frontend Installation
Go: https://github.com/DSpace/dspace-angular/releases
Copy the Latest Dspace Angular source link as a zip file.
>>>Open build directory
cd /build
>>>Download DSpace Angular Frontend
wget https://github.com/DSpace/dspace-angular/archive/refs/tags/dspace-8.0.zip
>>> Unzip DSpace Angular
unzip dspace-8.0.zip
>>> Remove dspace-7.5.zip from build directory
rm dspace-8.0.zip
>>> Open DSpace Angular directory:
cd dspace-angular-dspace-8.0/
>>> Install the local dependencies
yarn install
>>> It will take a few minuts (5-10 Min. Based on your internet speed)
Step 4: Build/Compile: Build the User Interface for Production. This builds source code (under [dspace-angular]/src/) to create a compiled version of the User Interface in the [dspace-angular]/dist folder. This /dist folder is what we will deploy & run to start the UI.
cd config/
>>> Copy config.example.yml as config.prod.yml
cp config.example.yml config.prod.yml
>>> Edit the config.prod.yml
nano config.prod.yml
>>> Change the # "rest:" settings as followings, and save
ssl : false
host : localhost
port: 8080
>>>Now run this command to buld your DSpace Frontend for production
yarn run build:prod
Step 5: Start up the User Interface
You must create a PM2 JSON configuration file to run the User Interface. This file can be named anything & placed where ever you like, but we recommend you save it to your deployment directory (e.g. [dspace-ui-deploy]/dspace-ui.json).
cd /build/dspace-angular-dspace-8.0/ >>>Create dspace-ui.json file nano dspace-ui.json >>> Copy and past this configration settings, and save it.
| {
“apps”: [ { “name”: “dspace-ui”, “cwd”: “/build/dspace-angular-dspace-8.0”, “script”: “dist/server/main.js”, “instances”: “max”, “exec_mode”: “cluster”, “env”: { “NODE_ENV”: “production” } } ] } |
Now, start the application (dspace-ui.json) using PM2 using the configuration file you created in the previous step.
pm2 restart /build/dspace-angular-dspace-8.0/dspace-ui.json
Now you can access the DSpace Angular user interface at http://localhost:4000
Happy Browsing!