Try out DSpace 7

Overview

DSpace 7 brings to DSpace a single, modern user interface and REST API and integrates current technological standards and best practices. This new UI combines with the existing core backend of DSpace 6, resulting in a lean, responsive, next-generation repository.

The preview release provides a first look at many of the new features that make DSpace 7 the largest development effort in the history of the software:

• New Angular UI that is modern, responsive, and built using a Bootstrap theme for easy customization. See demo site at https://dspace7-demo.atmire.com/
• A completely redesigned REST API that is self-documenting and human browsable. See demo site at https://dspace7.4science.cloud/server/ 
• Redesigned submissions and workflows featuring a one page submission process with a drag-and-drop interface, and automatic metadata extraction from common formats like PDFs.
• Configurable entities, an optional new item type inspired by the DSpace-CRIS project that allows for complex linked relationships between items. DSpace 7 will include the option to implement this feature for two use cases popular with the DSpace community:
• Journal Hierarchy: create and link objects for a Journal, Volume, Issue, Article, and Author
• Faculty & Organizational Units: a lightweight, CRIS-like option to represent Projects, Faculty, Department/Unit, Publication, etc.
• A deep-dive into Configurable Entities can be found in the DSpace 7 Configurable Entities early documentation (Google Doc)

Configurable entities help to better align DSpace with Next Generation Repository recommendations related to Identifiers as well as alignment with OpenAIRE v4.

DSpace 7 builds on DSpace 6 to create a modern and future-focused repository. The backend restructuring from DSpace 6 is retained and combined with the features above to create a powerful repository designed to address current user needs and plan for future standards.  

DSpace 7 is the first version of DSpace to be developed using test-driven development practices designed to identify and address issues earlier in the development process and lead to more stable releases. It is also the first release to use a working group model for decisions related to design and development.

Try it out using the Demo Site

If you want to quickly test out the DSpace 7 Preview Release, you may do so using our demo site.

• DSpace 7 User Interface Demo: https://dspace7-demo.atmire.com/ (Login: dspacedemo+admin@gmail.com , Password: dspace)
• DSpace 7 REST API Demo: https://dspace7.4science.cloud/server/ (Login: dspacedemo+admin@gmail.com , Password: dspace)
  • REST Contract / Documentation is available at: https://github.com/DSpace/Rest7Contract/blob/master/README.md

Keep in mind, our User Interface Demo uses the REST API Demo as the backend.  So, any content created (by anyone) will immediately appear in both locations.

Installation

Currently, we offer three different ways to install / run DSpace 7 locally.  The route you choose may depend on exactly what you'd like to try out.  Choose ONE of the following:

1. Install via Docker (Recommended for most)- This is the easiest/quickest way to get everything running locally (no matter your technical skills).  We even have a script to automatically load some test data and test accounts into your Docker instance.
2. Install the User Interface only, while using the demo REST API backend - This is the easiest way to try out just the User Interface locally.  Keep in mind, by default, the User Interface will be installed to use our DSpace 7 REST API Demo as a backend.  Therefore, you will be interacting with the content on that demo site and will need to use the login information for the demo site (see above)
3. Install both the User Interface and REST API locally (bring your own test content).  This is a fully manual local installation. Keep in mind this installation process is may still change slightly before the final 7.0 release.

Install via Docker

Running DSpace 7 via Docker allows you to quickly & easily install and start up all the "parts" of DSpace (database, Solr index, REST API, user interface) without having to install them all yourself.  This will work on any operating system (Windows 10, Mac OS, or Linux). 

1. First, install the necessary prerequisites. You will just need to install three things: Docker Desktop (to run Docker), Git (to access our shared Docker compose files) and finally download those shared Docker compose files.
   1. Instructions for Windows 10
   2. Instructions for Mac OS
   3. Instructions for Linux 
2. Next, using Git, download (clone) the DSpace Angular UI codebase & move into that codebase directory

   # Download the UI codebase
   git clone git@github.com:DSpace/dspace-angular.git
   # Move into the created codebase directory
   cd dspace-angular

