1. Einleitung

Im Verlauf der Weiterentwicklung der SmartSearch ist es erforderlich, Anpassungen an der Konfiguration, dem Schema oder den verwendeten Komponenten vorzunehmen, die manuelle Änderungen erfordern.

Dieses Dokument beschreibt solche Migrationsszenarien.

Mit dem Update auf Version 2.4.0 wurde haupia in SmartSearch umbenannt. Es kann daher vorkommen, dass Code-Beispiele oder APIs noch den Begriff haupia enthalten.

2. SmartSearch-Update - Allgemein

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:

  1. 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

  2. Je nach Einsatzszenario ist entweder im Einzelbetrieb dieser eine Knoten oder im Cluster-Betrieb ein einziger SmartSearch-Knoten herunterzufahren.

  3. Vor der Durchführung weiterer Schritte sind zuerst die Releasenotes auf eventuelle Aktualisierungshinweise zu prüfen.

  4. Falls die Releasenotes Aktualisierungshinweise enthalten, sind die in ihnen beschriebenen Änderungen an der application.yml beziehungsweise der server.conf durchzuführen.

  5. 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.

  6. 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.

2.1. Troubleshooting

Innerhalb des Verlaufs eines Projekts können unterschiedliche Situationen auftreten, die bestimmte Handlungsschritte erfordern. Die nachfolgenden Abschnitte beschreiben aus diesem Grund einige Lösungsansätze für bekannte Herausforderungen.

Probleme beim Laden des Keystores

Das in der application.yml-Datei definierte Keystore-Passwort muss beim Serverstart zum verwendeten Keystore passen. Dies gilt auch, wenn der mitgelieferte Keystore für die Entwicklung eingesetzt wird. In diesem Fall ist das Passwort aus der ebenfalls mitgelieferten application.yml-Vorlage zu nutzen.

Bei der Verwendung eines falschen Passworts erscheint im Log die folgende Fehlermeldung:

Fehlermeldung bei falschem Keystore-Passwort 
org.springframework.context.ApplicationContextException: Unable to start web server; nested exception is java.lang.IllegalStateException: org.springframework.boot.web.server.WebServerException: Could not load key store './../shared_resources/keystore/keystore.p12'
...
Caused by: java.security.UnrecoverableKeyException: failed to decrypt safe contents entry: javax.crypto.BadPaddingException: Given final block not properly padded. Such issues can arise if a bad key is used during decryption.
        ... 20 common frames omitted

3. Migration auf Version 3.10.0

Mit der Version 3.10.0 wird ein neues dynamisches Feld *_date_range eingeführt. Dazu ist eine Änderung am Schema notwendig. Dies passiert automatisch, sofern der SmartSearch Server mit dem Parameter update gestartet wird. Details dazu sind im Kapitel SmartSearch-Update - Allgemein zu finden

4. Migration auf Version 3

Mit der SmartSearch-Version 3 wurde die verwendete Solr-Version von 8.1.1 auf 8.6.3 aktualisiert. Das nachfolgende Unterkapitel beschreibt das Vorgehen für das dadurch erforderliche Solr-Upgrade.

Dieses Vorgehen richtet sich nach der offiziellen Solr-Dokumentation. Nach dem Update werden die Collections reindexiert, um sie auf die neue Version umzustellen. Die SmartSearch-Auslieferung enthält daher das sogenannte Reindex-Tool, dessen Funktionsweise im nachfolgenden Kapitel beschrieben ist.

Eine Änderung an der application.yml der SmartSearch-Instanz ist nicht notwendig.

4.1. Reindex-Tool

Nach einem Solr-Update kann sich das Dateiformat des Index ändern. Um das neue Dateiformat zu übernehmen, ist eine Reindexierung der Daten- und Signals-Collection notwendig. Dabei hilft das Reindex-Tool. Es legt jeweils eine neue Collection an und kopiert die Daten aus der alten in die neue Collection. Abschließend überprüft das Tool die kopierten Daten und legt im Erfolgsfall einen Alias an, den die SmartSearch verwendet.

Während der Reindexierung kann die SmartSearch suchend verwendet werden, Datengeneratoren dürfen allerdings nicht laufen. Die abschließende Überprüfung der Daten stellt die Vollständigkeit der Daten-Collection sicher. Für die Signals-Collection kontrolliert sie dagegen lediglich, ob alle Signals in der neuen Collection denen in der alten Collection entsprechen. Dadurch kann es passieren, dass während der Laufzeit des Tools gespeicherte Signals verloren gehen.

Das Reindex-Tool muss auf den Solr-Server zugreifen können.

Die Verwendung des Reindex-Tools setzt die Extrahierung der entsprechenden zip-Datei aus der Auslieferung in ein Verzeichnis voraus. Die zip-Datei befindet sich im Verzeichnis tools der Auslieferung und der Name beginnt mit "reindex-tool". Die Anpassung der Konfiguration geschieht in der Datei reindex.properties. Dabei sind mindestens die folgenden Parameter anzupassen:

  • solr.url: Die URL auf einen Solr-Knoten. Zum Beispiel: http://solr1:8983/solr.

  • mandator: Der Company-Name aus der Lizenz. Zusätzlich muss auf dem Solr-Server eine dem Namen entsprechende Collection beziehungsweise ein dem Namen entsprechender Alias existieren.

