SmartSearch - Admin-Handbuch

1. Einleitung

Die SmartSearch bündelt Anforderungen, die an die Suchfunktion einer Online-Präsenz gestellt werden: Eine intuitiv bedienbare, hochperformante Suchlösung, die auf umfangreichen Webseiten einsetzbar ist und relevante Ergebnisse liefert. Sie bietet sowohl eine hohe Trefferqualität als auch einen optimalen Suchkomfort und bindet Nutzende somit auf der Webseite.

Gleichzeitig stellt sie Bearbeitenden durch das integrierte SmartSearch-Cockpit eine Web-Oberfläche bereit, die ohne IT-Kenntnisse verwendbar ist. Bearbeitende aus Fach- und Marketingabteilungen werden so in die Lage versetzt, Suchergebnisse auf der Webpräsenz zu steuern und zu überwachen. Das Cockpit stellt dafür Statistiken, Filter sowie Analysefunktionen bereit und erlaubt die Indizierung verschiedenster Datentypen (zum Beispiel XML, Audio, Video, Medien) aus unterschiedlichen Datenquellen. Mithilfe individualisierter Trefferlisten können Bearbeitende im Backend Suchergebnisse priorisieren und gewichten sowie ausgewählte Inhalte zu vordefinierten Suchanfragen ausgeben lassen.

Das vorliegende Dokument richtet sich an Admins und beschreibt daher lediglich die erforderlichen Installations- und Konfigurationsschritte. Alle durch die SmartSearch zur Verfügung gestellten Funktionalitäten und Anwendungsfälle sind in der SmartSearch-Dokumentation enthalten.

1.1. Architektur

Die Funktionalitäten der SmartSearch werden über eine Architektur verschiedener Komponenten realisiert (vgl. Abbildung Architektur).

Bei diesen Komponenten handelt es sich um:

ZooKeeper
Solr
SmartSearch

Abbildung 1. Architektur

Das Zusammenspiel der Komponenten erfolgt immer nach dem folgenden Schema:

Für die Erstellung des Suchindex muss die SmartSearch zunächst die notwendigen Daten erfassen. Dafür greift sie kundenunternehmensseitig auf die zu erfassenden Informationen zu, die in Form von Webseiten, Portalen oder Datenbanken vorliegen können. Darüber hinaus stellt eine REST-Schnittstelle die Möglichkeit bereit, den Suchindex von außen mit weiteren Daten zu befüllen.
Danach normalisiert der SmartSearch-Server die erfassten Daten und überträgt sie an den Solr-Server. Dieser nimmt die Daten entgegen und persistiert sie in einem Index.
Die Abfrage der Daten erfolgt äquivalent: Der SmartSearch-Server nimmt die Anfrage entgegen, modifiziert sie und leitet sie dann an den Solr-Server weiter. Dieser antwortet mit einem Suchergebnis, das der SmartSearch-Server über die REST-Schnittstelle an die Endanwendung des Kundenunternehmens zurückliefert.
Das SmartSearch-Cockpit ist losgelöst von den übrigen Komponenten zu sehen. Es dient der Verwaltung des SmartSearch-Servers und bietet dafür eine einfache, webbasierte Admin-Oberfläche an. In dieser sind unter anderem Suchlösungen erstell- und konfigurierbar.
Die Speicherung der im SmartSearch-Cockpit vorgenommenen Konfigurationen erfolgt neben den Solr-Konfigurationsdaten auf dem ZooKeeper-Server.

Die Kommunikation nach außen ist durch HTTPS geschützt, zwischen den Komponenten erfolgt sie per HTTP.

1.2. Technische Voraussetzungen

Der Einsatz der SmartSearch besitzt die folgenden technischen Voraussetzungen:

Java 11 als Java Development Kit (JDK) für die Ausführung von ZooKeeper und Solr
ZooKeeper in der Version 3.4.10
Solr in der Version 8.6.3 im Cloud-Modus
SmartSearch in der neuesten Version, die zur Ausführung unbedingt Java 21 benötigt

ZooKeeper und Solr sind nicht in der Auslieferung enthalten. Sie müssen daher vor der Installation in der angegebenen Version heruntergeladen werden.

Obwohl Java 11 die Standardanforderung für ZooKeeper und Solr ist, arbeitet SmartSearch mit Java 21. Um dies zu berücksichtigen, müssen sowohl Java 11 als auch Java 21 auf dem System vorhanden sein. Allerdings erfordert nur SmartSearch Java 21.

Um SmartSearch mit Java 21 laufen zu lassen, führen Sie es mit der ausführbaren Datei Java 21 aus. Stellen Sie sicher, dass Java 11 das Standard-JDK des Systems für alle anderen Operationen bleibt. Sie können den SmartSearch-Server starten, indem Sie den Pfad zur ausführbaren Java 21-Datei wie folgt angeben:

/pfad/zu/java21/bin/java -jar Server.jar -server -Dhaupia.master.profile=STANDALONE -Dfile.encoding=UTF-8

Mit diesem Vorgehen können Sie Java 21 für die Ausführung des SmartSearch-Servers verwenden, ohne die für Java 11 konfigurierte Standard-Java-Umgebung zu ändern, wodurch die Kompatibilität mit anderen Abhängigkeiten gewährleistet wird.

2. Installation und Konfiguration

Für die Verwendung der Funktionalitäten der SmartSearch müssen zunächst die einzelnen Komponenten installiert werden, die beliebig verteilbar und frei skalierbar sind. Es ist essenziell, dass sie in der folgenden Reihenfolge installiert werden, damit die grundlegenden Konfigurationen richtig vorgenommen werden können:

ZooKeeper
Solr
SmartSearch

ZooKeeper und Solr sind nicht in der Auslieferung enthalten. Sie müssen daher vor der Installation in der Version, die in den technischen Voraussetzungen genannt ist, heruntergeladen werden.

Es wird davon abgeraten, die Installation der Komponenten als root auszuführen. Stattdessen wird die Verwendung eines technischen Users mit den entsprechenden Zugriffsrechten empfohlen. Es wird erwartet, dass der Name des technischen Users jeweils dem Namen der Komponente entspricht.

Solr legt diesen User-Eintrag automatisch an. Eine manuelle Erstellung ist daher in diesem Fall nicht notwendig.

Da die meisten Rechnersysteme auf Linux basieren, konzentrieren sich auch die folgenden Unterkapitel ausschließlich auf die Installation unter Linux. Die angegebenen Befehle beziehen sich dabei auf das folgende System:

Ubuntu 18/04 LTS (Bionic Beaver)
OpenJDK 11

Des Weiteren wird für die Installationsbeschreibung das Szenario einer einfachen Redundanz angenommen (vergleiche Abbildung einfache Redundanz). Die zwei auf der folgenden Abbildung dargestellten Knoten N₁ und N₂ entsprechen zwei physikalischen oder virtuellen Systemen, auf denen jeweils eine ZooKeeper-, Solr- und SmartSearch-Instanz zu installieren ist. Solch ein Cluster-Betrieb aus mindestens zwei Knoten gewährleistet eine grundlegende Ausfallsicherheit und Datenredundanz.

Sind die Aspekte Ausfallsicherheit und Datenredundanz für Sie nicht relevant, lässt sich der gesamte Stack auch auf einem einzigen Knoten installieren. Das Kapitel zum Betrieb eines einzelnen Knotens beschreibt die dafür zu beachtenden Unterschiede.

Abbildung 2. einfache Redundanz

Das beschriebene Szenario kann als Grundlage für einen Cluster-Betrieb mit beliebig vielen Knoten angesehen werden.

Abbildung 3. Cluster-Betrieb mit beliebig vielen Knoten

2.1. Verwendete Ports

Im Rahmen der nachfolgenden Kapitel zur Installation der verschiedenen Komponenten werden diverse Ports genannt. Die folgende Tabelle zeigt eine Übersicht über diese Ports und erläutert ihre Bedeutung.

Tabelle 1. verwendete Ports
Port	Bedeutung
8181	Dieser Port ist für das SmartSearch-Cockpit und erlaubt den Zugriff auf die REST API.
8983	Dieser Port erlaubt den Zugriff auf die Solr-Oberfläche und die API.
2181	Dieser Port ermöglicht die Client-Kommunikation einer ZooKeeper-Instanz.
2888	Dieser Port dient der Kommunikation zwischen den ZooKeeper-Instanzen.
3888	Dieser Port dient ebenfalls der Kommunikation zwischen den ZooKeeper-Instanzen.

2.2. ZooKeeper

