Wie du Solr mit DDEV und TYPO3 v10 in deine lokale Entwicklungsumgebung integrierst

Viele unserer Kunden benötigen eine leistungsstarke Suchfunktion auf ihren Websites. TYPO3 stellt sich dieser Herausforderung, indem es die Integration der Solr-Suche denkbar einfach macht. Wir setzen auf die Solr-Extension von dkd, um leistungsstarke Suchfunktionen einzurichten.

Bei b13 praktizieren unsere Entwickler und Entwicklerinnen „Continuous Integration“ und „Continuous Delivery“ (CI/CD) und testen Änderungen lokal, bevor der Code auf den Produktionssystemen veröffentlicht wird. Um Änderungen machen zu können, müssen unsere lokalen und produktiven Umgebungen identische Konfigurationen haben - für Solr und andere Systeme. Daher müssen Entwickler, die Solr ohne größere Probleme im Live-System einsetzen wollen, dies auch lokal implementieren. 

Diese Schritt-für-Schritt-Anleitung zeigt dir, wie du Solr in wenigen Minuten lokal über Docker einrichtest.

Voraussetzungen

Eines der Tools, die wir bei der lokalen Entwicklung einsetzen, ist DDEV, eine leistungsstarke Plattform, die auf Docker und Docker-Compose für PHP-Projekte aufbaut. DDEV bietet eine hervorragende Unterstützung für TYPO3. Bevor du beginnst, solltest du sicherstellen, dass du DDEV und die Solr-Extension von dkd bereits in deinem bestehenden TYPO3-Projekt installiert hast. In dieser Anleitung wird davon ausgegangen, dass du die Versionskontrolle Git verwendest und bereits auf TYPO3 v10 LTS aktualisiert hast. Als kurze Checkliste erwarten wir, dass dein Projekt die folgenden Voraussetzungen erfüllt: 

• TYPO3 v10 LTS läuft mit Composer und dein Public Root Verzeichnis ist als „htdocs/“ konfiguriert (wo sich dein fileadmin-Ordner befindet).
• Die Solr Extension v11.0.x ist installiert.
• Der verbundene Solr Server 8.11.1 ist bereits in der TYPO3 Site-Configuration konfiguriert (weitere Informationen findest du in der Versionsmatrix der Solr Extension).
• Für jede Sprache auf deiner Website ist ein eigener Solr-Kern eingerichtet, der das TYPO3-Solr-Konfigurationsset „ext_solr_11_1_0“ verwendet. (Eine Website mit vier Sprachen hätte zum Beispiel vier Solr Cores: „corporate_en“, ´„corporate_de“, „corporate_it“ und „corporate_cn“.)
• DDEV läuft bereits und ist in .ddev im Stammverzeichnis deines Projekts konfiguriert

Schritt 1: Solr als DDEV-Container einrichten

DDEV wird bereits mit grundlegender Unterstützung für Solr ausgeliefert, und du kannst jede docker-compose-Datei verwenden, um schnell zusätzliche Docker-Container einzurichten. (Das ist genial!)

Erstelle in deinem bestehenden Projekt eine neue Datei namens .ddev/docker-compose.solr.yaml mit folgendem Inhalt:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

version: '3.6'

services:
 solr:
   container_name: ddev-${DDEV_SITENAME}-solr
   image: solr:8.11.1
   restart: "no"
   expose:
     - 8983
     - 8984
   labels:
     com.ddev.site-name: ${DDEV_SITENAME}
     com.ddev.approot: $DDEV_APPROOT
   environment:
     - VIRTUAL_HOST=$DDEV_HOSTNAME
     - HTTP_EXPOSE=8983
     - HTTPS_EXPOSE=8984:8983
   volumes:
     - ./solr:/var/solr/data
 web:
   links:
     - solr

Beachte die folgenden drei Punkte: 

1. Der Name des Docker-Images ist „solr:8.11.1“. Wir verwenden das offizielle „solr“-Image mit dem Tag „8.11.1“, da es in der Produktion eingesetzt wird und wir so nah wie möglich am Produktionssystem bleiben wollen. Schau auf „hub.docker.com“ für verfügbare Versionen dieses Images. Solr 8.11.1 ist außerdem sicher vor allen Log4J-Schwachstellen.
2. Der Containername lautet ddev-${DDEV_SITENAME}-solr und wir werden diesen später verwenden, um uns mit dem Solr-Dienst in TYPO3 zu verbinden.
3. Die exponierten Ports für HTTP und HTTPS, die wir verwenden, sind die Standardports, die Solr verwendet. 8983 für den nicht verschlüsselten HTTP-Port und 8984 für den verschlüsselten HTTPS-Port.

Schritt 2: Konfiguriere deine Solr-Kerne

Konfiguriere die Solr-Kerne in DDEVs Konfigurationsdatei .ddev/config.yaml. Füge die folgenden Zeilen am Ende der Datei hinzu und passe sie an deine Spracheinstellungen an:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

environment:
 - SOLR_HOST=${DDEV_SITENAME}.ddev.site