Bei Bedarf ist die Konfiguration einer Authentifizierung möglich. Ein Beispiel ist in der properties-Datei enthalten.

Nach der erfolgreicher Konfiguration startet der folgende Befehl das Reindex-Tool:

Startbefehl 
java -jar reindex-tool.jar

4.2. Solr-Upgrade auf Version 8.6.3

Die folgende Beschreibung setzt voraus, dass die Solr-Installation in das Verzeichnis /opt erfolgt ist und die Daten im Verzeichnis /opt/solr-data liegen. Sie basiert außerdem auf der Annahme, dass die Steuerung aller Services mit systemd erfolgt und diese mit smartsearch, solr und zookeeper benannt sind.

Das Solr-Update erfordert einen Austausch des Schemas und der solrconfig.xml-Datei. Darüber hinaus ist die Variable MANDATOR durch den Kundennamen aus der Lizenz zu ersetzen.

Die nachfolgende Beschreibung geht von einem laufenden SmartSearch-Server und einem oder mehreren Solr- und ZooKeeper-Servern aus und gliedert sich in vier Schritte:

  • Solr-Upgrade

  • Einspielung der Konfigurationen der Daten-Collection

  • Einspielung der Konfigurationen der Signals-Collection

  • Abschluss der Migration.

Solr-Upgrade

  1. Laden Sie das Solr-Archiv in der Version 8.6.3 über die offizielle Webseite herunter.

  2. Entpacken Sie das Installations-/Upgrade-Skript:

    tar xzf solr-8.6.3.tgz solr-8.6.3/bin/install_solr_service.sh --strip-components=2

  3. Stoppen Sie sowohl den SmartSearch- als auch den Solr-Server und führen Sie anschließend das Installations-/Upgrade-Skript aus:

    sudo systemctl stop smart-search
sudo systemctl stop solr
sudo ./install_solr_service.sh solr-8.6.3.tgz -d /opt/solr-data -n -f

  4. Ändern Sie den Eigentümer und die Gruppe des erstellten symbolischen Links und des Ordners:

    sudo chown -R solr:solr /opt/solr
sudo chown -R solr:solr /opt/solr-8.6.3

  5. Ergänzen Sie das Skript zkCli.sh um das Ausführungsrecht, um die Konfiguration der Collection herunterzuladen:

    sudo chmod +x /opt/solr/server/scripts/cloud-scripts/zkcli.sh

Einspielung der Konfiguration der Daten-Collection

  1. Laden Sie die Konfiguration in das Verzeichnis /tmp/backup/SmartSearch herunter:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd downconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  2. Erstellen Sie ein Back-up der Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch.

  3. Ersetzen Sie die Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch durch die gleichnamigen Dateien aus dem Verzeichnis main aus der zip-Datei des Reindex-Tools.

  4. Laden Sie die neue Konfiguration hoch:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  5. Löschen Sie den zuvor erstellten Ordner /tmp/backup/SmartSearch. Die in ihm enthaltenen Daten werden nicht mehr benötigt.

    rm -rf /tmp/backup/SmartSearch

Einspielung der Konfiguration der Signals-Collection

  1. Laden Sie die signals-Konfiguration in das Verzeichnis /tmp/backup/SmartSearch herunter:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd downconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR_signals

  2. Erstellen Sie ein Back-up der Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch.

  3. Ersetzen Sie die Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch durch die gleichnamigen Dateien aus dem Verzeichnis signals aus der zip-Datei des Reindex-Tools.

  4. Laden Sie die neue Konfiguration hoch:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR_signals

  5. Löschen Sie den zuvor erstellten Ordner /tmp/backup/SmartSearch. Die in ihm enthaltenen Daten werden nicht mehr benötigt.

    rm -rf /tmp/backup/SmartSearch

Abschluss der Migration

  1. Starten Sie sowohl den Solr- als auch den SmartSearch-Server sowie das Reindex-Tool. Ab jetzt sind wieder Suchabfragen ausführbar. Der Befehl setzt die zuvor ausgeführte Konfiguration des Tools voraus.

    sudo systemctl start solr
sudo systemctl start smart-search
java -jar reindex-tool.jar

  2. Ermitteln Sie im Solr-Backend die Namen der neuen Collections für Daten und Signals.

  3. Überprüfen Sie, ob der Status beider Collections den Wert healthy besitzt. Im folgenden Aufruf setzt der Parameter -c den Namen der Collection.

    /opt/solr/bin/solr healthcheck -c MANDATOR_20210902141120 -z localhost:2181/solr

5. Migration auf Version 2.3.0

Die SmartSearch-Version 2.3.0 enthält ein internes Update von Spring Boot auf 2.3.8. Im Zuge dieses Upgrades sind einige Konfigurationsanpassungen in der application.yml-Datei notwendig. Die Anpassungen beziehen sich auf die Umbenennung der weiter unten aufgeführten Schlüssel. Weitere Details sind in den Spring Boot 2.3 Release Notes aufgeführt.

