Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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


    Code Block
    # 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:  

      Code Block
      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.): 

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


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

      Code Block
      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. At this point, you should be able to see a completely empty DSpace 7 site.  You may now choose to either add test/demo content (see step #5 below) and/or add an initial Administrator account (see step #6 below).
    1. User Interface: http://localhost:30004000/
    2. REST API: http://localhost:8080/server/
  5. 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: 

      Code Block
      # If you don't have an Admin created with the email "test@test.edu", create it. The AIP ingest runs as that user by default.
      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
      
      # This second command will import a batch of test/sample AIPs (see "cli.ingest.yml" for more info)
      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.

        Code Block
        # 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:

        Code Block
        # 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


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

    Code Block
    # This example creates an Admin user with email "test@test.edu" and password "admin".
    # (You may have already created this user above, before loading AIP test data. If so, you can skip this)
    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


  7. After a few minutes, you should have a full local installation of DSpace 7 Preview (with test data).
    1. User Interface: http://localhost:30004000/
    2. REST API: http://localhost:8080/server/ 
    3. Admin Login: (whatever login you setup via the "dspace-cli" command above)
  8. 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).
  9. Once you are done testing, you can stop Docker and clean up the data (deleting the volumes). 

    Code Block
    # 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


...

  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 (v10.x or v12.x) 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

    Code Block
    # clone the repo
    git clone https://github.com/DSpace/dspace-angular.git
    
    # change directory to our repo
    cd dspace-angular
    
    # 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:30004000/
    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

...

  • 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 an issue ticket 
    • Frontend / User Interface issues (including accessibility issues) can be reported via GitHub Issues at https://github.com/DSpace/dspace-angular/issues
    • Backend / REST API issues should be reported via JIRA: GitHub issues at https://jiragithub.lyrasis.orgcom/projectsDSpace/DSDSpace/issues
    • (If you aren't sure where to report the issue, don't worry. Just report it via either route, and we'll move it to the proper place as needed.)
  • 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.

...