Installation

Diese Seite beschreibt die Neuinstallation von smart.finder. Beachten Sie, dass die vorgegebenen Systemanforderungen erfüllt sind, siehe Systemanforderungen.

Im folgenden werden die notwendigen Schritte zur Integration von smart.finder mit Apache Solr beschrieben. Die Installation von Apache Solr wird an dieser Stelle nicht dokumentiert. Folgenden Sie hierzu der offiziellen Apache Solr Dokumentation .

Wenn Sie eine bestehende Installation aktualisieren möchten, fahren Sie mit Update einer bestehenden Installation fort.

Installation von smart.finder

smart.finder besteht aus folgenden Komponenten, die im folgenden Abschnitt beschrieben werden:

Komponente Speicherort

Apache Solr Index Konfiguration

[RELEASE-ORDNER]/ressources/solr/cores

Server Webapp

[RELEASE-ORDNER]/smartfinder-search.war

map.apps Bundles

[RELEASE-ORDNER]/ct-smartfinder-js-3.0.0.jar

map.apps Apps

[RELEASE-ORDNER]/resources/apps

Server Command Line Interface (CLI)

[RELEASE-ORDNER]/cli

Die folgenden Abschnitte beschreiben die Installation der einzelnen Komponenten.

Apache Solr Konfiguration

Die Konfiguration von Apache Solr erfolgt in zwei Schritten:

  1. Definition erforderlicher Umgebungsvariablen

  2. Konfiguration des smart.finder Index

Definition erforderlicher Umgebungsvariablen

Definieren Sie vor dem Start von Apache Solr die folgenden Umgebungsvariablen:

SOLR_ENABLE_STREAM_BODY=true
SOLR_ENABLE_REMOTE_STREAMING=true
SOLR_SECURITY_MANAGER_ENABLED=false
SOLR_MODULES=extraction,analysis-extras,scripting

Die Umgebungsvariablen können auf unterschiedliche Weise definiert werden:

  • in der Datei /etc/default/solr.in.sh (Linux) oder [SOLR_INSTALL_DIR]/bin/solr.in.cmd (Windows)

    • für Linux fügen Sie die Variablen wie oben genannt ein

    • für Windows erweitern Sie die Zeilen folgendermaßen: set SOLR_ENABLE_STREAM_BODY=true

  • als Systemumgebungsvariablen

Konfiguration des smart.finder Index

Das Rollout von smart.finder beinhaltet vorkonfigurierte Apache Solr Indexe. Diese müssen in des SOLR_HOME Verzeichnis kopiert werden.

Das SOLR_HOME Verzeichnis befindet sich standardmäßig unter [SOLR_INSTALL_DIR]/server/solr.

Sie können Apache Solr auch mit einem anderen Verzeichnis starten. In diesem Fall müssen Sie dies entsprechend anpassen. Hier bestehen folgende Möglichkeiten:

  • in der Datei /etc/default/solr.in.sh (Linux) oder [SOLR_INSTALL_DIR]/bin/solr.in.cmd (Windows)

  • als Systemumgebungsvariablen

  • beim Start von Apache Solr mit dem Parameter --solr-home <dir>

  1. Kopieren Sie den Inhalt des Verzeichnisses [RELEASE-ORDNER]/resources/solr/cores in das SOLR_HOME Verzeichnis. Damit entsteht folgende Verzeichnisstruktur:

    /SOLR_HOME
 /core0
 /featuresearch
 /indexingmanagement
 /lib
 /...

  2. Verschieben Sie die Datei [RELEASE-ORDNER]/resources/solr/cores/lib/jts-core-[VERSION].jar in das Verzeichnis [SOLR_INSTALL_DIR]/server/solr-webapp/webapp/WEB-INF/lib. Diese Bibliothek wird von Apache Solr für die erweiterte räumliche Suchfunktionen benötigt.

  3. Starten Sie Apache Solr und rufen Sie die Admin-Oberfläche auf, um sicherzustellen, dass die Konfiguration erfolgreich war.