Die folgende Liste zeigt die Schlüssel, die umbenannt werden müssen, sowie ihre neuen Namen.

Tabelle 1. Table Alte und neue Konfigurationsschlüssel

Alter Key Name

Neuer Key Name

spring.http.encoding.charset

server.servlet.encoding.charset

spring.http.encoding.enabled

server.servlet.encoding.enabled

spring.http.encoding.force

server.servlet.encoding.force

6. Migration auf Version 2.2.0

Um die neuen Features der SmartSearch-Version 2.2.0 nutzen zu können, sind Anpassungen an der Solr-Konfiguration erforderlich. Daher muss die neue Konfiguration nach dem Update manuell auf den Solr-Server hochgeladen werden. Führen Sie dazu folgenden Befehl im SmartSearch-Installationsverzeichnis aus. Ersetzen Sie dabei den Platzhalter MANDATOR durch den Mandantennamen - in der Schreibweise, wie er der Lizenzdatei eingetragen ist.

Der Befehl basiert auf der Annahme, dass die Solr-Installation in das Verzeichnis /opt erfolgt ist. Sollte das nicht der Fall sein, sind die Pfade entsprechend anzupassen.
Update-Befehl 
/opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir ./shared_resources/configsets/SmartSearch -confname MANDATOR

Um zu verifizieren, ob die Übertragung erfolgreich war, können Sie sich mit der Solr-Weboberfläche verbinden. Diese ist über den Aufruf der URL localhost:8983 in Ihrem Browser erreichbar. Die Weboberfläche enthält am linken Rand zwei Dropdown-Boxen. Selektieren Sie in der oberen Box die Collection mit Ihrem Mandantennamen und klicken Sie in der folgenden Ordneransicht auf Files. Wählen Sie dann ganz unten in der Liste den Eintrag managed-schema aus, um rechts den Inhalt der ausgewählten Datei im XML-Format zu sehen. Wenn in der zweiten Zeile das Attribut version den Wert 2.1 zeigt, war die Übertragung erfolgreich.

Falls bei einer Prepared Search Gruppierung verwendet wird, ist zu beachten, dass Felder mit dem Suffix _keyword vom neuen Schema nicht mehr unterstützt werden. Stattdessen sollten Felder mit dem Suffix _token verwendet werden.

7. Migration auf Version 2.1.0

Mit der SmartSearch-Version 2.1.0 wurde die verwendete Solr-Version auf 8.1.1 aktualisiert. Die nachfolgenden Unterkapitel beschreiben das Vorgehen für das dadurch erforderliche Solr-Upgrade.

Dieses Vorgehen richtet sich nach der offiziellen Solr-Dokumentation. Nach dem Update werden die Collections reindexiert, um sie auf die neue Version umzustellen. Die SmartSearch-Auslieferung enthält daher das sogenannte Reindex-Tool, dessen Funktionsweise im nachfolgenden Kapitel beschrieben ist.

Darüber hinaus benötigt die SmartSearch ab dieser Version Java 11. Ältere Java-Versionen werden nicht mehr unterstützt. Im Rahmen der Migration ist die Aktualisierung der Java-Version nach dem Upgrade der Solr-Version 6 auf 7 durchzuführen.

Eine Änderung an der application.yml der SmartSearch-Instanz ist nicht notwendig.

7.1. Reindex-Tool

Nach einem Solr-Update kann sich das Dateiformat des Index ändern. Um das neue Dateiformat zu übernehmen, ist eine Reindexierung der Daten- und Signals-Collection notwendig. Dabei hilft das Reindex-Tool. Es legt jeweils eine neue Collection an und kopiert die Daten aus der alten in die neue Collection. Abschließend überprüft das Tool die kopierten Daten und legt im Erfolgsfall einen Alias an, den die SmartSearch verwendet.

Während der Reindexierung kann die SmartSearch suchend verwendet werden, Datengeneratoren dürfen allerdings nicht laufen. Die abschließende Überprüfung der Daten stellt die Vollständigkeit der Daten-Collection sicher. Für die Signals-Collection kontrolliert sie dagegen lediglich, ob alle Signals in der neuen Collection denen in der alten Collection entsprechen. Dadurch kann es passieren, dass während der Laufzeit des Tools gespeicherte Signals verloren gehen.

Das Reindex-Tool muss auf den Solr-Server zugreifen können.

Die Verwendung des Reindex-Tools setzt die Extrahierung der entsprechenden zip-Datei aus der Auslieferung in ein Verzeichnis voraus. Die zip-Datei befindet sich im Verzeichnis tools der Auslieferung und der Name beginnt mit "reindex-tool". Die Anpassung der Konfiguration geschieht in der Datei reindex.properties. Dabei sind mindestens die folgenden Parameter anzupassen:

  • solr.url: Die URL auf einen Solr-Knoten. Zum Beispiel: http://solr1:8983/solr.

  • mandator: Der Company-Name aus der Lizenz. Zusätzlich muss auf dem Solr-Server eine dem Namen entsprechende Collection beziehungsweise ein dem Namen entsprechender Alias existieren.