Für die Sicherung der Konfigurationen von Solr und der SmartSearch ist die Installation und Konfiguration zweier ZooKeeper-Instanzen notwendig, die nicht in der Auslieferung enthalten sind. Laden Sie ZooKeeper dafür in der Version, die in den technischen Voraussetzungen angegeben ist, herunter und installieren Sie es auf beiden Systemen in das zu erstellende Verzeichnis ZooKeeper. Dieser Ordner kann sich an einer beliebigen Stelle in dem jeweiligen System befinden.

Standardmäßig ist die Annahme, dass sich das zu erstellende Installationsverzeichnis im opt-Verzeichnis des zugehörigen Systems befindet. Abweichungen sind in der ZooKeeper.service-Datei entsprechend anzupassen.

Erzeugen Sie anschließend pro System mit dem folgenden Befehl die notwendige Konfigurationsdatei unter conf/zoo.cfg.

Anlegen der Konfigurationsdatei (auf beiden System auszuführen)

cp ~/zookeeper/conf/zoo_sample.cfg ~/zookeeper/conf/zoo.cfg

Legen Sie in demselben Verzeichnis eine Datei mit dem Namen java.env an, um die Menge des ZooKeeper zur Verfügung stehenden Speichers anzupassen. In dieser Datei müssen Sie die Parameter zur Änderung des Speichers für ZooKeeper angeben.

Anlegen der java.env-Datei (auf beiden Systemen auszuführen)

touch ~/zookeeper/conf/java.env

Standardmäßig speichert ZooKeeper Konfigurationsdaten im tmp-Verzeichnis. Da dieses jedoch nur der temporären Speicherung dient, wird stattdessen das im Installationsverzeichnis beider Systeme zu erstellende Verzeichnis ZooKeeper-data benötigt. Damit ZooKeeper es für die Persistierung verwendet, ist auf beiden Systemen der Pfad des ZooKeeper-data-Verzeichnisses in der zoo.cfg-Datei als Wert des Parameters dataDir anzugeben. Ergänzen Sie in derselben Datei die Hostnamen beziehungsweise statischen IP-Adressen aller einzubindenden ZooKeeper-Instanzen. In diesem Fall entspricht diese Angabe den Hostnamen hostname-n1 und hostname-n2. Für die Kommunikation untereinander benutzen die ZooKeeper-Instanzen standardmäßig die Ports 2888 und 3888. Die Portangabe nach dem Semikolon bezieht sich auf den Port, auf dem ZooKeeper auf Verbindungen horcht. Zusätzlich ist die Erlaubnis sogennanter 4 letter words-Kommandos erforderlich, da Solr diese benötigt.

Bei der beschriebenen Serverkonfiguration wird jedem Server eine ID mitgegeben: Beispielsweise ist in der Angabe server.1 die ID 1. Die ID muss einer Zahl zwischen 1 und 255 entsprechen. Die Definition der Server-ID erfolgt in der im Datenverzeichnis zu erstellenden Datei myid, die darüber hinaus keinen weiteren Inhalt besitzt.

zoo.cfg - Angabe der ZooKeeper-Instanzen (auf beiden System identisch)

server.1=hostname-n1:2888:3888;2181
server.2=hostname-n2:2888:3888;2181

4lw.commands.whitelist=*

Anschließend lassen sich beide ZooKeeper-Server mithilfe des folgenden Befehls starten.

Starten des ZooKeeper-Servers (auf beiden Systemen auszuführen)

~/zookeeper/bin/zkServer.sh start

Zusätzlich zu den SmartSearch-Konfigurationen werden auch die Einstellungen des Solr-Servers in ZooKeeper gespeichert. Um Konflikte zu vermeiden, ist eine Trennung der Daten notwendig. Dies erreichen Sie durch die Erzeugungen eines leeren Solr-Knotens, den ZooKeeper für die Persistierung der Solr-Dateien nutzt. Der Knoten lässt sich nur mit einem laufenden ZooKeeper-Client erstellen, der anschließend wieder zu beenden ist.

Da ZooKeeper die Daten synchron hält, ist die Erstellung des Solr-Knotens nur auf einer der beiden Instanzen notwendig.

Der ebenfalls benötigte SmartSearch-Knoten wird während der Installation des SmartSearch-Servers automatisch erzeugt und muss daher nicht manuell angelegt werden.

Erzeugung des Solr-Knotens (auf einem System auszuführen)

~/zookeeper/bin/zkCli.sh
create /solr ""
quit

Kopieren Sie abschließend die ZooKeeper.service-Datei, die in der Auslieferung im Ordner systemd-samples enthalten ist, auf beiden Systemen jeweils in das Verzeichnis etc systemd system. Diese ermöglicht, ZooKeeper als Service zu nutzen und über systemctl zu steuern.

Es ist zu gewährleisten, dass in der service-Datei jeweils sowohl der User-Eintrag als auch der Pfad des Installationsverzeichnisses richtig angegeben sind. Standardmäßig wird der User-Eintrag ZooKeeper sowie eine Installation unter opt angenommen.

Die Speicherung der Konfigurationen aus dem Backend der SmartSearch erfolgt ebenfalls in ZooKeeper. Der Name des root-Knotens lautet dabei standardmäßig haupia. So ist eine Trennung zu den Solr-Daten gewährleistet. Innerhalb dieses Ordners sind die Konfigurationsdaten lesbar gespeichert. Die vergebenen Namen in der Konfiguration sind gleichzeitig die Namen der Knoten.

2.3. Solr

Die Persistierung unternehmensspezifischer Daten, die der SmartSearch-Server sammelt, erfolgt mithilfe zweier Solr-Server. Diese sind nicht in der Auslieferung enthalten und müssen daher manuell installiert werden. Laden Sie dafür Solr in der Version, die in den technischen Voraussetzungen angegeben ist, herunter und installieren Sie es auf beiden Systemen in das zu erstellende Verzeichnis Solr. Das Verzeichnis kann sich an einer beliebigen Stelle in dem jeweiligen System befinden.

Standardmäßig ist die Annahme, dass sich das zu erstellende Installationsverzeichnis im opt-Verzeichnis des zugehörigen Systems befindet. Abweichungen sind in der solr.service-Datei entsprechend anzupassen.

Solr stellt für die Installation das Skript install_solr_service.sh bereit, das Sie zunächst aus der heruntergeladenen Datei extrahieren und anschließend auf beiden Systemen ausführen müssen. Dabei können Sie das Zielverzeichnis für die Persistierung der gesammelten Daten jeweils frei wählen. Das Skript installiert beide Solr-Server als Service, legt auf ihnen den User-Eintrag solr an und erzeugt zusätzlich alle benötigten Dateien sowie Verzeichnisse.

Für die noch ausstehende Konfiguration müssen sich beide Solr-Server zwingend in einem nicht laufenden Zustand befinden.

Installation des Solr-Servers (auf beiden System auszuführen)

./install_solr_service.sh solr-8.6.3.tgz -d <VARIABLE_PATH> -n

Beispielsweise für die Speichernutzung benötigen die Solr-Server diverse Java-Variablen. Diese sind pro System in der Konfigurationsdatei etc/default/solr.in.sh zu definieren.

Des Weiteren muss in dieser Datei jeweils die Verwendung der Solr-Cloud aktiviert und der Solr-Knoten, der zuvor während der ZooKeeper-Installation erzeugt wurde, angegeben werden.

Vor der Ausführung des Skripts ist sicherzustellen, dass der Solr-Knoten während der ZooKeeper-Installation erzeugt wurde und dort tatsächlich existiert.

Anpassung der Solr-Konfiguration (auf beiden Systemen auszuführen)

sed -i 's/#ZK_HOST=.*/ZK_HOST=hostname-n1:2181,hostname-n2:2181\/solr/' /etc/default/solr.in.sh

Da die aktuell empfohlene Solr Version von der Log4J CVE-2021-44228 Problematik betroffen sind, ist die Empfehlung, folgende Konfiguration anzpassen:

(Linux/MacOS) In der Datei solr.in.sh folgendes ergänzen SOLR_OPTS="$SOLR_OPTS -Dlog4j2.formatMsgNoLookups=true"
(Windows) In der Datei solr.in.cmd folgendes ergänzen SOLR_OPTS=%SOLR_OPTS% -Dlog4j2.formatMsgNoLookups=true

Mehr Information zu dem Thema sind hier zu finden.

Kopieren Sie abschließend die solr.service-Datei, die in der Auslieferung im Ordner systemd-samples enthalten ist, auf beiden Systemen jeweils in das Verzeichnis etc systemd system. Diese ermöglicht, Solr als Service zu nutzen und über systemctl zu steuern.