Stellen sie nach dem Kopieren sicher, dass die korrekten Zugriffsrechte auf die Dateien und Verzeichnisse für Apache Solr gesetzt sind. Dies gilt insbesondere für Linux Umgebungen. Beispiel für das SOLR_HOME Verzeichnis, wenn Solr mit dem Standard-Nutzer solr und der Gruppe solr installiert wurde:

chown -R solr:solr core0/ featuresearch/ indexingmanagement/ lib/

Gleiches gilt für die Datei jts-core-[VERSION].jar.

Optional: Absicherung des direkten Zugriffs auf Apache Sorl

Der direkte Zugriff auf den Apache Solr Dienst kann optional über Basic Authentication abgesichert werden. Konfigurieren Sie hierzu das Basic Authentication Plugin in Apache Solr. Andere Authentifizierungsmethoden werden durch smart.finder nicht unterstützt.

Im Fall einer Absicherung mittels Basic Authentication muss der Nutzer für den Zugriff auf Apache Solr entsprechend in smart.finder konfiguriert werden. Verwenden Sie hierzu die Properties solr.auth.username und solr.auth.password (bzw. secret.solr.auth.password).

Installation der Server Webapp

Installieren Sie die Server Webapp smartfinder-search.war wie folgt.

  1. Optional können Sie den Namen der WAR-Datei ändern. Der Name erscheint in der URL zur Anwendung.

  2. Stellen Sie sicher, dass der Tomcat-Dienst gestartet ist.

  3. Kopieren Sie anschließend die WAR-Datei in den Ordner %TOMCAT%\webapps. Die Datei wird nun automatisch entpackt.
    Alternativ können Sie den Tomcat Manager benutzen, um die WAR-Datei zu installieren. Wenn der Tomcat-Dienst gestartet ist, erreichen Sie den Tomcat Manager üblicherweise unter http://<yourserver>:8080/manager/html.

  4. Konfigurieren Sie nun die Basis-URL zum Apache Solr Dienst. Dies erfolgt in der Datei application.properties, die für die smart.finder Server Webapp verwendet wird. Weitere Informationen zur Konfiguration finden Sie in der Konfigurationsreferenz.

    Folgendes Property muss gesetzt werden:

    solr.server.url

    URL zur verwendeten Apache Solr Instanz.

    Standardwert: http://localhost:8983/solr

  5. Starten Sie den Tomcat oder die Web-Anwendung neu. Die Server-Anwendung ist nun unter der folgenden URL verfügbar:

    https://<yourserver>/smartfinder-search

Installation der Client-Webapp

Die Client-Anwendung wird in einer existieren map.apps Instanz installiert. Die Installation und Konfiguration erfolg in drei Schritten:

  1. Installation der Bundles

  2. Installation der Apps

  3. Installation des smart.finder Job-Manager

Installation der Bundles

  1. Melden Sie sich als admin-Benutzer in map.apps Manager an.

  2. Öffnen Sie den Reiter Bundles.

  3. Klicken Sie auf die +-Schaltfläche oberhalb der Liste der installierten Bundles.

  4. Laden Sie die Datei [RELEASE-ORDNER]/ct-smartfinder-js-3.0.0.jar hoch. Diese enthält alle Bundles für smart.finder.

Sobald die Bundles hochgeladen wurden, werden sie in der Liste der installierten Bundles angezeigt. Um die smart.finder-Bundles von anderen Bundles einfacher unterscheiden zu können, beginnen deren Namen immer mit dem Kürzel sf_.

