Skip to content

NewInstallation

Jump to bottom Edit New page
Ondřej Košarko edited this page Jun 21, 2024 · 4 revisions

There are two ways to install dspace. First is in docker, which is easier and preferred. Second consists of downloading all necessary software, matching versions, configuring it, compiling, installing and running.

Running dspace in docker

Docker compose v2 is required. On Linux it does not always come default, so if necessary, install it with official guide.

All necessary files are in frontend repository, so first, checkout the repository from github.

git clone https://github.com/ufal/dspace-angular
cd dspace-angular

In order to run dspace in docker, .env file with environment variables is necessary.

There are two basic scenarions, that require slightly different configuration.

After docker containers are started, don't forget to set up Nginx as specified below, in order to be able to access DSpace from remote hosts.

Localhost

When running on localhost, frontend MUST run in development mode. .env file example is here:

INSTANCE=0
DSPACE_HOST=localhost
DSPACE_VER=dspace-7_x
DSPACE_SSL=false

FE_CMD=yarn start:dev

#please do not edit following variables, unless you know what you are doing
DOCKER_OWNER=ufal
DSPACE_UI_IMAGE=${DOCKER_OWNER}/dspace-angular:$DSPACE_VER
DSPACE_REST_IMAGE=${DOCKER_OWNER}/dspace:$DSPACE_VER
DSPACE_REST_PORT=808$INSTANCE
REST_URL=http://${DSPACE_HOST}:${DSPACE_REST_PORT}/server 
UI_URL=http://${DSPACE_HOST}:4000

Public

Example of .env in frontend:

INSTANCE=0
DSPACE_HOST=example.com
DSPACE_VER=dspace-7_x
DSPACE_SSL=true

# If you want to run front-end in development mode, uncomment next line
# FE_CMD=yarn start:dev
# NOTE!: line above is NECESSARY for localhost.

#please do not edit following variables, unless you know what you are doing
DOCKER_OWNER=ufal
DSPACE_UI_IMAGE=${DOCKER_OWNER}/dspace-angular:$DSPACE_VER
DSPACE_REST_IMAGE=${DOCKER_OWNER}/dspace:$DSPACE_VER
DSPACE_REST_PORT=8$INSTANCE
REST_URL=http://${DSPACE_HOST}:${DSPACE_REST_PORT}/server 
UI_URL=http://${DSPACE_HOST}:${DSPACE_REST_PORT}

# If you want to set up JAVA_OPTS
# Server memory limit (4GB)
# JAVA_OPTS=-Xmx4g

It is possible you will need to change DSPACE_REST_PORT to something else, e.g.443. Feel free to leave out $INSTANCE part and just use port number.

In both versions, it is possible to modify first section of values. Instance is arbitrary number, but enables several dspace instances to run on the same machine. Be sure to use different project names (-p parameter for docker compose)! Also be sure to check if your machine has sufficient resources (CPU, RAM) for that.

DSPACE_VER refers to image tag, most are in this list: Docker Tags

Then run commands for starting docker (you can replace dspace-project-name with something suitable for you):

docker-compose --env-file .env -f docker/docker-compose.yml -f docker/docker-compose-rest.yml pull
docker-compose --env-file .env -p dspace-project-name -f docker/docker-compose.yml -f docker/docker-compose-rest.yml up -d --no-build