Bei Bedarf ist die Konfiguration einer Authentifizierung möglich. Ein Beispiel ist in der properties-Datei enthalten.

Nach der erfolgreicher Konfiguration startet der folgende Befehl das Reindex-Tool:

Startbefehl 
java -jar reindex-tool.jar

7.2. Solr-Upgrade auf Version 7.7.3

Die folgende Beschreibung setzt voraus, dass die Solr-Installation in das Verzeichnis /opt erfolgt ist und die Daten im Verzeichnis /opt/solr-data liegen. Sie basiert außerdem auf der Annahme, dass die Steuerung aller Services mit systemd erfolgt und diese mit smartsearch, solr und zookeeper benannt sind.

In der Solr-Version 7 wurde das ukrainian.dict, das die Analyse der ukrainischen Sprache ermöglicht, entfernt. Die nachfolgenden Schritte beschreiben die notwendigen Änderungen, um das Schema entsprechend anzupassen. In den Shell-Anweisungen bezeichnet der Platzhalter MANDATOR den Mandantennamen in der Schreibweise, wie er in die Lizenzdatei eingetragen ist.

Ausgehend von einem laufenden SmartSearch-Server und einem oder mehreren Solr- und ZooKeeper-Servern sind die folgenden Schritte auszuführen:

  1. Laden Sie das Solr-Archiv in der Version 7.7.3 über die offizielle Webseite herunter.

  2. Entpacken Sie das Installations-/Upgrade-Skript:

    tar xzf solr-7.7.3.tgz solr-7.7.3/bin/install_solr_service.sh --strip-components=2

  3. Stoppen Sie sowohl den SmartSearch- als auch den Solr-Server und führen Sie anschließend das Installations-/Upgrade-Skript aus:

    sudo systemctl stop smart-search
sudo systemctl stop solr
sudo ./install_solr_service.sh solr-7.7.3.tgz -d /opt/solr-data -n -f

  4. Ändern Sie den Eigentümer und die Gruppe des erstellten symbolischen Links und des Ordners:

    sudo chown -R solr:solr /opt/solr
sudo chown -R solr:solr /opt/solr-7.7.3

  5. Ergänzen Sie das Skript zkCli.sh um das Ausführungsrecht, um die Konfiguration der Collection herunterzuladen:

    sudo chmod +x /opt/solr/server/scripts/cloud-scripts/zkcli.sh

  6. Laden Sie die Konfiguration in das Verzeichnis /tmp/backup/SmartSearch herunter:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd downconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  7. Erstellen Sie ein Back-up der Datei managed-schema im Verzeichnis /tmp/backup/SmartSearch.

  8. Passen Sie das Schema folgendermaßen an, um den Filter für die ukrainische Sprache auszukommentieren:

    sed -i 's/<filter class="solr\.MorfologikFilterFactory" dictionary="org\/apache\/lucene\/analysis\/uk\/ukrainian.dict" \/>/<!-- filter class="solr.MorfologikFilterFactory" dictionary="org\/apache\/lucene\/analysis\/uk\/ukrainian.dict" \/ -->/' /tmp/backup/SmartSearch/managed-schema

  9. Laden Sie die neue Konfiguration hoch:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  10. Löschen Sie den zuvor erstellten Ordner /tmp/backup/SmartSearch:

    rm -rf /tmp/backup/SmartSearch

  11. Starten Sie sowohl den Solr- als auch den SmartSearch-Server sowie das Reindex-Tool. Ab jetzt sind wieder Suchabfragen ausführbar.

    sudo systemctl start solr
sudo systemctl start smart-search
java -jar reindex-tool.jar

  12. Ermitteln Sie im Solr-Backend die Namen der neuen Collections für Daten und Signals.

  13. Überprüfen Sie, ob der Status beider Collections den Wert healthy besitzt. Im folgenden Aufruf setzt der Parameter -c den Namen der Collection.

    /opt/solr/bin/solr healthcheck -c MANDATOR_20200612141120 -z localhost:2181/solr

7.3. Solr-Upgrade auf Version 8.1.1

Ab der Version 2.1.0 benötigt die SmartSearch Java 11. Aus diesem Grund muss ab dieser Stelle Java in der Version 11 gewährleistet sein. Ältere Java-Versionen werden nicht mehr unterstützt.

Die folgende Beschreibung setzt voraus, dass die Solr-Installation in das Verzeichnis /opt erfolgt ist und die Daten im Verzeichnis /opt/solr-data liegen. Sie basiert außerdem auf der Annahme, dass die Steuerung aller Services mit systemd erfolgt und diese mit smartsearch, solr und zookeeper benannt sind.

Mit dem Wechsel auf die Solr-Version 8 erfolgte eine Konfigurationsanpassung der Collections, deren Namen für die Migration erforderlich sind: Für die Daten-Collection entspricht dieser dem Company-Namen aus der Lizenz, der nachfolgend als Mandant oder Mandator bezeichnet ist. Der Name für die Signals-Collection setzt sich aus dem Mandanten und dem Suffix _signals zusammen.