Installation der Apps

  1. Melden Sie sich als admin-Benutzer in map.apps Manager an.

  2. Öffnen Sie den Reiter Apps.

  3. Klicken Sie auf die +-Schaltfläche oberhalb der Liste der installierten Apps. Es öffnet sich der App-Assistent.

  4. Geben Sie einen Namen und einen Titel für die App ein und gehen Sie im Assistenten vor bis zu dem Schritt für das Hochladen einer App.

  5. Die Apps liegen als ZIP-Dateien im Ordner [RELEASE-ORDNER]/resources/apps. Laden Sie die gewünschte App hoch.

  6. Fahren Sie mit den nächsten Schritten im Assistenten fort, bis der Assistent abgeschlossen ist.

  7. Starten Sie die App, indem Sie in der App-Liste auf der rechten Seite auf die Starten-Schaltfläche klicken.

Installation des smart.finder Job-Manager

Um den smart.finder Job-Manager innerhalb des map.apps Manager nutzen zu können, gehen Sie folgendermaßen vor:

  1. Öffnen Sie die map.apps Konfigurationsdatei application.properties. Diese liegt üblicherweise im Ordner [USER_HOME]/.mapapps

  2. Suchen Sie den Eintrag manager.config.viewbundles. Falls er bereits existiert, ergänzen Sie am Ende den Wert sf_jobadmin. Falls er noch nicht existiert, fügen Sie den Eintrag mit dem folgenden Wert ein:

    Beispiel für manager.config.viewbundles
    manager.config.viewbundles=appmanagement,reportmanagement,bundlemanagement,mapapps-github-manager,bundleupdatechecker,sf_jobadmin

  3. Fügen Sie außerdem einen neuen Eintrag finder.service.url für die URL des smart.finder Servers hinzu:

    finder.service.url=https://<yourserver>/smartfinder-search

    Die Property finder.service.url wird sowohl vom Job Manager zur Verwaltung der Indexierungs-Jobs verwendet, als auch von sämtlichen Apps für Suchanfragen.

  4. Um Raumausschnitte für den CSW-Filter zu definieren, können Sie in dieser Datei zusätzlich die Property csw.filters.boundingboxes ergänzen.

    Beispiel für csw.filters.boundingboxes:
    csw.filters.boundingboxes=[\
{\
'title': {\
  'de':'Deutschland',\
  'en':'Germany'\
},\
'minX': 5.8663153,\
'maxX': 15.0419319,\
'minY': 47.2701114,\
'maxY': 55.058347\
},\
{\
'title': {\
'de':'Frankreich',\
'en':'France'\
},\
'minX': -5.142222,\
'maxX': 9.662499,\
'minY': 41.333740,\
'maxY': 51.124199\
}\
]

    Eine genaue Beschreibung dazu finden Sie in der Dokumentation zum Bundle "sf_jobadmin" .

Starten Sie Tomcat neu und laden Sie map.apps Manager erneut im Webbrowser. Anschließend erscheint im map.apps Manager der neue Reiter Indexierungs-Jobs.

smart.finder Server und map.apps mit unterschiedlichen Domänen

Falls die smart.finder Serverkomponente unter einer anderen Domäne als map.apps erreichbar ist, stellen Sie sicher, dass das map.apps Proxy-Servlet für den Zugriff auf den smart.finder Server freigeschaltet ist. In diesem Fall sollten Sie den Domänennamen des Clients zu der CORS-Konfigurationseigenschaft cors.allowed.origins in der Datei application.properties der smart.finder-Server-Webapp hinzufügen.

Wenn Sie Schwierigkeiten mit CORS haben, können Sie auch das map.apps Proxy Servlet verwenden. Für weitere Informationen siehe CORS Einstellungen.

Konfiguration smart.finder map.apps App

Zum Ausführen der mitgelieferten Apps ist nun alles konfiguriert. Diese Apps bieten Ihnen einen Ausgangszustand für eigene Anpassungen.

Wenn Sie smart.finder in einer ihrer eigenen map.apps Apps verwenden möchten, können Sie über den map.apps Manager das Bundle sf_full-screen-map zu dieser App hinzufügen. Das Bundle lädt alle nötigen weiteren Bundles, um die Suche per Omnisearch (dem Standard-Bundle in map.apps für Schlüsselwortsuche) und die Ergebnisanzeige in einem Popup zu ermöglichen.

