Installation

Die Installationsanweisungen sind derzeit nur in englischer Sprache verfügbar

The following instructions are primarily oriented towards the DARIAH-DE default environment - specifically DARIAH-DE/Ubuntu/Tomcat8/Apache proxy. Please evaluate and modify the installation steps according to your installation environment.

Prerequisites

The installation of an instance of the GS requires the setup of some required components: * An installed Java-JDK, minimum version 1.8 - installation of the JDK is required as the :term:`GS` creates and compiles Java code Please note that while the GS might startup correctly with only the JRE installed, most functionality of the GS will be limited. * A Java web-application server such as Tomcat or Jetty * MongoDB 3 as storage backend for administrative data * Elasticsearch 6 for data/metadata indices * Apache or Nginx as a web proxy server

Installation

Aside from building the application on your own, two primary installation methods are provided. For debian-based systems, the installation of the deb package is recommended as it takes care of some post-installation steps and thus simplifies installation and upgrades.

Debian Repository

GitLab CI/CD generates and provides packages for a simplified installation of the GS on Debian-based machines. The repository can be found at: https://minfba.de.dariah.eu/rep

Apt source

To install productive versions:

echo "deb https://minfba.de.dariah.eu/rep stable main" | sudo tee /etc/apt/sources.list.d/minfba_dariah_main.list

For development releases:

echo "deb https://minfba.de.dariah.eu/rep testing snapshot" | sudo tee /etc/apt/sources.list.d/minfba_dariah_snapshot.list

Repository Key

Install the signing key of the repository:

wget -O - https://minfba.de.dariah.eu/rep/key/A89C168D.gpg.key | sudo apt-key add -

Installation

Update apt sources and install GS:

apt-get update && apt-get install search

Continue with the steps in Post-installation setup

WAR Container

As an alternative installation method WAR container files of the GS can be found at:

• Production releases: https://minfba.de.dariah.eu/artifactory/webapp/#/artifacts/browse/tree/General/dariah-minfba-releases/eu/dariah/de/search
• Snapshot releases: https://minfba.de.dariah.eu/artifactory/webapp/#/artifacts/browse/tree/General/dariah-minfba-snapshots/eu/dariah/de/search

To install the GS, simply place the WAR container in the applications directory of your web server - e.g. /path/to/tomcat/webapps for Tomcat.

Post-installation setup

Directory setup

The deb package (post-installation script):

• installs the GS at /var/dfa/webapps/search. This directory needs to be linked from within the Tomcat webapps directory (e.g. in a standard Ubuntu install: ln -s /var/dfa/webapps/search/ /var/lib/tomcat8/webapps/)
• creates /etc/dfa/search and installs the simple sample configuration if search.yml does not yet exist. This configuration will probably need to be adapted, which is discussed in section 3) of this page.
• creates some working directories under /var/lib/search/

Configure Tomcat

Although the debian package comes with a complete configuration setup, manual registration of the GS configuration file is explicitly required. Modify/create the setenv.sh script within the bin directory of the installed Tomcat (default Ubuntu/Tomcat8 /usr/share/tomcat8/bin/) to point to the GS configuration:

#!/bin/sh
# Application specific environment variables

export CATALINA_OPTS="$CATALINA_OPTS -Dsearch.yml=/etc/dfa/search/search.yml"

Test startup

Start/restart Tomcat: the GS will be accessible at http://localhost:8080/search. To debug startup issues analyze the Tomcat log file (/var/log/tomcat8/catalina.out)

Additional configuration

Tomcat behind proxy

If the tomcat server is running behind a web proxy, additional configuration steps are required in order to let the application know about the outside perspective (e.g. to show correct links).

Tomcat configuration

If the proxy server is providing SSL access over port 443 (recommended), modify the Tomcat conf/server.xml file (Ubuntu/Tomcat8: /var/lib/tomcat8/conf/server.xml) and update the Connector for port 8080 to:

<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" proxyPort="443" scheme="https" />

Based on an Apache as proxy server, the host configuration is required to pass some header information to the tomcat. An appropriate proxy configuration could be as follows. Modify accordingly or adapt as nginx configuration:

# Pass host information to tomcat
ProxyPreserveHost on

# Redirect incomplete paths to the actual tomcat equivalent
Redirect /search https://search.de.dariah.eu/search/
Redirect / https://search.de.dariah.eu/search/

# Actual proxy
ProxyPass /search/ http://127.0.0.1:8080/search/
ProxyPassReverse /search/ http://127.0.0.1:8080/search/

If the Apache proxy has been setup correctly, the GS should be available at https://localhost:443 or - in the case of the above snippet - https://search.de.dariah.eu.

Hint: make sure that the Apache server has the modules ssl, proxy and proxy-http enabled.

SAML Integration

The GS includes components of the dariahsp [1] and is prepared for integration with SAML-based AAI infrastructures such as the DFN-AAI [2]. Please review the documentation of the dariahsp [3] component in order to create custom configurations.

Here, only the default DARIAH-DE/DFN-AAI case is illustrated - skipping some steps that might be necessary in other scenarios.