Now you should be able to open $UI_URL (http://localhost:4000/ if you haven't changed it) in you browser. It takes a while before everything starts.

To add administrator and other users, use following commands, docker compose files and .env exactly the same as above.

docker-compose --env-file .env -p dspace-project-name -f docker/cli.yml run --rm dspace-cli create-administrator -e [email protected] -f firstname -l lastname -p password -c en -o organization
docker-compose --env-file .env -p dspace-project-name -f docker/cli.yml run --rm dspace-cli user --add -m [email protected] -g givenname -s surname -l en -p user -o organization

Obviously, it is possible to change parameters like -e for email, -m for email, -f for first name, -g for given name, -s for surname, -l for last name, -p for password, -o for organization. Only use the arguments for command as specified above. Just modify values if needed.

In folder with docker compose files (docker file in the above) it is also possible to have config.prod.yml file for frontend and local.cfg for backend.

Avoiding deleting volumes

The main rule is just to be careful. When volume is mounted on another disk, Docker doesn't allow removal of volume. Instead, error is displayed: Error response from daemon: remove <volume-name>: Unable to remove a directory outside of the local volume root /var/lib/docker: /<path-to-docker-storage>/volumes/test/_data. It is possible to use this fact to add another layer of protection of volumes by placing them on another disk (which is sometimes necessary in any case, due to data size). It can be done simply by sym link /var/lib/docker/volumes to specified place on another disk. But be sure to test it before relying on it.

Running dspace without docker

There are original installation instructions from vanilla dspace. However, they are quite long and extensive and some parts are not necessary. They also list several possible versions, so here is shortened list. Consult the original instructions, if anything is unclear.

Required software

Make sure you know and are able to access installed/extracted software.

Installation

  • create database

    • go to database installation folder
    • createuser --username=postgres --no-superuser --pwprompt dspace
    • createdb --username=postgres --owner=dspace --encoding=UNICODE dspace
    • psql --username=postgres -c "CREATE EXTENSION pgcrypto;" dspace

  • download dspace sources (this repo)

  • edit configuration in dspace/config/clarin-dspace.cfg (and other configs)

  • use command mvn clean install in repo root

  • (go to /dspace/target/dspace-installer)

  • use command ant fresh_install in <dspace-repo>/dspace/target/dspace-installer

    • above command creates dspace installation in new folder. By default it is C:/dspace or /dspace.
    • locate it and make sure this command created it.
    • from now on, we will refer to it as <dspace-installation-folder>

  • (go to dspace installation folder )

  • use command bin/dspace database migrate force in <dspace-installation-folder>

  • create admin bin/dspace create-administrator in <dspace-installation-folder>

  • copy everything from webapps/* to <tomcat>\webapps

  • copy solr cores cp -R [dspace]/solr/* [solr]/server/solr/configsets

  • download frontend sources

  • use command yarn install

Running dspace

  • make sure your database is running (it should be automatically)
  • (go to frontend sources)
  • use command yarn start in <frontend-source>
  • start solr by solr start
  • start tomcat by using catalina run

Notes

.env file can contain the following additional variables, to configure S3

S3_STORAGE=1
S3_ENABLED=true

S3_RELATIVE_PATH=false
S3_BUCKET=docker-dummy-bucket
S3_SUBFOLDER=
S3_ACCESS=myaccestoken
S3_SECRET=mysecretpasswordtoken
S3_REGION_NAME=us-east-1

This should be valid since version 7.5. First two must remain as is, in order to enable S3. The rest can (should) be modified.

Nginx

Whole server block should look like this:

server {
        listen 80;
        server_name dspace.url;
        location / {
            proxy_pass http://localhost:4000;
        }
        location /server/ {
            proxy_set_header Host $http_host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

            proxy_pass http://localhost:8080;
        }
}

This assumes the following:

  • Dspace is run in docker
  • backend runs on port 8080
  • frontend runs on port 4000
  • settings in .env or config state following addresses:
    • DSPACE_UI_URL: dspace.url
    • DSPACE_REST_URL: dspace.url/server/

Of course, if some ports are different, change them in cofiguration.

CMDI data for machines

Returning just cmdi metadata must be ensured in clarin installations Add this to location / block from above.

# placed in location block of dspace frontend

# redirect .../handle/123456/123456?format=cmdi to .../cmdi/oai-metadata... which returns just XML file with metadata
# ? at the end of redirect stops nginx from appending original parameters
if ($query_string ~* "format=cmdi"){
    rewrite ^/(.*)handle/(.*)$ http://$http_host/server/cmdi/oai-metadata?metadataPrefix=cmdi&handle=$2? redirect;
}

# if HTTP request to .../handle/123456/123456 contains header "Accept: application/x-cmdi+xml" or similar, redirect
# to the same as above. 
# http_*name*of*header* returns any header, in this case Accept:
if ($http_accept ~ "(.*cmdi.xml*)"){
    rewrite ^/(.*)handle/(.*)$ http://$http_host/server/cmdi/oai-metadata?metadataPrefix=cmdi&handle=$2? redirect;
}

Check

To check first part, use command like

curl -k https://dspacehost.com/handle/1234/56789?format=cmdi -L

To check second part, use command like

curl -k https://dspacehost.com/handle/1234/56789 -L -H "Accept: application/x-cmdi+xml"

Please note

OAI

There exists fear, that OAI might be unstable. Please check if OAI shows items after adding (or harvesting) many of them. They should be visible in OAI interface. If something is wrong, either empty site or Error number and short description will be shown. Check logs of apache-tomcat, try folders /dspace/log and tomcat/logs (in docker it's usually /usr/local/tomcat/logs).

Add a custom footer
Add a custom sidebar
Clone this wiki locally