Weitere Informationen zur Konfiguration finden Sie im Abschnitt Apps und Bundles.

Installation der CLI

Das smart.finder CLI ist ein Werkzeug, um über die Kommandozeile Indexierungsjobs zu verwalten.

finderctl wird als ausführbare Datei für Windows- und Linux-Betriebssysteme (x86-64 Architektur) ausgeliefert. Es befindet sich unter:

  • [RELEASE-ORDNER]\cli\windows_x64\finderctl.exe für Windows

  • [RELEASE-ORDNER]/cli/linux_x64/finderctl für Linux

Verzeichnis verschieben
Sie können das finderctl Verzeichnis inklusive der Hilfsdateien auch an einen beliebigen anderen Ort kopieren. Kopieren Sie ebenfalls die neben der ausführbaren Datei liegenden Hilfsdateien. Diese werden gegebenenfalls zur Laufzeit von finderctl benötigt.

Fügen Sie den Speicherort von finderctl zum Suchpfad Ihres Systems hinzu (z.B. $PATH oder %PATH%). So können Sie finderctl ausführen, ohne den vollständigen Pfad angeben zu müssen. Abhängig von Ihrem Betriebssystem ist es gegebenenfalls notwendig, finderctl zur Ausführung zu berechtigen.

Verifizieren Sie die Installation durch Ausführen des folgenden Befehls:

~$ finderctl --version

Sicherheitsaspekte

Den Zugriff auf sicherheitskritische Funktionen verwalten Sie komplett in der Serverkomponente des smart.finder. Diese beinhaltet das Anlegen von Indexierungsjobs, das Befüllen oder Löschen des Indexes sowie das Lesen spezifischer administrativer Schnittstellen. Für jeden dieser Fälle ist eine Nutzerauthentifizierung erforderlich, die im Browser angefragt wird.

Web Application Security

smart.finder besitzt Endpunkte für die Abfrage und den schreibenden Zugriff auf den Index oder sonstige Kernfunktionen.

Die Konfiguration der Sicherheitseinstellungen sind in Authentifizierung und Autorisierung beschrieben.

TLS/SSL Server Trust

Stellen Sie beim Aufbau von Verbindungen zu HTTPS-Endpunkten durch serverseitige Java-Komponenten sicher, dass das TLS/SSL-Server-Zertifikat des angefragten Hosts von der Java Virtual Machine (JVM) akzeptiert und als vertrauenswürdig erachtet wird. Dies betrifft den smart.finder, wenn Sie im Manager mittels Job-Konfiguration Quellen indexieren, auf die über einen HTTPS-Endpunkt zugegriffen wird (z.B. OGC CSW-Katalog).

Mit der Konfigurationsoption security.ssl.trustAny wird gesteuert, unter welchen Bedingungen ein TLS-Server-Zertifikat akzeptiert wird:

security.ssl.trustAny=true

Es werden alle Zertifikate akzeptiert.
Einzige Bedingung ist, dass das Zertifikat zeitlich gültig ist. Das Zertifikat muss weder für den angefragten Host, noch von einer vertrauenswürdigen Stelle ausgestellt worden sein. Diese Einstellung sollte nur in Entwicklungsumgebungen aktiv sein.

security.ssl.trustAny=false

Auslieferungszustand
Es werden nur Zertifikate akzeptiert, die von der JVM als vertrauenswürdig erachtet werden.
Es wird dringend empfohlen, diese Einstellung beizubehalten. Dies gilt insbesondere für produktive Umgebungen. Sie müssen sicherstellen, dass Server-Zertifikate von HTTPS-Endpunkten, zu denen Verbindungen hergestellt werden, vertrauenswürdig sind. Andernfalls kommt es beim Aufbau einer Verbindung zu einem Fehler.