Es ist zu gewährleisten, dass in der Service-Datei jeweils sowohl der User-Eintrag als auch der Pfad des Installationsverzeichnisses richtig angegeben sind. Standardmäßig wird eine Installation unter opt angenommen.

Die SmartSearch liefert ein eigenes Schema mit, das auf dem Solr-Server zu installiert ist. Dafür müssen nach der Solr-Installation, aber vor dem ersten Start, folgende Jar-Dateien zusätzlich im Classpath vorhanden sein. Diese sind ein Bestandteil der Solr-Auslieferung und im contrib-Verzeichnis enthalten.

morfologik-stemming-X.Y.Z.jar
morfologik-fsa-X.Y.Z.jar
morfologik-polish-X.Y.Z.jar
lucene-analyzers-morfologik-X.Y.Z.jar
lucene-analyzers-smartcn-X.Y.Z.jar

2.4. SmartSearch

Die SmartSearch ist eine auf Spring Boot basierende Suchlösung und ermöglicht die Steuerung, Filterung und Analyse von individualisierten Trefferlisten. Um die Funktionalitäten des SmartSearch-Stacks zu nutzen, ist dieser auf beiden Systemen in das zu erstellende Verzeichnis SmartSearch zu installieren. Er wird in Form einer zip-Datei bereitgestellt. In dem pro System erstellten Installationsverzeichnis ist außerdem die Lizenz abzulegen, die sich vom Technical Support anfordern lässt. Das Verzeichnis kann an einer beliebigen Stelle in dem jeweiligen System erzeugt werden.

Standardmäßig ist die Annahme, dass sich das zu erstellende Installationsverzeichnis im opt-Verzeichnis des zugehörigen Systems befindet. Abweichungen sind in der smart-search.service-Datei und in der application.yml für alle Parameter entsprechend anzupassen.

Nach der Installation des SmartSearch-Stacks ist auf beiden Systemen die Durchführung der folgenden Konfigurationsschritte notwendig:

Erzeugung des Verzeichnisses data: Der SmartSearch-Stack benötigt für die Datenspeicherung das Verzeichnis data. Dieses ist innerhalb des jeweiligen Installationsverzeichnisses manuell zu erstellen.

Anpassung der application.yml-Datei

Die in der Auslieferung enthaltene application.yml-Datei ermöglicht die Konfiguration des jeweiligen SmartSearch-Servers. Dabei sind insbesondere die folgenden Punkte zu beachten:

Der SmartSearch-Server verwendet standardmäßig den Port 8181. Diesen können Sie jedoch pro System optional anpassen.
Die Kommunikation des Servers ist nach außen per SSL geschützt. In der Auslieferung ist dafür ein selbstsigniertes Zertifikat enthalten. Dieses dient ausschließlich der lokalen Entwicklung und muss für den produktiven Einsatz zwingend gegen ein offiziell signiertes Zertifikat ausgetauscht werden.
Die in der application.yml-Datei enthaltene SSL-Konfiguration darf zwar verändert, jedoch nicht entfernt werden, da für den Betrieb der SmartSearch eine gültige SSL-Konfiguration erforderlich ist.
Für die Speicherung von Konfigurationsdaten benötigt der SmartSearch-Server eine Verbindung zu dem ZooKeeper seines Systems. Dafür muss ihm unter dem Parameter connection des Keys ZooKeeper die Adresse des entsprechenden ZooKeeper-Servers bekannt gemacht werden.
Das zuvor angelegte Verzeichnis data muss dem SmartSearch-Stack ebenfalls bekannt gemacht werden. Dafür ist in der zugehörigen application.yml-Datei der Parameter root des Keys haupia entsprechend anzupassen.
Den ZooKeeper-Instanzen muss der Host-Name jeder einzelnen SmartSearch-Instanz bekannt sein. Dieser ist daher jeweils zwingend als Wert des Parameters server.address anzugeben. Erfolgt keine Angabe, ist eine Verwendung des SmartSearch-Cockpits nicht möglich.
Die Ermittlung von Userdaten erfolgt durch den Zugriff auf einen Cache. Dieser benötigt im Fall von Änderungen eine gewisse Zeitspanne für die Aktualisierung. Der Parameter haupia.zookeeper.users.cache.await definiert die Zeitspanne in Sekunden, in der auf eine solche Aktualisierung gewartet wird. Initial entspricht der Standardwert einem Timeout von einer Sekunde.
Die SmartSearch ermittelt das zu verwendende URL-Schema aus der Solr Cluster Property urlScheme. Ist dieser Wert nicht gesetzt, wird standardmäßig http verwendet. Der Parameter solr.url.scheme ermöglicht eine Überschreibung des Verhaltens und muss den Wert http oder https besitzen.
Es ist möglich, den Solr-Server mithilfe einer Basis-Authentifizierung zu sichern. Die notwendigen Zugangsdaten sind über die Parameter solr.auth.username und solr.auth.password anzugeben.
Bei der Nutzung des FirstSpirit-Moduls SmartSearch Connect ermöglicht der Parameter haupia.connect.datagenerator.pool.size die Konfiguration, auf wie viele FirstSpirit-Projekte in Form eines eigenen Datengenerators reagiert werden muss. Ist der Wert kleiner als die Anzahl der angebundenen FirstSpirit-Projekte, so können nicht von allen Projekten Daten empfangen werden. Ist dieser Wert nicht gesetzt, so gilt ein Maximum von Anzahl der Kerne x 500.
Den Timeout für den automatischen Logout von Usern aus dem SmartSearch-Cockpit definiert der Parameter server.servlet.session.timeout. Mögliche Werte für ihn sind zum Beispiel 60s oder 1h. Der Default-Timeout liegt bei 15 Minuten.

Der Master-Admin-Eintrag wird beim initialen Start des ersten SmartSearch-Servers automatisch erzeugt und muss daher für alle Instanzen dieselben Daten besitzen. Er ist weder deaktivier- noch löschbar und verhindert so ein Aussperren aus dem SmartSearch-Cockpit. Das Master-Admin-Passwort kann im SmartSearch-Cockpit geändert werden. Ein Start des SmartSearch-Servers mit dem optionalen Parameter resetAdminPassword setzt das Master-Admin-Passwort auf den Wert aus der application.yml zurück.

Start-Parameter, Encoding und JVM-Modus: Die beiden SmartSearch-Server benötigen zum Starten den Parameter -Dhaupia.master.profile=STANDALONE. Dieser ist standardmäßig in der mitgelieferten server.conf-Datei enthalten und darf nicht geändert werden. Darüber hinaus lassen sich in dieser Datei unter anderem das Encoding und der Modus der Java Virtual Machine bestimmen. Diese sind ebenfalls bereits gesetzt und lassen sich bei Bedarf anpassen. Zusätzlich bietet die Datei die Möglichkeit, die Speichernutzung des jeweiligen SmartSearch-Servers zu definieren.

Starten Sie den SmartSearch-Stack des ersten Systems über das in der zip-Datei enthaltene server.jar. Diese enthält ein Launch-Skript, welches den Einsatz der jar-Datei als Unix-Service ermöglicht. Erst, wenn die Logdatei der ersten SmartSearch-Instanz die folgende Meldung über den erfolgreichen Start enthält, darf die zweite Instanz analog gestartet werden:

Logmeldung

less /opt/SmartSearch/logs/SmartSearch.log
(...) Started Server in 60 seconds (JVM running for 61.2)

Beim Starten von server.jar mit Java 21 ist es wichtig sicherzustellen, dass der Server die korrekte Java-Version verwendet und gleichzeitig nahtlos als Dienst funktioniert. Wenn das Startskript aus dem Verzeichnis etc init.d ausgeführt wird, erkennt es diesen Kontext und startet den Server als Dienst. Um server.jar als Dienst mit Java 21 zu betreiben, müssen Sie explizit die MODE-Variable auf service setzen und den Pfad zur ausführbaren Java 21-Datei im Befehl verwenden. Hier ist, wie Sie SmartSearch im Dienstmodus starten können:

MODE=service /path/to/java21/bin/java -jar server.jar -server -Dhaupia.master.profile=STANDALONE -Dfile.encoding=UTF-8 start

Kopieren und editieren Sie abschließend die smart-search.service-Datei entsprechend, die in der Auslieferung im Ordner systemd-samples enthalten ist, auf beiden Systemen jeweils in das Verzeichnis etc systemd system. Diese ermöglicht, die SmartSearch als Service zu nutzen und über systemctl zu steuern.