typo3_solr_cores:
 - { name: corporate_en, schema: "english/schema.xml" }
 - { name: corporate_de, schema: "german/schema.xml" }
 - { name: corporate_zh, schema: "chinese/schema.xml" }
 - { name: corporate_it, schema: "italian/schema.xml" }
typo3_solr_ext_path: 'htdocs/typo3conf/ext/solr/Resources/Private/Solr/'
typo3_solr_configset: 'ext_solr_11_0_0'
hooks:
 post-start:
   - exec-host: "composer install --no-scripts"
   - exec: |
       SOLR_EXT_PATH=(`yq e '.typo3_solr_ext_path' .ddev/config.yaml`)
       cp -r ${SOLR_EXT_PATH}solr.xml .ddev/solr/
       cp -r ${SOLR_EXT_PATH}configsets .ddev/solr/

       CONFIGSET=(`yq e '.typo3_solr_configset' .ddev/config.yaml`)
       NAME=(`yq e '.typo3_solr_cores.[].name' .ddev/config.yaml`)
       SCHEMA=(`yq e '.typo3_solr_cores.[].schema' .ddev/config.yaml`)

       length=${#NAME[@]}
       for (( i = 0; i < length; i++ )); do
         curl -s -o /dev/null "http://solr:8983/solr/admin/cores?action=CREATE&name=${NAME[$i]}&configSet=${CONFIGSET}&schema=${SCHEMA[$i]}&dataDir=data/"
       done

In diesem Schritt wird die Hauptlogik für die TYPO3-Integration implementiert. Auch hier sind drei Punkte wichtig: 

• Definiere die Kerne, die du erstellen willst (typo3_solr_ext_cores), den Pfad zum Asset-Ordner der Solr-Extension (typo3_solr_ext_path), der die Configsets bereits enthält und die Solr-Konfiguration, die schon einsatzbereit ist für TYPO3.
• Der Post-Start-Hook kopiert die Konfiguration aus der Extension und erstellt die Cores über eine Curl-Anfrage an den Solr-Host, falls sie noch nicht existieren. Der Hook nutzt composer install, um sicherzustellen, dass die Solr-Extension zu diesem Zeitpunkt auch installiert ist.
• Die zusätzliche Umgebungsvariable für den Haupt-Webcontainer SOLR_HOST wird später in TYPO3 verwendet, um den internen Docker-Dienst direkt in der Site-Configuration von TYPO3 zu referenzieren.

Wenn du Git verwendest, ist es jetzt an der Zeit, die Datei .ddev/.gitignore zu bearbeiten und sicherzustellen, dass die erstellten Solr-Core-Daten und Configsets nicht übertragen werden. Um .gitignore zu deinem Git-Repository hinzuzufügen und den Ordner .ddev/solr/ und seinen Inhalt von der Versionskontrolle auszuschließen, musst du die ersten drei Zeilen in .ddev/.gitignore entfernen und /solr/ ganz am Ende der Datei hinzufügen. 

Führe ddev restart aus und – voila – deine Solr-Kerne werden automatisch erstellt.

Schritt 3: Verbinde deine Solr-Kerne in TYPO3

In unserem Beispiel gehen wir davon aus, dass du in deiner Produktionsumgebung mit Umgebungsvariablen arbeitest (siehe https://12factor.net/config für weitere Details). Wir verwenden denselben Solr Host zum Lesen und Schreiben und die Umgebungsvariable SOLR_HOST in der Produktionsumgebung. Angenommen, dein Setup ist ähnlich, dann folge der TYPO3 Solr-Dokumentation und passe die Umgebungsvariable SOLR_HOST in deiner Site-Konfiguration an - entweder über die GUI oder durch Bearbeiten der Datei config/sites/main/config.yaml.

Als finalen Check solltest du sicherstellen, dass du in der Produktionumgebung Umgebungsvariablen verwendest und die SOLR_HOST-Variable in deiner Site-Configuration angegeben hast. Außerdem musst du die Namen deiner lokalen Solr-Kerne mit denen in der Produktionsumgebung abgleichen. Sobald du das getan hast, ist deine Einrichtung abgeschlossen! Du kannst deine Solr-Suche lokal in DDEV indizieren und testen.

Dies ist ein kurzer Auszug aus der Konfigurationsdatei des Beispielprojekts, die sich in config/sites/main/config.yaml befindet.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

-
 title: English
 languageId: 0
 base: /en/
 typo3Language: default
 ...
 solr_core_read: corporate_en
-
 title: Deutsch
 languageId: 1
 base: /
 typo3Language: de
 ...
 solr_core_read: corporate_de
solr_enabled_read: true
solr_host_read: '%env(SOLR_HOST)'
solr_path_read: /solr/
solr_port_read: '8983'
solr_scheme_read: http

Last but not least: Committe und pushe deinen Code, damit deine Teammitglieder das von dir erstellte Setup für das Projekt ebenfalls nutzen können.

Wir hoffen, dass das dir und deinen Teammitgliedern Zeit spart!