Die nachfolgende Beschreibung geht von einem laufenden SmartSearch-Server und einem oder mehreren Solr- und ZooKeeper-Servern aus und gliedert sich in vier Schritte:

  • Solr-Upgrade

  • Einspielung der Konfiguration der Daten-Collection

  • Einspielung der Konfiguration der Signals-Collection

  • Abschluss der Migration.

Solr-Upgrade

  1. Laden Sie das Solr-Archiv in der Version 8.1.1 über die offizielle Webseite herunter.

  2. Entpacken Sie das Installations-/Upgrade-Skript:

    tar xzf solr-8.1.1.tgz solr-8.1.1/bin/install_solr_service.sh --strip-components=2

  3. Stoppen Sie sowohl den SmartSearch- als auch den Solr-Server und führen Sie anschließend das Installations-/Upgrade-Skript aus:

    sudo systemctl stop smart-search
sudo systemctl stop solr
sudo ./install_solr_service.sh solr-8.1.1.tgz -d /opt/solr-data -n -f

  4. Ändern Sie den Eigentümer und die Gruppe des erstellten symbolischen Links und des Ordners:

    sudo chown -R solr:solr /opt/solr
sudo chown -R solr:solr /opt/solr-8.1.1

  5. Ergänzen Sie das Skript zkCli.sh um das Ausführungsrecht, um die Konfiguration der Collection herunterzuladen:

    sudo chmod +x /opt/solr/server/scripts/cloud-scripts/zkcli.sh

Einspielung der Konfiguration der Daten-Collection

  1. Laden Sie die Konfiguration in das Verzeichnis /tmp/backup/SmartSearch herunter:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd downconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  2. Erstellen Sie ein Back-up der Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch.

  3. Ersetzen Sie die Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch durch die gleichnamigen Dateien aus dem Verzeichnis main aus der zip-Datei des Reindex-Tools.

  4. Laden Sie die neue Konfiguration hoch:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR

  5. Löschen Sie den zuvor erstellten Ordner /tmp/backup/SmartSearch. Die in ihm enthaltenen Daten werden nicht mehr benötigt.

    rm -rf /tmp/backup/SmartSearch

Einspielung der Konfiguration der Signals-Collection

  1. Laden Sie die signals-Konfiguration in das Verzeichnis /tmp/backup/SmartSearch herunter:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd downconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR_signals

  2. Erstellen Sie ein Back-up der Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch.

  3. Ersetzen Sie die Dateien managed-schema und solrconfig.xml im Verzeichnis /tmp/backup/SmartSearch durch die gleichnamigen Dateien aus dem Verzeichnis signals aus der zip-Datei des Reindex-Tools.

  4. Laden Sie die neue Konfiguration hoch:

    /opt/solr/server/scripts/cloud-scripts/zkcli.sh -zkhost localhost:2181/solr -cmd upconfig -confdir /tmp/backup/SmartSearch -confname MANDATOR_signals

  5. Löschen Sie den zuvor erstellten Ordner /tmp/backup/SmartSearch. Die in ihm enthaltenen Daten werden nicht mehr benötigt.

    rm -rf /tmp/backup/SmartSearch

Abschluss der Migration

  1. Starten Sie sowohl den Solr- als auch den SmartSearch-Server sowie das Reindex-Tool. Ab jetzt sind wieder Suchabfragen ausführbar. Der Befehl setzt die zuvor ausgeführte Konfiguration des Tools voraus.

    sudo systemctl start solr
sudo systemctl start smart-search
java -jar reindex-tool.jar

  2. Ermitteln Sie im Solr-Backend die Namen der neuen Collections für Daten und Signals.

  3. Überprüfen Sie, ob der Status beider Collections den Wert healthy besitzt. Im folgenden Aufruf setzt der Parameter -c den Namen der Collection.

    /opt/solr/bin/solr healthcheck -c MANDATOR_20200612141120 -z localhost:2181/solr

8. Migration auf Version 2.0.62

Die SmartSearch-Version 2.0.62 enthält ein internes Update von Spring Boot 1 auf 2. Dieses Update erleichtert zukünftig den SmartSearch-Betrieb. Ein Beispiel ist die Möglichkeit, den SmartSearch-Server durch einen Prometheus-Endpoint zu monitoren.

Dieses Major-Version-Upgrade erfordert einige Konfigurationsanpassungen in der application.yml-Datei. Weitere Details sind im Spring-Boot 2-Migrationsguide aufgeführt. Zusätzlich erfolgte eine Verbesserung der Struktur der application.yml-Datei.

Die folgende Liste zeigt die Änderungen an der application.yml:

Entfernung des Keys cache-period

Der Key spring.resources.cache-period in der application.yml definiert den cache control max age-Wert für statische Dateien (zum Beispiel JS oder CSS). Dieser Key wird nicht mehr benötigt und ist in der Konfiguration nicht mehr enthalten.

Exklusion von Autokonfigurationen