Es ist zu gewährleisten, dass in der service-Datei jeweils sowohl der User-Eintrag als auch der Pfad des Installationsverzeichnisses richtig angegeben sind. In der überarbeiteten Konfiguration muss der Dienst explizit den Pfad zur ausführbaren Java 21-Datei /path/to/java21/bin/java zusammen mit dem Pfad zur Jar-Datei der Anwendung /opt/haupia/server.jar angeben. Standardmäßig wird der Benutzer haupia sowie die Installation unter /opt/haupia angenommen. Stellen Sie sicher, dass diese Pfade in der Servicekonfiguration aktualisiert werden, um die tatsächliche Installationsumgebung widerzuspiegeln.

Die installierten und konfigurierten SmartSearch-Instanzen kommunizieren miteinander und führen eine sogenannte Leader Election durch, mit der die führende Instanz festgelegt wird. Während sich der REST-Service auf allen laufenden Instanzen identisch verhält, lässt sich das SmartSearch-Cockpit ausschließlich auf dem Leader aufrufen. Dies hat zur Folge, dass sowohl die Konfiguration als auch die automatische beziehungsweise manuelle Ausführung der Datengeneratoren ebenfalls lediglich auf der führenden Instanz möglich ist.

Bei dem Versuch das Cockpit über eine andere Instanz als dem Leader anzusprechen, erfolgt eine automatische Weiterleitung. Diese Weiterleitung wird durch eine an ZooKeeper adressierte Leader-Abfrage realisiert. Dem ZooKeeper muss dafür der Host-Name jeder einzelnen Instanz bekannt sein.

Darüber hinaus muss die SmartSearch-Lizenz in einer Textdatei auf dem SmartSearch-Server hinterlegt sein. Die Beantragung der Lizenz erfolgt über den Technical Support der Crownpeak Technology GmbH. Der folgende Key ermöglicht, in der application.yml-Datei auf diese Lizenzdatei zu verweisen:

Verweis zur SmartSearch-Lizenz

haupia:
   licence:
      path: ./license.txt

2.5. HTTPS-Proxy-Konfiguration

Sollte ein http(s)-Proxy nötig sein, damit die Web/XML-Crawler Zugriff auf ihre Crawl-Ziele haben, so lässt dieser sich per JAVA_OPTS konfigurieren. Die relevanten Parameter zur Konfiguration sind die folgenden:

Tabelle 2. Proxy-Konfiguration
Parameter	Beschreibung	Wert
http\|https.proxyHost	Host für den http(s)-Proxy	12.13.14.15
http\|https.proxyPort	Port für den http-Proxy	8080
http.nonProxyHosts	Ausnahmen, bei denen der Proxy nicht berücksichtigt werden soll.	localhost

Exemplarischer Eintrag in der server.conf-Datei

JAVA_OPTS="-server
-Dhaupia.master.profile=STANDALONE
-Dfile.encoding=UTF-8
-Dhttp.proxyHost=12.13.14.15
-Dhttp.proxyPort=8080
-Dhttps.proxyHost=12.13.14.15
-Dhttps.proxyPort=8080
-Dhttp.nonProxyHosts=localhost|127.0.0.1"

In der aktualisierten Konfiguration, in der keine server.conf Datei verwendet wird, muss die Konfiguration für einen HTTP(S)-Proxy, der für Web/XML-Crawler notwendig ist, direkt im Java-Ausführungsbefehl angegeben werden.

Dies könnte auch in der smart-search.service Datei erforderlich sein, abhängig von der Konfiguration.

3. Tiefergehende Konfiguration

Die SmartSearch basiert auf Spring Boot und lässt sich über die application.yml-Datei, die im SmartSearch-Verzeichnis neben der server.jar-Datei liegt, konfigurieren. Die application.yml-Datei bietet eine Vielzahl von Konfigurationsmöglichkeiten, die in der Spring-Boot-Dokumentation beschrieben sind. Beispielsweise stellt sie die Möglichkeit bereit, Logging- und Sicherheitseinstellungen vorzunehmen. Das nachfolgende Beispiel erläutert die Konfiguration von SSL, die einen häufigen Anwendungsfall darstellt.

Beispiel: SSL-Konfiguration

Die SmartSearch nutzt standardmäßig SSL, um eine sichere Übertragung der Daten zu ermöglichen, und verwendet dabei den Spring-Boot-Jetty. Dies funktioniert in den meisten Fällen. Bei der Wahl des Protokolls oder der Verschlüsselung können aber Problemen auftreten. Die Spring-Boot-Dokumentation beschreibt die Konfigurationsschlüssel server.ssl.enabled-protocols und server.ssl.ciphers, mit denen sich etwaige Probleme lösen lassen. Um zunächst eine Liste möglicher Parameter zu bekommen, muss das Logging für Jetty an der richtigen Stelle auf DEBUG gesetzt werden. Dazu ist der application.yml-Datei folgende Konfiguration hinzuzufügen:

Konfiguration des Jetty-Loggings

logging:
   level:
      org:
         eclipse:
            jetty:
               util:
                  ssl: DEBUG

Nach der Konfiguration des Loggings und einem Neustart enthält das Log am Ende des Startvorgangs eine DEBUG-Ausgabe, die ungefähr folgendes Aussehen besitzt:

Beispiel für eine DEBUG-Ausgabe der SSL-Informationen des Jettys