Vertrauenswürdigkeit von Serverzertifikaten

Damit ein Serverzertifikat von der JVM als vertrauenswürdig erachtet wird, müssen Sie entweder das konkrete Serverzertifikat oder dessen Stammzertifikat im Java Runtime Environment (JRE) installieren. Vertrauenswürdige Zertifikate bzw. Stammzertifikate werden im JRE standardmäßig in einem Java-Keystore unter [JRE_HOME]/lib/security/cacerts gespeichert. Je nach Betriebssystem oder Konfiguration der JVM ist es jedoch möglich, dass andere Quellen für vertrauenswürdige Zertifikate genutzt werden.

Im Folgenden wird beschrieben, welche Typen von Serverzertifikaten von HTTPS-Endpunkten üblicherweise verwendet werden und was bezüglich der Vertrauenswürdigkeit zu beachten ist.

Zertifikate mit Stammzertifikat, das im JRE installiert ist

Produktive Web Sites, die Dienste per HTTPS zur Verfügung stellen, besitzen üblicherweise Serverzertifikate, deren Stammzertifikat von einer vertrauenswürdigen Certificate Authority (CA) ausgestellt wurde. Diese Stammzertifikate sind im JRE bereits vorinstalliert und werden damit automatisch als vertrauenswürdig eingestuft.

Um die Verbindung mit einem Endpunkt zu erlauben, dessen Serverzertifikat ein bereits im JRE installiertes Stammzertifikat besitzt, sind keine weiteren Schritte notwendig.

Zertifikate mit Stammzertifikat, das nicht im JRE installiert ist

Gelegentlich werden in Organisationen Serverzertifikate verwendet, die von einer eigenen, organisationsinternen CA ausgestellt wurden. Das zugehörige Stammzertifikat ist folglich nicht Teil der im JRE vorinstallierten Zertifikate. Verbindungen zu HTTPS-Endpunkten mit solchen Serverzertifikaten schlagen dann fehl, es sei denn, Sie fügen das Stammzertifikat durch unternehmensinterne Prozesse automatisch allen JRE-Installationen hinzu.

Um sicherzustellen, dass allen von dieser organisationsinternen CA ausgestellten Serverzertifikaten vertraut wird, fügen Sie das Stammzertifikat der CA dem Keystore [JRE_HOME]/lib/security/cacerts hinzu.

Selbstsignierte Zertifikate

Selbstsignierte Serverzertifikate, also Zertifikate, die sich selbst als Herausgeber referenzieren, werden häufig zu Testzwecken verwendet und sollten in Produktivsystemen nicht genutzt werden. Da ein selbstsigniertes Serverzertifikat nicht Teil der in der JRE bereits installierten Zertifikate ist, ist es nicht vertrauenswürdig.

Um HTTPS-Verbindungen mit einem Host zu erlauben, der ein selbstsigniertes Serverzertifikat verwendet, fügen Sie dieses Zertifikat dem Keystore [JRE_HOME]/lib/security/cacerts hinzu.

Typische Fehlermeldungen

Beim Aufbau serverseitiger HTTPS-Verbindungen kann es zu verschiedenen Fehlersituationen im Zusammenhang mit der Validierung von Serverzertifikaten kommen. In den folgenden Abschnitten werden typische Fehlermeldungen aufgeführt, die in der Log-Datei der serverseitigen Anwendung oder in den Browser-Oberflächen der Applikationen erscheinen können. Zusätzlich werden möglichen Ursachen beschrieben und Lösungen vorgeschlagen. Abhängig von der konkreten Infrastruktur, in der die betroffene Applikation betrieben wird, sind ggf. auch andere Ursachen und Lösungen in Betracht zu ziehen.

Typische Fehlermeldungen:

PKIX path building failed

Vollständige Fehlermeldung:

sun.security.validator.ValidatorException:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Diese Fehlermeldung ist ein Hinweis darauf, dass das vom Server präsentierte Zertifikat für die HTTPS-Verbindung von der JVM nicht als vertrauenswürdig eingestuft wird. Ggf. handelt es sich um ein selbst-signiertes Zertifikat, oder das Stammzertifikat ist nicht im JRE installiert.

Mögliche Lösungen:

  • Installieren des Stammzertifikats im JRE

  • Installieren des Serverzertifikats im JRE

  • Wenn der angefragte Server unter eigener Kontrolle ist: Bereitstellung eines neuen Serverzertifikats auf dem angefragten Server, das von einer vertrauenswürdigen CA ausgestellt wurde.

No name matching [requested.host.name] found

Vollständige Fehlermeldung:

javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No name matching maps.example.com found

Diese Fehlermeldung zeigt an, dass der in der HTTPS-Anfrage genutzte Host-Name nicht zu dem Host-Namen passt, der im Serverzertifikat angegeben ist. Der Client (Browser, Java-Applikation) vergleicht dabei den in der Anfrage-URL verwendeten Host-Namen mit dem CN-Namen des Subject-Feldes im X509-Zertifikat des Servers, z.B.

https://maps.example.com/

mit

CN = www.example.com, O = Example LLC, L = Mountain Dew, ST = California, C = US.

Stimmen beide Namen nicht überein (Groß-/Kleinschreibung ist nicht relevant), wird der Verbindungsaufbau mit der oben genannten Fehlermeldung abgebrochen. Dabei ist es unerheblich, ob das Zertifikat als vertrauenswürdig eingestuft würde. Die Prüfung der Vertrauenswürdigkeit findet erst statt, wenn sichergestellt ist, dass die Host-Namen übereinstimmen.

Häufig kommt es zu diesem Problem, wenn Clients denselben Server mit unterschiedlichen Namen ansprechen können, weil mehrere DNS-Einträge vorhanden sind. Insbesondere wenn der Client sich in derselben Domäne wie der Server befindet, führt oft die uneinheitliche Nutzung von nicht-qualifizierten und vollqualifizierter Host-Namen in Anfrage-URLs bzw. Serverzertifikaten zu diesem Problem. Auch die Verwendung des speziellen Host-Namens localhost oder von IP-Adressen in URLs führt zu diesem Problem, wenn das Serverzertifikat auf den qualifizierten Rechnernamen ausgestellt wurde.

Mögliche Lösungen:

  • Verwendung des Host-Namen in Anfrage-URLs in der Form, wie er im Serverzertifikat angegeben wird.

  • Erstellen und Hinterlegen eines neuen Serverzertifikats für den vom Client gewünschten Host-Namen, wenn sich zum Beispiel herausstellt, dass die Verwendung eines nicht-vollqualifizierten Host-Namens (oder localhost oder IP-Adresse) nicht sinnvoll ist.

  • Erstellen und Hinterlegen eines neuen Serverzertifikats mit alternativen Host-Namen (Subject Alternative DNS Names), wenn sich zum Beispiel herausstellt, dass der Server unausweichlich unter unterschiedlichen Host-Namen erreichbar sein muss.

No subject alternative DNS name [requested.host.name] found

Vollständige Fehlermeldung:

javax.net.ssl.SSLHandshakeException:
java.security.cert.CertificateException: No subject alternative DNS name matching maps.example.com found

Diese Fehlermeldung ist ein Sonderfall der Fehlermeldung No name matching [requested.host.name] found dieser Liste. Einziger Unterschied ist, dass das Serverzertifikat ein zusätzliches Feld mit alternativen Host-Namen besitzt, jedoch der vom Client verwendete Host-Name weder dem Subject-CN des Serverzertifikats entspricht noch in dessen Liste alternativer Host-Namen (Subject Alternative DNS Names) angegeben ist.

Mögliche Lösungen: Die Lösungsvorschläge der vorherigen Fehlermeldung gelten auch hier.