Java keystore (JKS)

The GS requires a Java keystore (JKS) to be present and configured in order to generate SAML metadata. A JKS can easily be created by means of openssl as illustrated here: https://gitlab.rz.uni-bamberg.de/dariah/dariahsp#java-keystore.

Modify the search.yml configuration according to the available JKS, appending the following snippet (modify accordingly):

saml:
  keystore:
    path: /etc/dfa/key/dfa-de-dariah-eu.jks
    # Uncomment if keystore is protected by password
    #pass: 'somepass'
    alias: dfa.de.dariah.eu
    aliaspass: ''

DFN-AAI Metadata

Point the configuration towards the correct DFN-AAI metadata. For new installations this will typically be metadata of the testfederation, which might later be changed to productive metadata. Append some configuration to the existing saml block:

metadata:
  url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-test-metadata.xml
  #url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-basic-metadata.xml

SP Metadata

To be able to register your installation of the GS with the DFN-AAI, you will need to create appropriate service provider (SP) metadata. While the GS includes a webbased SAML metadata management component (see https://gitlab.rz.uni-bamberg.de/dariah/dariahsp#2-saml-sp-metadata), the fastest way to produce metadata is to provide some sp configuration parameters - leading to the automatic generation of deployable SP metadata.

Append the following configuration to the existing saml block - taking particular care of:

• baseUrl: this is the base URL of the installation as configured e.g. in the apache proxy above
• entityId: use a good identifier of your SP. The baseUrl is a good and commonly used entityId.
• signingKey, encryptionKey and tlsKey point to the correct alias within your JKS
• discovery.return is build from the baseUrl and the alias of the installation

Sample configuration:

sp:
  maxAuthAge: -1
  alias: search
  baseUrl: https://search.de.dariah.eu/search
  entityId: https://search.de.dariah.eu/search
  securityProfile: metaiop
  sslSecurityProfile: pkix
  sslHostnameVerification: default
  signMetadata: true
  signingAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
  signingKey: dfa.de.dariah.eu
  encryptionKey: dfa.de.dariah.eu
  tlsKey: dfa.de.dariah.eu
  requireArtifactResolveSigned: true
  requireAttributeQuerySigned: true
  requireLogoutRequestSigned: true
  requireLogoutResponseSigned: false
  discovery:
    enabled: true
    url: https://wayf.aai.dfn.de/DFN-AAI-Test/wayf
    #url: https://auth.dariah.eu/CDS/WAYF
    return: https://search.de.dariah.eu/search/saml/login/alias/search?disco:true
  allowedNameIds : EMAIL, TRANSIENT, PERSISTENT, UNSPECIFIED, X509_SUBJECT

AAI Proxy

AAI in DARIAH-DE is simplified with the AAI Proxy, which takes care of a multitude of SAML-related aspects. If you install a service that is indended to be integrated into DARIAH-DE, please see: https://wiki.de.dariah.eu/display/publicde/DARIAH+AAI+Documentation#DARIAHAAIDocumentation-RegisteringyourServicewiththeDARIAHAAIIdPProxy

Modify tomcat configuration and restart

In order to be able to easily switch between authentication mechanisms, a flag is provided as environment parameter. Please modify the setenv.sh script within the bin directory of your Tomcat installation and append the saml flag:

export CATALINA_OPTS="$CATALINA_OPTS -Dsaml=true"

When executing a now necessary restart of the Tomcat, closely monitor the Tomcat log in order to find out if parameters around the JKS and metadata has been configured correctly.

You can access the generated metadata at https://your-servername/search/saml/metadata if everything has been setup correctly. This URL can be used to fill some parameters in the DFN-AAI self-management tools.

Also, please download the metadata yourself and place them within the configuration directory of the GS - i.e. /etc/dfa/search/sp_metadata.xml and configure the externalMetadata parameter in the search.yml under saml.sp (see the complete search.yml sample configuration below). In doing so, no automatic generation of metadata is attempted on every restart of the Tomcat/GS and the configured static metadata is utilized instead. This has proven to be more robust especially in production scenarios.

Complete DARIAH-DE sample confguration

This sample configuration comes within the installed GS directory and is also accessible here: https://gitlab.rz.uni-bamberg.de/dariah/search/blob/master/src/main/resources/search_saml_auth.yml:

#debugging:
#  sync_service_debugging: true
#  refresh_views: false
#  indexing:
#    log_resources: true
#    disable_downloads: true
#  querying:
#    log_queries: true

logfile: /data/_srv/search/logs/search.out
html_logs: /data/_srv/search/logs/html/

paths:
  main: /data/_srv/search
  datamodels: ${paths.main}/datamodels
  mappings: ${paths.main}/mappings
  grammars: ${paths.main}/grammars
  models: ${paths.main}/models
  config: ${paths.main}/config
  data: ${paths.main}/data
  crawls: ${paths.data}/crawls
  pictures: ${paths.data}/images
  downloads: ${paths.data}/downloads
  gtf:
    parse_errors: ${paths.data}/parseErrors

datamodels:
  integration: 564ca78fe4b088abc7b7fc62
  indexing: 5a27ab9b0246440d479c6c46
  presentation: 5b8fe9dd61432f44d641974c
  special:
    oai_dc: 564ca78fe4b088abc7b7fc62

presentation:
  resource:
    images:
      thumbnails:
        box_width: 135
        box_width: 135
      display:
        box_width: 500
        box_height: 500

models:
  messagecodes:
    prefix: ~de.mww
    modelIds: 598f06e706bffc03a8e44f82, 598f06e706bffc03a8e44f83

crawling:
  debugging: false
  max_threads: 4
  timeout: 172800 # 48 hours
  automation:
    online: true
    offline: true
    sync_interval: 300 # every 5 minutes

indexing:
  data:
    prefix: gs_
  index_config: ${paths.config}/index_config.json

url:
  colreg: https://dfatest.de.dariah.eu/colreg-ui/
  dme: https://dfatest.de.dariah.eu/dme/

api:
  colreg:
    autosync: false
    syncInterval: 3600
    timeout: 300
    fetch_all: ${url.colreg}api/collections
    fetch_detail: ${url.colreg}api/collections/%s/
    collection: ${url.colreg}collections/%s
  dme:
    autosync: false
    autoname: true
    autocreate: true
    syncInterval: 3600
    timeout: 300
    modelLink: ${url.dme}model/editor/%s/
    models: ${url.dme}api/models
    model: ${url.dme}api/models/%s
    mappings: ${url.dme}api/mappings
    mapping: ${url.dme}api/mappings/%s
    mapping_byST: ${url.dme}api/mappings/by-source-and-target/%s/%s
    mapping_byS: ${url.dme}api/mappings/by-source/%s
    mapping_byT: ${url.dme}api/mappings/by-target/%s

es:
  host: localhost
  port: 9200
  cluster: dariah-generic-search
  mappings:
    putlog: true
    logpath: ${paths.main}/es/mappings


mongo:
  host: localhost
  port: 27017
  database: search

auth:
  local:
    forceHttps: false
    users:
      - username: 'admin'
        passhash: '$2a$10$nbXRnAx5wKurTrbaUkT/MOLXKAJgpT8R71/jujzPwgXXrG.OqlBKW'
        roles: ["ROLE_ADMINISTRATOR"]
      - username: 'tgradl'
        passhash: '$2a$10$EeajSQQUepa7H7.g4xQCaeO.hjUwh0yzYCMrfOkWCZGe1IiWaexa6'
        roles: ["ROLE_CONTRIBUTOR"]
      - username: 'nutzer_dla'
        passhash: '$2a$10$fSb4ezX/TtVSOa9L2Y3TpOsg1TTGIZWO4Cap8rH6XqzD3gu4B4Idi'
        roles: ["ROLE_CONTRIBUTOR"]
  saml:
    keystore:
      path: ${paths.main}/key/search-de-dariah-eu.jks
      # Uncomment if keystore is protected by password
      #pass: 'somepass'
      alias: search.de.dariah.eu
      aliaspass: ''
    metadata:
      url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-test-metadata.xml
      #url: https://www.aai.dfn.de/fileadmin/metadata/dfn-aai-basic-metadata.xml
    sp:
      externalMetadata: ${paths.main}/key/search_sp.xml
      maxAuthAge: -1
      alias: search
      baseUrl: https://search.de.dariah.eu/search
      entityId: https://search.de.dariah.eu/search
      securityProfile: metaiop
      sslSecurityProfile: pkix
      sslHostnameVerification: default
      signMetadata: true
      signingAlgorithm: "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
      signingKey: search.de.dariah.eu
      encryptionKey: search.de.dariah.eu
      tlsKey: search.de.dariah.eu
      requireArtifactResolveSigned: true
      requireAttributeQuerySigned: true
      requireLogoutRequestSigned: true
      requireLogoutResponseSigned: false
      discovery:
        enabled: true
        url: https://wayf.aai.dfn.de/DFN-AAI-Test/wayf
        #url: https://auth.dariah.eu/CDS/WAYF
        return: https://search.de.dariah.eu/search/saml/login/alias/search?disco:true
      allowedNameIds : EMAIL, TRANSIENT, PERSISTENT, UNSPECIFIED, X509_SUBJECT

Finalize the installation

Having saved the metadata in the configuration directory and pointed to it within the configuration perform another restart of the Tomcat/GS to make sure that the SAML configuration is complete and correct.

After a successful restart, click on Login and you should see the following screen - indicating that the login is supposed to be handled by the DFN-AAI, which does not know our new SP installation, however. Now, the generated SP metadata needs to be registered with the DFN as soon as the DFN refreshes its metadata including the newly provided SP, logins are possible (without having to restart the GS again).

It is up to you/your organization to then push the instance to the Basic federation of the DFN-AAI.

[1]	https://gitlab.rz.uni-bamberg.de/dariah/dariahsp

[2]	https://www.aai.dfn.de/

[3]	https://gitlab.rz.uni-bamberg.de/dariah/dariahsp