May 22 11:14:50 smart-search-cluster-1 server.jar[1208]: 2017-05-22 11:14:50.621 DEBUG 1230 --- [ main] o.e.jetty.util.ssl.SslContextFactory : Selected Protocols [TLSv1, TLSv1.1, TLSv1.2] of [SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2]
May 22 11:14:50 smart-search-cluster-1 server.jar[1208]: 2017-05-22 11:14:50.622 DEBUG 1230 --- [ main] o.e.jetty.util.ssl.SslContextFactory : Selected Ciphers [TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, [...]
May 22 11:14:50 smart-search-cluster-1 server.jar[1208]: A, SSL_DH_anon_WITH_DES_CBC_SHA, [...]

Diese zwei Logausgaben geben die aktuellen Werte für das Protokoll und die Verschlüsselung sowie die möglichen Werte aus. Um die Verschlüsselung bei Bedarf auf zwei Verschlüsselungsverfahren zu begrenzen, ist die application.yml-Datei wie folgt anzupassen:

Konfiguration der SSL-Verschlüsselungsverfahren

server:
   ssl:
      ciphers:
         TLS_DHE_RSA_WITH_AES_128_CBC_SHA,
         TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256

Gleiches gilt für das verwendete Protokoll. Nach einer erfolgreichen Konfiguration ist diese bei einem Neustart in den Logs zu finden.

3.1. Konfiguration der Solr-Replikas

Nach der Installation ZooKeepers, Solrs und der SmartSearch sind in der Solr-Weboberfläche abschließend die nachfolgenden Schritte durchzuführen. Sie ermöglichen auf beiden Solr-Instanzen die automatische Replikation der Daten, die die SmartSearch für die Beantwortung von Suchabfragen benötigt.

Die beschriebenen Schritte beziehen sich lediglich auf den beschriebenen Cluster-Betrieb mit mindestens zwei Knoten. Für den Betrieb eines einzelnen Knotens sind sie ignorierbar.

Öffnen Sie über die URL http://hostname-<INSTANCE>:8983 zunächst die Solr-Weboberfläche auf einem der beiden Systeme und wählen Sie den Menüpunkt Collections. Die Weboberfläche zeigt daraufhin eine Liste aller existierenden Collections. Selektieren Sie in dieser Liste die Collection, die den Namen des Mandanten trägt, und klicken Sie auf den Punkt Shard: shard1.

Mithilfe des Buttons Add replica lässt sich dann eine weitere Replika anlegen. Belassen Sie das Dropdown im Zustand No specified node und erzeugen sie die Replika über den Button Create Replica. Solr wählt dabei automatisch einen freien Knoten aus.

Laden Sie Weboberfläche nach der Erstellung der Replika neu und überprüfen Sie die Existenz der zweiten Replika über einen Klick auf den Punkt Shard: shard1.

Wiederholen Sie die beschriebenen Schritte anschließend mit der Collection, die den Suffix _signals besitzt.

3.2. Betrieb eines einzelnen Knotens

Sind die Aspekte Ausfallsicherheit und Datenredundanz für den Betrieb der SmartSearch nicht relevant, lässt sich der gesamte Stack auch auf einem einzigen Knoten installieren.

Abbildung 4. Betrieb eines einzelnen Knotens

Die Installation der einzelnen Instanzen erfolgt analog zur Beschreibung in den vorhergehenden Kapiteln. Allerdings sind die folgenden Unterschiede zu beachten:

Angabe von ZooKeeper-Instanzen

Im Cluster-Betrieb müssen in den zoo.cfg-Dateien aller Systeme die Hostnamen bzw. statischen IP-Adressen aller einzubindenden ZooKeeper-Instanzen angegeben werden. Diese Angabe entfällt im Fall eines einzelnen Knotens.

Sed-Skript zur Anpassung der Solr-Konfiguration

Die Anpassung der Solr-Konfiguration erfolgt über das Skript solr.in.sh. Der Befehl für dessen Ausführung lautet in diesem Fall wie folgt:

Anpassung der Solr-Konfiguration für den Betrieb eines einzelnen Knotens

sed -i 's/#ZK_HOST=.*/ZK_HOST=localhost:2181\/solr/' /etc/default/solr.in.sh

Solr-Replikas

Die Erstellung von Replikas bezieht sich nur auf den Cluster-Betrieb. Für den Betrieb eines einzelnen Knotens ist ihre Erzeugung daher zu ignorieren.

3.3. LDAP

Die Verwaltung der für die Nutzung der SmartSearch notwendigen User und Gruppen sowie die Definition der Berechtigungen findet standardmäßig innerhalb des SmartSearch-Cockpits statt. Die Speicherung der User und Gruppen erfolgt über den zuvor installierten ZooKeeper-Server.

Alternativ dazu besteht jedoch die Möglichkeit, die User- und Gruppenverwaltung auf Basis von LDAP umzusetzen. Dabei ist zu beachten, dass sich diese Möglichkeit nur auf die Authentifizierung (User und Gruppen), nicht jedoch auf die Autorisierung (ACLs) bezieht.

Die Anbindung LDAPs stellt lediglich einen lesenden Zugriff auf den LDAP-Server her. Eine Verwaltung von Usern und Gruppen innerhalb des SmartSearch-Cockpits ist anschließend nicht mehr möglich.

Für die Nutzung LDAPs müssen auf dem LDAP-Server die folgenden Aspekte gegeben sein:

LDAP-seitig sind die User an den Gruppen zu konfigurieren.
Erfolgt die Verwaltung der User und Gruppen über das SmartSearch-Cockpit, wird für den allerersten Login und die initiale Zuweisung von Berechtigungen ein Master-Admin-Eintrag bereitgestellt. Äquivalent dazu wird auch LDAP-seitig ein Master-Admin-Eintrag vorausgesetzt. Der Master-Admin-Eintrag muss der ebenfalls benötigten Gruppe ADMIN zugeordnet sein.

Abbildung 5. LDAP-seitiges Usermanagement

Es ist zu beachten, dass User, die der Admin-Gruppe angehören, uneingeschränkt die Berechtigungen innerhalb des SmartSearch-Cockpits bearbeiten dürfen.

Voraussetzung für einen erfolgreichen User-Login ist, dass dem SmartSearch-Cockpit der LDAP-seitig verwendete Passwort-Encoder bekannt ist. Dieser kann daher im Passwortfeld in der Form {id}hash angegeben werden. Die ID entspricht dabei der ID des Hashing-Algorithmus' und muss einem der folgenden Werte entsprechen:
- bcrypt
- sha, SHA oder SHA-1
- md4 oder MD4
- md5 oder MD5
- noop oder NOOP
- pbkdf2
- SHA-256, SHA256 oder sha256

Alternativ besteht die Möglichkeit, den Passwort-Encoder in der application.yml-Datei des SmartSearch-Servers als Wert des Parameters haupia.ldap.default-password-encoder zu definieren.

Zusätzlich zu den LDAP-seitigen Anpassungen sind in der application.yml-Datei des SmartSearch-Servers die folgenden Pflichtparameter anzugeben:

haupia.ldap.enable
Dieser Parameter aktiviert die Nutzung LDAPs. Der Wert des Parameters haupia.ldap.enable ist auf true zu setzen.
spring.ldap.username und spring.ldap.password
Für die Verbindung zum LDAP-Server wird ein technischer User benötigt, welcher dem SmartSearch-Server bekannt zu machen ist. Aus diesem Grund müssen der Distinguished Name (DN) sowie das Passwort des technischen Users für die Parameter spring.ldap.username und spring.ldap.password angegeben werden.
haupia.ldap.user-search-base bzw. haupia.ldap.group-search-base
Für die Suche der User- bzw. Gruppenobjekte ist ebenfalls der entsprechende Distinguished Name (DN) als Wert des Parameters haupia.ldap.user-search-base bzw. haupia.ldap.group-search-base anzugeben.
(Beispiel: ou=people,dc=example,dc=org bzw. ou=groups,dc=example,dc=org)

Die Suche nach User- bzw. Gruppenobjekten bezieht sich ausschließlich auf die angegebene Ebene. Subtrees sind von dieser Suche ausgeschlossen.

Zusätzlich zu diesen Pflichtangaben lassen sich darüber hinaus optional weitere Anpassungen vornehmen:

spring.ldap.urls
Dieser Parameter enthält eine Liste der URLs zu den verfügbaren LDAP-Servern. Standardmäßig besitzt der Parameter den Wert ldap://localhost:389.
spring.ldap.base
Mit diesem Parameter lässt sich für alle gegen den LDAP-Server ausgeführten Operationen ein DN-Suffix definieren.
haupia.ldap.user-filter
Um ein User-Objekt im Baum des LDAP-Servers zu finden, kann mit diesem Parameter ein Filter angegeben werden. Standardmäßig besitzt er den Wert uid={0}. Der Platzhalter {0} wird dabei durch den eingegebenen Username ersetzt.
haupia.ldap.group-filter
Äquivalent zum User-Filter ermöglicht dieser Parameter die Angabe eines Gruppenfilters, der alle mit dem User verknüpften Gruppenobjekte findet. Standardmäßig besitzt er den Wert (member={0}). Der Platzhalter {0} wird in diesem Fall durch den Distinguished Name (DN) des entsprechenden User-Eintrags ersetzt.
haupia.ldap.default-password-encoder
Wird der verwendete Password-Encoder nicht dem Passwortfeld auf dem LDAP-Server hinzugefügt, kann er stattdessen mithilfe dieses Parameters angegeben werden. Standardmäßig besitzt er den Wert bcrypt.
haupia.ldap.user-attributes.uid und haupia.ldap.user-attributes.password
Die Werte dieser Parameters entsprechen den Feldern, in denen der Username bzw. das Passwort LDAP-seitig gespeichert sind. Standardmäßig besitzen sie die Werte uid und userPassword.
haupia.ldap.user-attributes.language und haupia.ldap.user-attributes.default-language
Mithilfe des language-Parameters lässt sich steuern, in welcher Sprache das SmartSearch-Cockpit startet. Fehlt er, wird stattdessen der Wert des default-language-Parameters verwendet. Dieser definiert als Standard-Sprache initial Englisch.
haupia.ldap.group-attributes.name und haupia.ldap.group-attributes.user
Äquivalent zu den User-Attributen entsprechen die Werte dieser Parameter dem Namen einer Gruppe sowie der Liste der in einer Gruppe enthaltenen User. Sie besitzen standardmäßig die Werte cn und member.

Die Gruppennamen werden im SmartSearch-Cockpit grundsätzlich in Großbuchstaben angezeigt, auch wenn sie LDAP-seitig eine andere Schreibweise besitzen.

LDAP-Parameter in der application.yml

spring:
   [...]
   ldap:
      urls: ldap://localhost:389
      password: admin
      username: cn=admin,dc=example,dc=org
      base: dc=example,dc=org

[...]

haupia:
   [...]
   ldap:
      enable: false
      user-search-base: ou=people,dc=example,dc=org
      user-filter: uid={0}
      group-search-base: ou=groups,dc=example,dc=org
      group-filter: (member={0})
      default-password-encoder: bcrypt
      user-attributes:
         uid: uid
         password: userPassword
         language: language
         default-language: en
      group-attributes:
         name: cn
         user: member

4. SSL

Die Verarbeitung der von der SmartSearch gesammelten Daten setzt eine Kommunikation zwischen den einzelnen Komponenten sowie der Endanwendung des Kundenunternehmens voraus. Die Kommunikation des SmartSearch-Stacks nach außen ist dabei per SSL geschützt. Der SmartSearch-Server verwendet dafür standardmäßig ein selbstsigniertes Zertifikat, das in der Auslieferung enthalten ist.

Das in der Auslieferung enthaltene, selbstsignierte Zertifikat ist lediglich für den Einsatz in lokalen Entwicklungsumgebungen ausgerichtet. Für den Einsatz des SmartSearch-Stacks im Produktivbetrieb wird daher die Verwendung eines offiziell signierten Zertifikats dringend empfohlen.

Die Durchführung der nachfolgenden Schritte setzt voraus, dass bereits ein offiziell signiertes Zertifikat angefordert wurde und die Datei server.crt somit zur Verfügung steht. Des Weiteren wird angenommen, dass alle notwendigen Dateien jeweils in demselben Verzeichnis abgelegt sind.

Für den Einsatz des SmartSearch-Stacks im Produktivsystem ist zunächst ein neuer Keystore zu erzeugen. Dieser muss dem Server bekannt gemacht werden, um die bereits vorhandenen Zertifikate zu ersetzen. Der nachfolgende Befehl zeigt ein Beispiel für die Erzeugung des neuen Keystores:

Erzeugung des neuen Keystores

openssl pkcs12 -export -in server.crt -inkey server.key -out server.p12 -name server -CAfile ca.crt -caname root

Der Befehl bewirkt eine Konvertierung des x509-Zertifikats und des zugehörigen Keys in eine pkcs12-Datei. Das dabei zu vergebende Passwort ist in der application.yml-Datei unter dem Parameter key-store-password des Keys ssl anzugeben. An derselben Stelle muss der neu erstellte Keystore für den Parameter key-store sowie das keyAlias server definiert werden.

Der Betrieb der SmartSearch setzt eine gültige SSL-Konfiguration voraus. Aus diesem Grund darf die SSL-Konfiguration zwar verändert, jedoch nicht entfernt werden.

SSL-Parameter

server:
   ssl:
      key-store: server.p12
      key-store-password: PASSWORD
      keyStoreType: PKCS12
      keyAlias: server

4.1. Unsignierte SSL-Zertifikate

Beim Crawling eines https-Servers kann der unten dargestellte Fehler auftreten. Er sagt aus, dass im Keystore kein gültiges Zertifikat eingetragen ist.

Möglicher Fehler bei unsigniertem SSL-Zertifikat

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

Für die Behebung des Fehlers ist das SSL-Zertifikat des gecrawlten https-Servers in den Keystore des SmartSearch-Servers einzubinden. Die Einbindung des Zertifikats erfolgt durch einen Download der Zertifikatsdatei, die der JRE mit dem keytool-Befehl hinzuzufügen ist.

Ein exemplarischer Aufruf für Mac OS sieht wie folgt aus:

Beispielaufruf

sudo keytool -import -alias BELIEBIGER_ALIAS -keystore /PFAD_ZUR_JAVA_JRE/lib/security/cacerts -file /PFAD/ZUM/ZERTIFIKAT/zertifikats.datei

Nach der erfolgreichen Einbindung des Zertifikats tritt der beschriebene Fehler nicht mehr auf und die Seite ist wie gewünscht crawlbar.

5. Monitoring

Monitoring dient der Überwachung von Prozessen, Abläufen und Zuständen. Dabei soll vor allem sichergestellt werden, dass der SmartSearch-Server weiterhin einwandfrei läuft und keine Ausfällen auftreten.

Auch die SmartSearch bietet für seinen eigenen Server diese Möglichkeit. Eine einfache Anbindung an Prometheus erlaubt die Erfassung und Auswertung der Serverdaten. Damit die Kommunikation zwischen Prometheus und der SmartSearch funktioniert, sind an beiden Enden kleinere Konfigurationen erforderlich.

Auf der Seite der SmartSearch muss in der application.yml der Key management.metric.export.prometheus.enabled auf true gesetzt werden.

Konfiguration des Keys

management:
   metrics:
      export:
         prometheus:
            enabled: true

Danach ist der Prometheus-Service unter folgender URL erreichbar:
smart-search-server:port/actuator/prometheus

Zuletzt muss der SmartSearch-Server Prometheus bekannt gemacht werden. Dies geschieht in der Konfigurationsdatei prometheus.yml und benötigt folgende Einstellungen:

Einstellungen

scrape_configs:
- job_name : smart-search
  metrics_path: /actuator/prometheus
  scheme: https
  basic_auth:
     username: USERNAME
     password: PASSWORD
  static_configs:
     - targets:
       - smart-search-server:PORT

5.1. Metriken

Um die Aktivität eines SmartSearch-Servers zu überwachen, erfasst Prometheus die sogenannten Metriken. Diese sind nach Durchführung der Konfiguration für das Monitoring auf dem Prometheus-Server verfügbar. Bei den Metriken handelt es sich um Parameter, die bestimmte Messgrößen des Servers beschreiben. Sie ermöglichen die Ableitung verschiedener Informationen über das Verhalten des SmartSearch-Servers und werden von Prometheus periodisch erfasst und gespeichert.

Interessant sind vor allem die JVM-Parameter, wie beispielsweise die Speichernutzung und die Anzahl der Threads. Weitere wichtige Metriken beinhalten die CPU-Auslastung oder die Performance von HTTP-Requests.

Abbildung 6. Prometheus-Metriken

5.2. Grafana

Die zusätzliche Konfiguration einer Grafana-Instanz erlaubt eine umfangreiche Visualisierung mit Dashboards. Grafana ist eine Software, die Werte aus Metriken in Graphen darstellt. Die Visualisierung der Werte bietet den Vorteil einer besseren Vergleichbarkeit. Informationen zur Installation und zum Start eines Grafana-Servers befinden sich auf der offiziellen Webseite.

Die Ergänzung des konfigurierten Prometheus-Servers als Datenquelle in der Grafana-Bedienoberfläche gestattet den Zugriff auf die von der SmartSearch bereitgestellten Metriken.

Abbildung 7. Grafana-Graphen

5.3. Solr-Prometheus-Exporter

Mit der Version 8 stellt Solr ebenfalls einen Prometheus-Exporter zur Verfügung. Dieser befindet sich im contrib-Unterordner des Solr-Installationsordners. Weitere Informationen zum Betrieb und zur Konfiguration des Exporters befinden sich in der offiziellen Dokumentation.

6. Update

Die Nutzung der Funktionen, Möglichkeiten sowie Leistungsanpassungen neuer SmartSearch-Versionen setzt regelmäßige Versionsupdates voraus. Mit diesen sind potenziell Änderungen sowohl innerhalb der Software der SmartSearch selbst als auch in den verbundenen ZooKeeper- sowie Solr-Instanzen notwendig. Bei ihnen handelt es sich vor allem um minimale Anpassungen des Solr-Schemas oder um Veränderungen an der ZooKeeper-Struktur, in der die SmartSearch Daten persistiert. Der Startparameter update ermöglicht eine automatische Übernahme dieser Änderungen bei einem Versionsupdate, indem er die Durchführung der benötigten Modifikationen innerhalb von ZooKeeper und Solr anstößt. Seine Verwendung ist ausschließlich dann notwendig, wenn während des Updateprozesses ein Exitcode 1 auftritt.

Ein SmartSearch-Update führt niemals ein automatisches Versionsupdate für ZooKeeper oder Solr durch.

Des Weiteren sind SmartSearch-Updates grundsätzlich rückwärtskompatibel und beeinträchtigen die Funktionsweise der SmartSearch-APIs soweit möglich nicht.

Sollte es in Ausnahmefällen zu Abweichungen von diesen beiden Punkten kommen, weisen die Releasenotes explizit darauf hin und sind jeweils vor der Durchführung eines Updates zu beachten. Dies gewährleistet, dass angebundene Systeme vorab auf eventuelle Anpassungen vorbereitet sind.

Aktualisierungen für SmartSearch können unter Crownpeak | e-Spirit Support angefragt werden..

Die Durchführung eines Versionsupdates erfolgt stets anhand der nachfolgenden Schritte:

Im ersten Schritt ist das neue SmartSearch-Archiv herunterzuladen und in einem beliebigen (leeren) Ordner des Zielsystems zu entpacken. Er enthält anschließend verschiedene Verzeichnisse und Dateien, von denen die folgenden potenziell für das Update relevant sind:
- application.yml
- server.conf
- server.jar
Je nach Einsatzszenario ist entweder im Einzelbetrieb dieser eine Knoten oder im Cluster-Betrieb ein einziger SmartSearch-Knoten herunterzufahren.
Vor der Durchführung weiterer Schritte sind zuerst die Releasenotes auf eventuelle Aktualisierungshinweise zu prüfen.
Falls die Releasenotes Aktualisierungshinweise enthalten, sind die in ihnen beschriebenen Änderungen an der application.yml beziehungsweise der server.conf durchzuführen.

Im Ausführungsverzeichnis der gestoppten Instanz muss anschließend sowohl die server.jar-Datei als auch das Verzeichnis shared_resources gegen die Datei beziehungsweise das Verzeichnis des entpackten Archivs ausgetauscht werden.

Verzeichnisse wie taglib oder documentation müssen nicht ersetzt werden, um die Funktionalität zu gewährleisten, sie dürfen aber ohne Risiko ebenfalls ersetzt werden.

Im letzten Schritt ist der zuvor gestoppte SmartSearch-Knoten wieder zu starten. Die Software prüft bei jedem Start automatisch, ob alle notwendigen Konfigurationen existieren. Ist dies nicht der Fall oder benötigen ZooKeeper beziehungsweise Solr zusätzliche Änderungen, gibt sie eine entsprechende Meldung aus und beendet sich mit einem Exitcode 1.

Im Fall eines Exitcodes 1 sind die Informationen über die noch fehlenden Anpassungen im Log des SmartSearch-Prozesses enthalten und diese entsprechend manuell durchzuführen.

Anschließend muss für den erneuten Start des SmartSearch-Knotens der update-Parameter verwendet werden (zum Beispiel ./server.jar update)

Die Software führt eine erneute Prüfung durch und nimmt notwendige Anpassungen an der Datenstruktur ZooKeepers oder Solrs automatisch vor. Diese Anpassungen werden ebenfalls im SmartSearch-Log festgehalten.

Nach der erfolgreichen Durchführung aller notwendigen Änderungen startet die Software wie gewohnt.

Startet die SmartSearch nach dem Aufruf mit dem Parameter update nicht erfolgreich, ist das SmartSearch-Log auf entsprechende Fehlermeldungen zu prüfen.

Im Cluster-Betrieb müssen die Schritte 3-6 anschließend für jeden SmartSearch-Knoten durchgeführt werden. Die Verwendung des update-Parameters ist in diesen Fällen ausschließlich dann notwendig, wenn die Releasenotes explizit darauf hinweisen.

7. Betrieb

Dieses Kapitel enthält Hinweise, die für den Betrieb der SmartSearch sowie der verbundenen Systeme notwendig sind.

7.1. Zurücksetzen des Master-Admin-Passworts

Beim initialen Start des SmartSearch-Servers wird der Master-Admin-Eintrag automatisch mit den Daten aus der application.yml erzeugt. Das Master-Admin-Passwort lässt sich danach jederzeit im SmartSearch-Cockpit ändern. Ein Start des SmartSearch-Servers mit dem optionalen Parameter resetAdminPassword setzt das Master-Admin-Passwort auf den Wert aus der application.yml zurück. Auf diesem Weg wird ein Aussperren aus dem SmartSearch-Cockpit verhindert.

8. Troubleshooting

Die Verarbeitung von Daten durch die SmartSearch kann nur funktionieren, wenn die einzelnen Komponenten einwandfrei arbeiten. Treten Störungen auf oder ist eine Aktualisierung notwendig, sind daher stets sowohl der SmartSearch-Server als auch alle ZooKeeper- und Solr-Server zu betrachten. Die nachfolgenden Abschnitte beschreiben einige Lösungsansätze für bekannte Herausforderungen.

Aktivierung von Spring-Boot-Actuatoren

Spring Boot liefert eine Reihe von Actuatoren mit, die in der default-Konfiguration der SmartSearch aktiviert sind. Mit diesen ist es möglich, zur Laufzeit einen Einblick in den Server zu bekommen. Die Actuatoren liefern zum Beispiel Informationen zum aktuellen Environment oder zu den Konfigurationen der verschiedenen Log-Level. Detaillierte Hintergrundinformationen zu den Actuatoren sind in der Spring-Boot-Actuatoren-Dokumentation zu finden.

Die Actuatoren stellen ihre Informationen über REST-Services zur Verfügung. Diese sind über eine http-Basic-Authentifizierung gesichert und benötigen valide Zugangsdaten eines Admin-Kontos.

Die nachfolgende Konfiguration aktiviert die default-Actuatoren-Endpunkte, deaktiviert allerdings explizit den heapdump-Endpunkt. Der heapdump-Endpunkt ermöglicht einen Download in GB-Größe, was eventuell in einer Produktionsumgebung nicht gewünscht ist.

Konfiguration für default-Endpunkte

management:
   endpoint:
      health:
         show-details: when-authorized
      metrics:
         enabled: true
      prometheus:
         enabled: true
   endpoints:
      web:
         exposure:
            include: "*"
            exclude:
               - "heapdump"
   metrics:
      export:
         prometheus:
            enabled: false
            descriptions: false

Die folgende URL stellt einen Überblick über die aktuellen Actuatoren-Endpunkte bereit.

Method: GET

URL: /actuator

Der Aufruf führt eine Basic-Authentifizierung mit einem Admin-Konto aus. Zu diesem Zweck kann der Nutzer aus der application.yml-Datei verwendet werden.

Mögliche Rückmeldung bei einer Abfrage der Actuatoren

{
   "_links": {
      "self": {
         "href": "https://smart-search-server:8181/actuator",
         "templated": false
      },
      "auditevents": {
         "href": "https://smart-search-server:8181/actuator/auditevents",
         "templated": false
      },
      "beans": {
         "href": "https://smart-search-server:8181/actuator/beans",
         "templated": false
      },
      "health": {
         "href": "https://smart-search-server:8181/actuator/health",
         "templated": false
      },
      "conditions": {
         "href": "https://smart-search-server:8181/actuator/conditions",
         "templated": false
      },
      [...]
      "mappings": {
         "href": "https://smart-search-server:8181/actuator/mappings",
         "templated": false
      }
   }
}

Verwendung der Logging-API zur Anpassung der Log-Level

Es existiert ein spezieller Spring-Boot-Actutator zum Umgang mit den Log-Einstellungen. Dieser ermöglicht die Anpassung der Log-Level zur Laufzeit. Der Aufruf der folgenden relativen URL auf einer SmartSearch-Instanz erzeugt die Ausgabe aller derzeit konfigurierten Log-Level:

Method: GET
URL: /actuator/loggers

Es besteht auch die Möglichkeit, Informationen zu einem speziellen Logger auszugeben:
Method: GET
URL: /actuator/loggers/<Logger>

Beispiel-URL zur Abfrage des Loggers de.arithnea.haupia.Server:
URL: /actuator/loggers/de.arithnea.haupia.Server

Der folgende Code-Ausschnitt zeigt eine mögliche Antwort des SmartSearch-Servers auf diese Abfrage.
Beispiel-Rückmeldung
```
{
   "configuredLevel": "INFO",
   "effectiveLevel": "INFO"
}
```
Die Anpassung eines Log-Levels wird durch einen POST-Request gegen eine konkrete Logger-URL ausgeführt. In diesem Request wird im JSON-Format das neue Log-Level übermittelt.
Method: POST
URL: /actuator/loggers/<Logger>

Der Body ist ein JSON-Objekt, das als Wert für den Key configuredLevel das gewünschte Log-Level besitzt.

Beispiel:
curl-Aufruf
```
$ curl 'https://smart-search-server:8181/actuator/loggers/de.arithnea.haupia.Server'
-i -u 'user:password' -X POST \
   -H 'Content-Type: application/json' \
   -d '{
      "configuredLevel" : "DEBUG"
   }'
```
Der zurückgegebene HTTP-Statuscode 204 bestätigt das erfolgreiche Setzen des Log-Levels.

Prometheus-Endpoint

Prometheus ist ein Tool für das Monitoring von Prozessen. Das Tool erfasst in regelmäßigen Abständen den Zustand eines Prozesses und erlaubt eine zeitliche Auswertung der Daten. Dies ermöglicht zum Beispiel, den Speicherverbrauch im Verhältnis zu den Anfragen an die REST-Services zu beobachten. Die SmartSearch liefert bereits vorkonfiguriert einen Prometheus-Endpunkt mit, der über die application.yml-Datei zu aktivieren ist. Für die Aktivierung ist folgender Key auf true zu setzen:

Beispiel für die Aktivierung des Prometheus-Endpunkts

management:
   metrics:
      export:
         prometheus:
            enabled: true

Anschließend ist unter folgender URL ein Endpoint verfügbar:

URL: /actuator/prometheus

Der Endpoint lässt sich in Prometheus zum Beispiel wie folgt einbinden:

Beispiel für die Einbindung des Endpoints in Prometheus

scrape_configs:
   - job_name: 'smart-search'
   metrics_path: '/actuator/prometheus'
   scheme: https
   basic_auth:
      username: admin@localhost.de
      password: admin
   static_configs:
      - targets: ['smart-search-server:8181']

9. DSGVO

Die Datenschutzgrundverordnung (DSGVO) ist eine EU-Verordnung, die das Grundrecht europäischer Bürger auf Privatsphäre schützt und den Umgang mit personenbezogenen Daten regelt. Vereinfacht gesagt, haben alle Personen, von denen Daten erhoben werden, über die DSGVO unter anderem die folgenden Möglichkeiten:

zu erfahren, welche personenbezogenen Daten von ihnen gespeichert und wie diese verarbeitet werden (Informationspflicht und Auskunftsrecht),
die Datenerhebung einzuschränken (Recht auf Einschränkung der Verarbeitung),
die erhobenen Daten zu beeinflussen (Recht auf Berichtigung) und
die erhobenen Daten zu löschen (Recht auf Vergessen).

Was sind personenbezogene Daten?

Personenbezogene Daten sind alle Informationen, durch die eine natürliche Person direkt oder indirekt identifizierbar ist. Dies schließt jegliche potenziellen Identifizierungsmerkmale ein:

direkte Identifizierungsmerkmale, wie etwa
- Namen
- E-Mail-Adressen
- Telefonnummern
indirekte Identifizierungsmerkmale, wie
- Standortdaten
- Kundennummern
- Personalnummern
Online-Identifizierungsmerkmale, wie zum Beispiel
- IP-Adressen
- Cookies
- Tracking Pixel

Ausführliche Informationen zur DSGVO finden sich im Blogpost DSGVO - Alles Wichtige auf einen Blick.

9.1. DSGVO und die SmartSearch

Die Such-Engine SmartSearch speichert Daten als Dokumente, die auf verschiedenen Plattformen zur Verfügung gestellt werden können. Art und Umfang der Daten, im Folgenden "erfasste Daten" genannt, sind abhängig vom Einsatzzweck des Produkts.

Der Hersteller Crownpeak Technology GmbH weist ausdrücklich darauf hin, dass es in der Verantwortung des Kundenunternehmens liegt, erfasste Daten daraufhin zu prüfen, ob sie personenbezogene Daten enthalten und entsprechende Maßnahmen sicherzustellen.

Neben den redaktionellen Daten speichert die SmartSearch personenbezogene Daten (grundsätzlich die E-Mail, bei Verwendung von LDAP den Username), die zur Anmeldung an dem System und beim Auditieren von Konfigurationen verwendet werden, um gegebenenfalls Kontakt mit der Person aufnehmen zu können, welche ein Element bearbeitet hat. Teile dieser Daten werden in Logdateien vorgehalten. Diese Daten werden im Folgenden „Personenbezogene Systemdaten“ genannt (siehe unten).

9.2. Personenbezogene Systemdaten in der SmartSearch

Die Crownpeak Technology GmbH nimmt den Schutz und die Sicherheit Ihrer Daten sehr ernst. Selbstverständlich halten wir uns an die gesetzlichen Datenschutzbestimmungen und behandeln personenbezogene Daten aber auch nicht-personenbezogene Daten unserer User mit entsprechender Sorgfalt. Wir erheben personenbezogene Daten nur dann, wenn sie für die Sicherheit und die Funktionsfähigkeit der SmartSearch notwendig sind.

Die nachfolgenden Unterkapitel informieren über die Erhebung von und den Umgang mit personenbezogenen Daten in der SmartSearch.

9.2.1. Daten zur User-Autorisierung und -Authentifizierung in der SmartSearch

Die SmartSearch arbeitet mit einem durchgängigen User- und Rechtesystem. Neue User werden über das Usermanagement angelegt und verwaltet. Nach der Erstellung sind User auf dem Server bekannt und können sich (mit einem gültigen Login) über das SmartSearch-Cockpit anmelden. Der Zugriff auf die Konfigurationselemente wird über Gruppenrechte/Rollen erteilt.

Warum werden die Daten benötigt?

Durch die Autorisierung und Authentifizierung ist sichergestellt, dass nur authentifizierte User Zugriff auf die SmartSearch erhalten und diese User Elemente nur gemäß der ihnen erteilten Rechte bearbeiten dürfen. Diese Daten sind für die Sicherheit der Informationen also zwingend erforderlich.

Wo werden die Daten verwendet beziehungsweise angezeigt?

User-Informationen werden an diversen Stellen angezeigt, zum Beispiel:

bei der Anmeldung am Cockpit
bei der Vergabe von Gruppenrechten
beim Ändern eines Objektes über die Auditierung
u. v. m.

Wo werden die Daten gespeichert?

User-Anmeldeinformationen werden grundsätzlich in der Konfigurationskomponente gespeichert. Im Falle von LDAP werden die personenbezogenen Systemdaten nur lesend aus dem LDAP des Kundenunternehmens geladen.

Wie lange werden die Daten gespeichert?

Bei der Entfernung von Usern über das Usermanagement werden die User-Anmeldeinformationen sofort aus der Konfigurationskomponente entfernt.

Die User-Deaktivierung im Usermanagement führt nicht zum Löschen der User-Daten.

9.2.2. Daten für die Fehleranalyse und Fehlerbehebung in der SmartSearch (Protokollierung)

Die SmartSearch verwendet Logfiles, um Aktionen und Ereignisse auf dem SmartSearch-Server zu protokollieren. Logfiles werden zur Aufrechterhaltung des sicheren Betriebs erhoben. Sie können verwendet werden, um Fehlerzustände zu analysieren und zu beheben.

Warum werden die Daten benötigt?: Einige der von der SmartSearch verwendeten Logfiles enthalten unter anderem IP-Adressen, Login-Namen, Datumsangaben, Uhrzeiten, Requests usw. und damit personenbezogene Daten.
Wo werden die Daten gespeichert?: Grundsätzlich werden Logfiles in das Unterverzeichnis logs des SmartSearch-Servers geschrieben.
Wie lange werden die Daten gespeichert?: Standardverhalten: Wird eine fest eingestellte Dateigröße von 100 MB erreicht, wird die aktuelle Logdatei archiviert. Es werden bis zu neun archivierte Dateien behalten. Wenn dann eine neue Datei archiviert wird, wird die älteste gelöscht. Dieses Verhalten kann über die Konfigurationsdatei logback-spring.xml angepasst werden.

9.2.3. Daten für die Auditierung von Konfigurationselementen

Bei jeder Änderung, die an Konfigurationselementen (zum Beispiel einer Prepared Search) vorgenommen werden, wird daran vermerkt, wer die letzte Änderung vorgenommen hat und wann. Damit wird eine eventuell bestehende letzte Änderung überschrieben.

Wird ein Konfigurationselement neu angelegt, wird daran vermerkt, wer das Element angelegt hat und wann.

Warum werden die Daten benötigt?: Eine Zielsetzung der Datenspeicherung in der SmartSearch ist die Nachvollziehbarkeit der letzten Änderungen, aber auch Informationen über die Erstellung von Konfigurationselementen. Dazu speichert die SmartSearch Auditierungsdaten.
Wo werden die Daten verwendet beziehungsweise angezeigt?: Die Auditierungsdaten (Wer hat eine Änderung durchgeführt und wann?) werden in Listenansichten für die Konfigurationselemente angezeigt.
Wo werden die Daten gespeichert?: Die Daten werden an den Konfigurationselementen in der Konfigurationkomponente gespeichert.
Wie lange werden die Daten gespeichert?: Standardverhalten: Bei der User-Löschung werden die zugehörigen Referenzen anonymisiert. Es ist zudem möglich, nachträglich Referenzen von bereits gelöschten Usern zu anonymisieren, für den Fall, dass bei der Löschung nicht das Standardverhalten angewandt wurde. Nach der Anonymisierung wird ein Bericht angezeigt, in welchen Elementen die Referenz anonymisiert wurde. Es werden dazu keine Informationen geloggt. Der Bericht ist die einzige Möglichkeit, Informationen über die Anonymisierung zu bekommen.

9.2.4. Verwendung von Cookies im Cockpit

Cookies sind Information, die im Browser des Betrachtenden zu einer besuchten Website gespeichert werden können.

Warum werden die Daten benötigt?: Die SmartSearch verwendet im Cockpit Cookies, um die Session zu speichern und zum Schutz vor XSRF-Attacken.
Wo werden die Daten verwendet bzw. angezeigt?: Die Cookies werden im Browser gespeichert und ab dem Einloggen mit jeder Interaktion mit dem Cockpit mitgeschickt.
Wie lange werden die Daten gespeichert?: Die Lebenszeit der Cookies wird auf session gesetzt.

10. Rechtliche Hinweise

Die SmartSearch ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.
Für die Verwendung des Produkts gilt nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

11. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.