Im Spring-Kontext ist sowohl das MongoDB-Modul als auch der MongoDB-Treiber vorerst deaktiviert. Die MongoDB-spezifischen Autokonfigurationen werden dadurch nicht mehr benötigt und ihre Aktivierung muss exkludiert werden. Dazu ist die application.yml um folgende Keys zu erweitern:

Keys für die Exklusion der MongoDB-Autokonfigurationen 
spring:
   autoconfigure:
      exclude:
      - org.springframework.boot.autoconfigure.mongo.embedded.EmbeddedMongoAutoConfiguration
      - org.springframework.boot.autoconfigure.mongo.MongoAutoConfiguration
      - org.springframework.boot.autoconfigure.data.mongo.MongoDataAutoConfiguration
      - org.springframework.boot.autoconfigure.data.mongo.MongoRepositoriesAutoConfiguration
UTF-8-Datei-Enkodierung

Der problemlose Serverbetrieb setzt eine Datei-Enkodierung von UTF-8 voraus. Die Konfiguration bewirkt eine beim Start durchgeführte Prüfung, ob der Java-Parameter file.encoding auf UTF-8 gesetzt ist. Ist dies nicht der Fall, erfolgt ein Abbruch des Starts. Für die Definition des Parameters ist die application.yml um den folgenden Key zu erweitern:

Key für die UTF-8 Datei-Enkodierung 
spring:
   mandatory-file-encoding: UTF-8
UTF-8 für die Kommunikation mit dem Server

Um Problemen beim Serverbetrieb vorzubeugen, ist eine HTTP-Kommunikation mit UTF-8 sicherzustellen. Dazu ist die application.yml um folgende Keys zu erweitern:

Keys für die Kommunikation mit UTF-8 
spring:
   http:
      encoding:
         charset: UTF-8
         enabled: true
         force: true
Deaktivierung von Spring Session

Aufgrund einer derzeit fehlenden Verwendung ist Spring Session deaktivierbar. Die Deaktivierung erfordert die Anpassung des Keys spring.session.store-type, dessen Wert von hash-map auf none zu ändern ist.

Konfiguration der Actuatoren

Die Konfigurationen der Actuatoren haben sich grundlegend geändert. Das Changelog von Spring Boot 2 listet dazu die Details auf.

Der alte Key in der application.yml findet keine Berücksichtigung mehr und ist daher nicht mehr vorhanden:

Veralteter Key für die Actuatoren 
management:
   contextPath: /api/boot

Es wird empfohlen die Konfiguration der Actuatoren neu aufzusetzen.

9. Migration von Version 1.9 auf 2.0

Mit der SmartSearch-Version 2 haben sich im Vergleich zu Version 1 Basistechnologien geändert, die einige manuelle Schritte notwendig machen. Dies ermöglicht einige Features, die für moderne Enterprise-Software notwendig sind, zum Beispiel Hot Standby.

Dieses Kapitel beschreibt die erforderlichen Schritte für die Migration der Konfigurationen aus Version 1 in die Version 2. Wenn die aktuelle Version einer Version vor 1.9.x entspricht, muss erst ein Update auf diese Version erfolgen.

Die Migration setzt voraus, dass eine alte und neue SmartSearch-Instanz existieren und auf beiden Instanzen der Zugang sowohl zum SmartSearch-Cockpit als auch zum Dateisystem möglich ist. Die neue SmartSearch-Instanz ist bereits einmal gestartet und damit sind alle notwendigen Daten im ZooKeeper und Solr initialisiert.

9.1. Wichtige Änderungen in der Version 2

Mit der Version 2 erfolgte eine Umstellung des zuvor embedded verwendeten Solr-Server auf einen externen Server. Dieser muss im sogenannten Cloud-Modus laufen. Durch diese Änderung ist es möglich, alle Komponenten redundant zu betreiben und damit ausfallsicher aufzusetzen.

Das verwendete Solr-Schema ist grundlegend überarbeitet. Es besitzt nun beispielsweise für jede unterstütze Sprache ein eigenes Feld, um den Inhalt sprachenspezifisch zu verarbeiten. In der Suchabfrage ist das transparent. Wenn zum Beispiel das Feld title einer Prepared Search zur Durchsuchung definiert ist, berücksichtigt die eigentliche Suchabfrage die Felder aller vorhandenen Sprachvarianten, gibt am Ende aber nur den Wert als title zurück. Dadurch muss die verwendete Sprache bei der Auswertung der Antwort der Prepared Search-REST-API nicht bekannt sein, was die Integration erheblich erleichtert.

Weiter ist es ist nicht länger möglich, die REST-Services ohne User-Credentials zu benutzen. Dafür ist die Erzeugung eines technischen Users sinnvoll. Zusätzlich verwendet die REST-API nun HTTPS, um die Sicherheit weiter zu erhöhen.

9.2. Datengenerator und Prepared Search

Mit der SmartSearch-Version 2 hat sich der Speicherort der Konfiguration von einer lokalen Datenbank zum ZooKeeper geändert. Aus diesem Grund ist eine Übernahmen der bestehenden Konfiguration nach ZooKeeper erforderlich. Die Übernahme der bestehenden Konfigurationen für Datengeneratoren und Prepared Searches erfordert die folgenden manuellen Schritte.

