Repository Checklist

📝 This page needs a review The checklist items are valid but some may need updating

Handle server

TODO: merge the two pages if possible

Handle-Server covers the conceptual overview and policy. Handle server setup (v7) covers Docker-based installation steps.

In the Docker-based deployment, the handle server runs inside the dspace backend container. The config is generated with /dspace/bin/make-handle-config during initial setup. See Handle Server Setup (v7) and Installation for full details.

Verify handle server is running

The /dspace/handle-server directory inside the backend container should contain multiple files including config.dct. Verify that the java process is running inside the container:

docker exec dspace0 ps aux | grep handle
root      6036  0.1  2.8 1648728 59296 ?       Sl   08:42   0:01 /usr/bin/java -Xmx256m -Ddspace.log.init.disable=true -Dlog4j2.configurationFile=log4j2-handle-plugin.xml -classpath ... net.handle.server.Main /dspace/handle-server

TODO: fact check nginx stream /docu lindat setup Make sure the IPs in /dspace/handle-server/config.dct are set to 0.0.0.0 so the handle server is reachable from outside the Docker container. The handle port (default 2641) must be exposed via nginx stream block — see Handle Server Setup (v7).

Verify handles correctly resolve

If you already have an item access it via hdl.handle.net

Shibboleth

In the Docker-based deployment, Shibboleth (shibd) typically runs on the host rather than inside a container. The configuration paths below refer to the host filesystem. See Installation for the overall Docker setup.

Turn shibboleth debug logging on

Go to /etc/shibboleth/shibd.logger and turn requested DEBUG on e.g.,

  1 # set overall behavior
  2 log4j.rootCategory=DEBUG, shibd_log, warn_log
  3
  4 # fairly verbose for DEBUG, so generally leave at INFO
  5 log4j.category.XMLTooling.XMLObject=INFO
  6 log4j.category.XMLTooling.KeyInfoResolver=INFO
  7 log4j.category.Shibboleth.IPRange=INFO
  8 log4j.category.Shibboleth.PropertySet=DEBUG
  9
 10 # raise for low-level tracing of SOAP client HTTP/SSL behavior
 11 log4j.category.XMLTooling.libcurl=INFO
 12
 13 # useful categories to tune independently:
 14 #
 15 # tracing of SAML messages and security policies
 16 log4j.category.OpenSAML.MessageDecoder=DEBUG
 17 log4j.category.OpenSAML.MessageEncoder=DEBUG
 18 log4j.category.OpenSAML.SecurityPolicyRule=DEBUG
 19 #log4j.category.XMLTooling.SOAPClient=DEBUG
 20 # interprocess message remoting
 21 #log4j.category.Shibboleth.Listener=DEBUG
 22 # mapping of requests to applicationId
 23 log4j.category.Shibboleth.RequestMapper=DEBUG

shib_test.pl

Make sure you have made available and shibboleth protected the test script.

SSL certificates

Ensure that the ssl certificates are stricly valid as they are accessed from a java application that does not ignore even small glitches (Shibboleth.sso/DiscoFeed, lr.statistics.api.url in case it uses https).

You can verify with this command

openssl s_client -showcerts -connect www.something.org:443

Monitoring urls

Exclude traffic from specific monitoring urls from Matomo (see http://piwik.org/faq/how-to/faq_80/) and from dspace by adding the ip address (range) to the spider/bot ignore configuration.

Number of Connections to database

DSpace 7 uses the Hikari connection pool. Ensure the total connections configured do not exceed the PostgreSQL limit:

db.maxconnections (local.cfg) < max_connections (postgres/postgresql.conf)

In the Docker deployment, the PostgreSQL container's max_connections can be set via the docker-compose configuration or a custom postgresql.conf.

Web server rewrites/redirects

This section contains the necessary rewrites/redirects. In the Docker deployment, nginx runs on the host and proxies to the backend (/server/) and frontend containers. See Installation for the Docker compose and nginx setup.

The examples below are a mix of apache and nginx configs that should provide the general idea. Depending on your settings you might need to change the ports/paths/hostnames.

For accept header cmdi and query string format=cmdi. In apache it's as follows:

# handle cmdi requests with redirects
RewriteCond %{HTTP_ACCEPT} (.*cmdi.xml.*)
RewriteRule ^(.*)/handle/(.*)$ https://%{HTTP_HOST}$1/server/oai/cite?metadataPrefix=cmdi&handle=$2 [L,R=301]
RewriteCond %{QUERY_STRING} format=cmdi [NC]
RewriteRule ^(.*)/handle/(.*)$ https://%{HTTP_HOST}$1/server/oai/cite?metadataPrefix=cmdi&handle=$2 [L,R=301]

You can check it using

http://hdl.handle.net/11234/1-1548@format=cmdi

curl -L -H "Accept: application/x-cmdi+xml"  https://lindat.mff.cuni.cz/repository/handle/11234/1-1548

If you use handle prefix from EPIC, the prefix should have the namespace handle fragments set correctly to be able to resolve @format=cmdi, see e.g., http://hdl.handle.net/0.NA/11858

<namespace>
<template delimiter="@">
<foreach>
<if value="type" test="equals" expression="URL">
<value data="${data}?${extension}"/>
</if>
<else>
<if value="type" test="equals" expression="HS_ALIAS">
<value data="${data}@${extension}"/>
</if>
<else>
<value/>
<else>
</else>
</foreach>
</template>
</namespace>

If the query string is not working try what's suggested in #543

OAI-PMH must be available on http. In DSpace 7, the OAI-PMH endpoint is at /server/oai. The nginx proxy should route OAI requests directly to the backend container:

server {
  listen 80 default_server;
  server_name fqdn localhost;

  location ~ .*/server/oai.* {
    proxy_pass http://localhost:8080;
  }

  location / {
          return 301 https://$http_host$request_uri;
  }
}