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 :term:`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 :term:`GS` might startup correctly with only the JRE installed, most functionality of the :term:`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 :term:`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 :term:`GS`:: apt-get update && apt-get install search Continue with the steps in :ref:`Post-installation setup` WAR Container +++++++++++++ As an alternative installation method WAR container files of the :term:`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 :term:`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 :term:`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 :term:`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 :term:`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 :term:`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:: 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 :term:`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 :term:`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 :term:`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 :term:`GS` with the DFN-AAI, you will need to create appropriate service provider (SP) metadata. While the :term:`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 :term:`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/:term:`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 :term:`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/:term:`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 :term:`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