Im SmartSearch-Cockpit der Version 1.9.x ermöglicht der Button Exportiere Datengeneratoren-Konfiguration auf der Datengeneratoren-Seite den Download der aktuellen Datengeneratoren-Konfiguration. Analog ermöglicht der Button Export Prepared Searches Config auf der Prepared Search-Listenseite den Download der aktuellen Prepared Search-Konfiguration. Die erwarteten Namen der beiden Dateien sind datagenerators.xml und preparedsearches.xml.

Der Import erwartet beide Dateien im SmartSearch 2 Verzeichnis im Ordner migration. Der optionale Key haupia.migration.path in der application.yml definiert einen alternativen Pfad. Sind die Dateien im richtigen Verzeichnis vorhanden und ist die SmartSearch gestartet, wird die Migration geloggt.

Die importierte Konfiguration erfordert eine Überprüfung der Daten im SmartSearch-Cockpit auf Vollständigkeit. Nachdem die Migration abgeschlossen ist, werden die Migrationsdateien nicht mehr benötigt und sind daher zu entfernen.

Die Migration der Prepared Searches und Datengeneratoren prüft, ob bereits Konfigurationen mit den Namen existieren und überschreibt diese nicht.

Da sich Prepared Searches und Datengeneratoren gegenseitig referenzieren, ist zur Vermeidung invalider Zwischenstände ein paralleler Import aller Prepared Searches und Datengeneratoren ratsam.

9.3. Stoppwörter

Die Version 1.9.x speicherte die Stoppwörter in der Datei stopwords.txt im SmartSearch-Verzeichnis unter solr/core0/conf. Die neue Version wechselt von einer globalen Stoppwörter-Datei zu einer Konfiguration pro Sprache, die jeweils im ZooKeeper gespeichert ist. Die Migration geht davon aus, dass die ehemals globalen Stoppwörter Daten einer Sprache zuzuordnen sind. Die folgende Beschreibung migriert die Stoppwörter in die Sprache Deutsch (de).

Die Speicherung der Stoppwörter im ZooKeeper ermöglicht allen Solr-Knoten den Zugriff auf die Daten. Dieses Vorgehen wird als Managed Resources bezeichnet. Die Benamung der Managed Resources nimmt die SmartSearch auf Basis des Präfixes stopwords_general_ und des Sprachkürzels vor. Im Fall der deutschen Sprache ergibt sich daraus der Name stopword_general_de. Die folgende URL liefert die aktuellen Stoppwörter für diese Managed Resource:

http://SOLR_URL:8983/solr/COMPANY/schema/analysis/stopwords/stopwords_general_de

Das COMPANY in der URL ist ein Platzhalter für den Company-Namen aus der Lizenz.

Die Speicherung als Managed Resource setzt eine Konvertierung der globalen Daten in JSON voraus.

Das folgende Beispiel zeigt den Inhalt einer globalen Stoppwörter-Datei:

Stoppwörter-Datei 
der
die
das

Der erste Schritt der Konvertierung ist die Entfernung aller Zeilen, die mit # beginnen. Das Resultat ist eine Textliste, deren Einträge alle zu einem Eintrag in einer JSON-Liste wird.

Aus dem Beispiel ergibt sich folgendes JSON:

JSON-Liste 
["der",
"die",
"das"]

Die Speicherung dieser JSON-Liste geschieht mit einem PUT-Aufruf der URL der Managed Resource.

Der Import ersetzt keine bereits vorhandenen Daten, sondern ergänzt diese.

Beim PUT-Aufruf ist auch der Header Content-type:application/json zu setzen.

9.4. Synonyme

Analog zu den Stoppwörtern erfolgte auch für die Synonyme eine Umstellung auf Managed Resources. Ein einfacher Export- und Import-Vorgang wie bei den Stoppwörtern ist in diesem Fall leider nicht möglich, da die Art und Weise des Handlings von Synonymen auf Solr-Seite komplexer ist. Daher ist die Pflege über das SmartSearch-Cockpit auf der Seite der Synonyme für jede Sprache manuell vorzunehmen.

9.5. Taglib

Die neue Version hat die Taglib so weit wie möglich übernommen. Die Umstellung der REST-Services von HTTP auf HTTPS und die Authentifizierung machen jedoch Änderungen am context-Tag notwendig. Das Tag besitzt nun Attribute, um den Username und das Passwort zu übergeben. Die im propertyContext-Tag referenzierte Property-Datei enthält darüber hinaus weitere Felder zur Definition der Zugangsdaten.

Das context-Tag verwaltet die Definition des SmartSearch-REST-Endpunkts nicht mehr über die Parameter server, path und port, sondern vereint diese zum Parameter haupiaServer. Es gibt nun auch den optionalen Parameter ignoreSslErrors, der Validierungen des SSL-Zertifikats ignoriert und dessen Verwendung ausschließlich im Entwicklungskontext sinnvoll ist.