3. Using the Docker instructions in that codebase, start up both the DSpace 7 REST API and Angular UI via Docker

   1. First, pull down the latest version of the Docker images:  

      docker-compose -f docker/docker-compose.yml pull

   2. Optionally, you can choose to locally rebuild the Angular UI (This is only needed, if you want to try out local changes/customizations to that Angular UI. Otherwise, if you just want to run the default Angular UI, you can skip this step entirely.): 

      docker-compose -f docker/docker-compose.yml build

   3. Finally, start up both the Angular UI and REST API via Docker: 

      docker-compose -p d7 -f docker/docker-compose.yml -f docker/docker-compose-rest.yml up -d

      1. If you'd like to monitor the startup process, you can "tail" the logs as follows:  docker-compose -p d7 logs -f
      2. If anything goes wrong, occasionally a simple restart of the images will resolve it.  Just do a "down" followed by an "up -d" again.
4. Next, optionally, you can add test data to your Docker instance. We have two sets of test data available depending on what you want to test out. CHOOSE ONE.

   1. [Option #1: Use AIP test data] We have a set of AIP (Archival Information Package) data which was exported from a DSpace 6.x instance. This test data is good to get a quick feel for the changes in DSpace 7 compared to DSpace 6.  It's also the easiest to quickly import as we have an ingest script written for Docker using the "dspace-cli" container. Just run: 

      docker-compose -p d7 -f docker/cli.yml -f ./docker/cli.ingest.yml run --rm dspace-cli

   2. [Option #2: Use a database dump of Entities test data] Alternatively, if you'd like to instead test the new Configurable Entities features, we have a separate database dump which provides Entity test data.  (This test data is not yet available in AIP format).  Here's how you'd switch your Docker instance to using the Configurable Entities test data

      1. First, you unfortunately need to completely shut down any running volumes and remove them. We will be replacing them with a database dump of Entity test data.

         # Shut down the running containers
         docker-compose -p d7 -f docker/docker-compose.yml -f docker/docker-compose-rest.yml down
         
         # Remove any existing volumes
         docker volume rm $(docker volume ls -q)

      2. Now, let's recreate those containers with the Configurable Entities test data included:

         # NOTE: the `db.entities.yml` here will startup a database image with Entities test data included (from a database dump)
         docker-compose -p d7 -f docker/docker-compose.yml -f docker/docker-compose-rest.yml -f docker/db.entities.yml up -d
         
         # Once started, also load up the Entities test "assetstore" (files) & trigger a reindex
         docker-compose -p d7 -f docker/cli.yml -f docker/cli.assetstore.yml run --rm dspace-cli

5. Finally, in order to have an initial login, let's create an initial Administrator using the "dspace-cli" container:

   # This example creates an Admin user with email "test@test.edu" and password "admin"
   docker-compose -p d7 -f docker/cli.yml run --rm dspace-cli create-administrator -e test@test.edu -f admin -l user -p admin -c en

6. After a few minutes, you should have a full local installation of DSpace 7 Preview (with test data).
   1. User Interface: http://localhost:3000/
   2. REST API: http://localhost:8080/server/ 
   3. Admin Login: (whatever login you setup via the "dspace-cli" command above)
7. Objects/Pages of interest (within the test data):
   1. Journal Example represents a journal with journal volumes, issues and articles, as detailed in the Configurable Entities Design.
   2. Publications Example contains publications which contain a combination of plain-text authors and related author entities. It also contains relations to Research Projects and Organizational Units, as detailed in the Configurable Entities design. Navigating to e.g. a Person will reveal their relations to Publications, Research Projects and Organizational Units.
   3. Submission/Workflow functionality can be tested using one of the collections in this community where the workflow is enabled. You can use the accounts mentioned above to perform the submission and workflow steps. The admin account can perform the submission and all workflow steps as well.
   4. Once logged in, MyDSpace functionality is found in the user menu (upper right).  Submissions can be started from that page, or via the "New → Item" admin menu (if logged in as an Admin).

8. Once you are done testing, you can stop Docker and clean up the data (deleting the volumes). 

   # Shut down the running containers
   docker-compose -p d7 -f docker/docker-compose.yml -f docker/docker-compose-rest.yml down
   
   # Remove all volumes, images, etc (This removes all the existing data and images)
   docker system prune --volumes

Install the User Interface only

Running only the DSpace 7 user interface can be done quickly & easily on any operating system (Windows, Mac OS, or Linux).  By default, the installed user interface will use the DSpace 7 REST API Demo (https://dspace7.4science.cloud/server/) as its backend.  This means that you will immediately see test data (from that demo site) and be able to interact with it.  However, you will need to authenticate using the REST API Demo account. Any changes you make will also obviously appear on that shared REST API Demo site.

1. First, you will need to install the necessary prerequisites.
   1. Git is required.  If you do not already have it installed (try running git version at your command line), you can install it via https://git-scm.com/downloads (or via your local package manager tools for Linux or Mac OS)
   2. Node.js (v8.x or above) is required. Installing the latest LTS (Long Term Support) version, currently 10.x, is perfectly fine.
      1. NPM (v5.x or above) is required.  Don't worry, this gets installed with Node.js though, so you don't need to do anything extra here.
   3. Yarn (v1.x or above) package manage.  Just install the latest stable version (currently 1.16.x).
2. Then, download our "dspace-angular" application (which is the DSpace 7 user interface) and run it.  All you should need to do is the steps in the "Quick Start" at: https://github.com/DSpace/dspace-angular/#quick-start

   # clone the repo
   git clone https://github.com/DSpace/dspace-angular.git
   
   # change directory to our repo
   cd dspace-angular
   
   # Checkout the "preview" release branch
   git checkout preview
   
   # install the local dependencies
   yarn install
   
   # start the server
   yarn start

3. After a few minutes, the user interface will be running on your local machine.  Again, it will be accessing the REST API Demo site, so a stable internet connection is required.
   1. User Interface: http://localhost:3000/
   2. REST API (remote demo site): https://dspace7.4science.cloud/server/
   3. Admin Login: dspacedemo+admin@gmail.com, Password: dspace
   4. Submitter Login: dspacedemo+submit@gmail.com, Password: dspace
4. Objects/Pages of interest (within the test data):
   1. Journal Example represents a journal with journal volumes, issues and articles, as detailed in the Configurable Entities Design.
   2. Publications Example contains publications which contain a combination of plain-text authors and related author entities. It also contains relations to Research Projects and Organizational Units, as detailed in the Configurable Entities design. Navigating to e.g. a Person will reveal their relations to Publications, Research Projects and Organizational Units.
   3. Submission/Workflow functionality can be tested using one of the collections in this community where the workflow is enabled. You can use the accounts mentioned above to perform the submission and workflow steps. The admin account can perform the submission and all workflow steps as well.
   4. Once logged in, MyDSpace functionality is found in the user menu (upper right).  Submissions can be started from that page, or via the "New → Item" admin menu (if logged in as an Admin)
5. One you are done testing, you can stop the locally running DSpace 7 user interface via Ctrl+C

Install both the User Interface and REST API locally

This installation process describes manually installing both the frontend (User Interface) and backend (REST API) of DSpace 7 on a local machine. The frontend and backend need not be installed on the same machine.
Keep in mind the installation process here may change prior to DSpace 7.0 final. This should be considered an early version of the installation process.

1. First, install the User Interface and ensure it is successfully running against the REST API Demo site.  See the instructions under Try out DSpace 7#Install the User Interface only (above).  Remember, you can choose to install this on the same machine as the REST API, or on an entirely different machine.
2. Then, install the REST API.  The REST API installation process is very similar to the installation process for DSpace 6 or below (so if you are familiar with installing DSpace already, this will be familiar to you).
   1. Required Prerequisites for the DSpace 7 REST API are listed at Installing DSpace#PrerequisiteSoftware.  These include:
      1. Java JDK 8 (OpenJDK or Oracle). OpenJDK is recommended. (Note: Java 7 is no longer supported.)
      2. Apache Maven 3.3.x or above.
      3. Apache Ant 1.8 or above.
      4. Relational Database. Either PostgreSQL 9.4 (or above) or Oracle 10g (or above)
      5. Servlet Engine. Apache Tomcat 8 (or above) is recommended.
      6. Apache Solr 7.2.1 or above.  (NOTE: This is a new requirement for DSpace 7. You MUST install Solr separately from DSpace as it is no longer provided out-of-the-box.)
   2. Installation is very similar to that of DSpace 6.x.  Draft installation instructions for the DSpace 7 REST API are available at Installing DSpace#Installation
      1. Pay close attention to a new installation step (#11 in that list).  Because Solr is now a separate install, you need to copy the DSpace Solr core configurations into your Apache Solr installation location.
   3. If you have an existing test/demo version of DSpace 6.x locally, you can optionally choose to upgrade it to the DSpace 7 Preview Release.  DO NOT DO THIS IN PRODUCTION AS THE UPGRADE IS EXPERIMENTAL AT THIS TIME.
      1. Keep in mind, your old UI changes will not be upgraded as the XMLUI and JSPUI no longer exist in DSpace 7.  Therefore, only your data (in your database and assetstore) will be upgraded.
      2. To upgrade your data, Install the DSpace 7 REST API (as noted above) on top of a copy of your existing DSpace 6.x test/demo instance. We highly recommend doing this upgrade on a copy of your DSpace 6.x instance, as you cannot "undo" it. (NOTE: Make sure you are running a valid version of all prerequisites, and have installed Solr separately) 
      3. You will also need to perform step #11 in the Installation instructions (see above) in order to configure your Apache Solr installation properly.
      4. After you start up the DSpace 7 REST API, you will need to reindex all your content by running:  [dspace]/bin/dspace index-discovery -b 
         1. NOTE: At this time we are NOT yet able to upgrade DSpace 6.x (or below) Solr statistics.  A procedure for that upgrade will be coming in the future.
   4. Once it is running locally, your REST API should be available at: http://localhost:8080/server
      1. This assumes you are running Tomcat on port 8080 (which is its default port)
3. Once both the User Interface and REST API are installed, you will need to point your locally running User Interface at your REST API

   1. In the locally installed dspace-angular project folder, modify the [dspace-angular]/config/environment.default.js configuration to point at your local REST API.  The below settings assume your REST API is available at http://localhost:8080/server 

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

   2. Alternatively, if you want, you can copy the "environment.default.js" to a new file called "environment.prod.js" and modify that new file.
   3. After the update is made, restart your User Interface by running: yarn start
4. At this point your local UI should be using your local REST API
   1. User Interface: http://localhost:3000/
   2. REST API: https://localhost:8080/server
   3. Admin Login:  You can create one on the REST API server by running [dspace]/bin/dspace create-administrator from the command-line (this same command was used in DSpace 6.x)

Reporting Issues

As you try out DSpace 7, you may run across a bug, issue or oddity (afterall, it's still under active development).  Here's how to report those so they get resolved before the final 7.0 release:

• First, if you aren't sure whether it's a bug or want advice, feel free to ask on Slack.  The DSpace 7 development team uses the #angular-ui channel (for UI discussions) and #rest-api channel (for REST API discussions). Though even reporting it on #dev (general developer channel) is perfectly fine.
• If you are sure it's an issue, create a ticket 
  • User Interface issues (including accessibility issues) should be reported via GitHub Issues at https://github.com/DSpace/dspace-angular/issues
  • REST API issues should be reported via JIRA: https://jira.lyrasis.org/projects/DS/issues
• Once it is reported, we'll analyze it and schedule it to be completed (based on priority).  Please make sure to note how you found this issue and/or any steps to reproduce it.