Der folgende Code-Block zeigt das context-Tag in der bisherigen Verwendung sowie die vorzunehmende Anpassung:

context-Tag 
// bisherige Variante
<haupia:context server="localhost" path="haupia" port="8080">
</haupia:context>

// vorzunehmende Anpassung
<haupia:context user="admin@host.de" password="s3cret" haupiaServer="https://foo.de:8181">
</haupia:context>

Das Tag propertyContext beziehungsweise die benötigten Daten in der referenzierten Property-Datei ändern sich analog .

9.6. JAVA-API

Die Java-API hat sich grundlegend geändert. Um die gestiegenen Komplexitäten der Abfragen abzubilden, besteht die API nun aus Fluid-Buildern anstelle von statischen Methodenaufrufen. Zusätzlich kommen neue externe Abhängigkeiten hinzu.

Das folgende Beispiel beinhaltet die einfachste Variante zur Abfrage einer Prepared Search und zeigt einen Vergleich zwischen dem alten und neuen Ansatz.

JAVA-API-Variante 
// bisherige Variante
final String haupiaRestBaseUrl = "http://localhost:8080/haupia-backend-3_0/service";
final String preparedSearchName = "preparedSearchName";
final String query = "*:*";
final HaupiaResult result = PreparedSearch.execute(haupiaRestBaseUrl, preparedSearchName, query);

// neue fluide Variante
final String preparedSearchName = "preparedSearchName";
final String query = "*:*";
final PreparedSearch preparedSearch = new PreparedSearchBuilder(preparedSearchName).query(query).build();
final PreparedSearchResponse response = PreparedSearchExecutor.execute(this.serverUri, preparedSearch, "user", "password");

9.7. Externe Datengenerator REST-API

Damit die API externer Datengeneratoren unabhängig von der verwendeten Programmiersprache ist, wurde die Java-Unterstützung für den externen Datengenerator entfernt. Gleichzeitig besitzt die REST-API für die externen Datengeneratoren ab Version 2 Eigenschaften, um diese mit beliebigen Programmiersprachen verwenden zu können. Die Dokumentation für die neue API befindet sich in einem eigenen Dokument.

9.8. JSON-Response der Prepared Search

Im Gegensatz zur Version 1.9.x liefert eine Prepared Search in Version 2 nicht mehr das JSON des SLR-Servers als Antwort zurück. Stattdessen führt die Version 2 ein neues JSON-Format ein, das eine Anpassung der Verwendung des JSONs erforderlich macht. Das neue Format ist zum einen einfacher lesbar und zum anderen war mit der Einführung der i18n-Unterstützung eine Überarbeitung der Felder notwendig. Die wichtigsten Unterschiede sind im Folgenden aufgelistet.

Die gefundenen Dokumente befinden sich an einer anderen Stelle.

gefundene Dokumente 
// alte Version: Dokumente unter response/docs
{
   "response": {
      "docs": [
         {
            "[elevated]": false,
            "uid": "WEBCRAWLER.haupia:1758918fda5f8e63b7ef26f7c88e4ffd",
            "_storage": "WEBCRAWLER.haupia",
            "link": "...",
            "title": "..."
         },...
      ]
   }
   ...
}

// neue Version: Dokumente direkt unter results
{
   "results": [
      {
         "[elevated]": false,
         "uid": "WEBCRAWLER.haupia:1758918fda5f8e63b7ef26f7c88e4ffd",
         "_storage": "WEBCRAWLER.haupia",
         "link": "...",
         "title": "..."
      },...
   ]
   ...
}

Die Gesamtzahl der Ergebnisse befindet sich an einer anderen Stelle.

Gesamtzahl der Ergebnisse 
// alte Version: Gesamtzahl der Ergebnisse unter response/numFound
{
   "response": {
      "numFound": 92
   }
   ...
}

// neue Version: Gesamtzahl der Ergebnisse unter numRows
{
   "numRows": 92
   ...
}

Da sich die Konfiguration der Felder grundlegend geändert hat, kann es zu abweichenden Rückgabewerten kommen: Felder, wie beispielsweise der title, können als einfacher Wert oder Array zurückgegeben werden. Dies hängt davon ab, wie viele Werte das Feld besitzt.

Das neue Format in der Version 2 vereinfacht die Rückgabeliste mit den Facetten-Einträgen. Die zusätzliche Rückgabe des Keys filterQuery ermöglicht außerdem die Anwendung des entsprechenden Filters auf den Eintrag.

Facette 
// alte Version: Beispiel einer Facette
"facet_counts": {
   "facet_fields": {
      "keywords_facet_string": [
         "Content Management",
         32,
         "Digital Marketing",
         32
      ]
   }
}

// neue Version: einfachere Darstellung einer Facette
{
   "facets": [
      {
         "name": "keywords_facet_string",
         "counts": [
            {
               "value": "Content Management",
               "count": 32,
               "filterQuery": "keywords_facet_string:Content\\ Management"
            },
            {
               "value": "Digital Marketing",
               "count": 32,
               "filterQuery": "keywords_facet_string:Digital\\ Marketing"
            }
         ]
      }
   ]
}

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.