Einrichten der Entwicklungsumgebung

Diese seite erklärt im Detail die schritte zum Einrichten der Fess-Entwicklungsumgebung. Von der Auswahl der IDE über das Abrufen des Quellcodes bis hin zur Ausführung und zum Debuggen wird schritt für schritt erklärt.

systemanforderungen

Für die Entwicklungsumgebung werden folgende Hardware-Anforderungen empfohlen.

Hardware-Anforderungen

CPU: 4 Kerne oder mehr
speicher: 8 GB oder mehr (16 GB empfohlen)
Festplatte: 20 GB oder mehr freier speicherplatz

Bemerkung

Während der Entwicklung laufen Fess und das eingebettete Opensearch gleichzeitig, daher sollten sie ausreichend speicher und Festplattenspeicher bereitstellen.

software-Anforderungen

Os: Windows 10/11, macOs 11 oder höher, Linux (Ubuntu 20.04 oder höher usw.)
Java: JDK 21 oder höher
Maven: 3.x oder höher
Git: 2.x oder höher
IDE: Eclipse, IntelliJ IDEA, Vs Code usw.

Installation der erforderlichen software

Installation von Java

Für die Fess-Entwicklung ist Java 21 oder höher erforderlich.

Installation von Eclipse Temurin (empfohlen)

Eclipse Temurin (ehemals AdoptOpenJDK) wird empfohlen.

Besuchen sie Adoptium
Laden sie die LTs-Version von Java 21 herunter
Folgen sie den Anweisungen des Installers zur Installation

Überprüfung der Installation

Führen sie Folgendes im Terminal oder in der Eingabeaufforderung aus:

java -version

Bei Erfolg wird eine Ausgabe wie folgt angezeigt:

openjdk version "21.0.x" 2024-xx-xx LTs
OpenJDK Runtime Environment Temurin-21.0.x+x (build 21.0.x+x-LTs)
OpenJDK 64-Bit server VM Temurin-21.0.x+x (build 21.0.x+x-LTs, mixed mode, sharing)

Einstellung der Umgebungsvariablen

Linux/macOs:

Fügen sie Folgendes zu ~/.bashrc oder ~/.zshrc hinzu:

export JAVA_HOME=/path/to/java21
export PATH=$JAVA_HOME/bin:$PATH

Windows:

Öffnen sie „systemumgebungsvariablen bearbeiten“
Klicken sie auf „Umgebungsvariablen“
Fügen sie JAVA_HOME hinzu: C:\Program Files\Eclipse Adoptium\jdk-21.x.x.x-hotspot
Fügen sie %JAVA_HOME%\bin zu PATH hinzu

Installation von Maven

Installieren sie Maven 3.x oder höher.

Download und Installation

Besuchen sie die Maven-Download-seite
Laden sie das Binary zip/tar.gz-Archiv herunter
Entpacken sie es und platzieren sie es an einem geeigneten Ort

Linux/macOs:

tar xzvf apache-maven-3.x.x-bin.tar.gz
sudo mv apache-maven-3.x.x /opt/
sudo ln -s /opt/apache-maven-3.x.x /opt/maven

Windows:

Entpacken sie die ZIP-Datei
Platzieren sie sie unter C:\Program Files\Apache\maven oder ähnlich

Einstellung der Umgebungsvariablen

Linux/macOs:

Fügen sie Folgendes zu ~/.bashrc oder ~/.zshrc hinzu:

export MAVEN_HOME=/opt/maven
export PATH=$MAVEN_HOME/bin:$PATH

Windows:

Fügen sie MAVEN_HOME hinzu: C:\Program Files\Apache\maven
Fügen sie %MAVEN_HOME%\bin zu PATH hinzu

Überprüfung der Installation

mvn -version

Bei Erfolg wird eine Ausgabe wie folgt angezeigt:

Apache Maven 3.x.x
Maven home: /opt/maven
Java version: 21.0.x, vendor: Eclipse Adoptium

Installation von Git

Wenn Git nicht installiert ist, installieren sie es von folgenden Quellen.

Windows: Git for Windows
macOs: brew install git oder Git-Download-seite
Linux: sudo apt install git (Ubuntu/Debian) oder sudo yum install git (RHEL/CentOs)

Überprüfung der Installation:

git --version

IDE-Einrichtung

Im Fall von Eclipse

Eclipse ist die in der offiziellen Fess-Dokumentation empfohlene IDE.

Installation von Eclipse

Besuchen sie die Eclipse-Download-seite
Laden sie „Eclipse IDE for Enterprise Java and Web Developers“ herunter
Führen sie den Installer aus und folgen sie den Anweisungen zur Installation

Empfohlene Plugins

Eclipse enthält standardmäßig folgende Plugins:

Maven Integration for Eclipse (m2e)
Eclipse Java Development Tools

Importieren des Projekts

starten sie Eclipse
Wählen sie File > Import
Wählen sie Maven > Existing Maven Projects
Geben sie das Fess-Quellcodeverzeichnis an
Klicken sie auf Finish

Konfiguration der Ausführungskonfiguration

Wählen sie Run > Run Configurations...
Rechtsklick auf Java Application und wählen sie New Configuration
Konfigurieren sie Folgendes:
- Name: Fess Boot
- Project: fess
- Main class: org.codelibs.fess.FessBoot
Klicken sie auf Apply

Im Fall von IntelliJ IDEA

IntelliJ IDEA ist ebenfalls eine weit verbreitete IDE.

Installation von IntelliJ IDEA

Besuchen sie die IntelliJ IDEA-Download-seite
Laden sie die Community Edition (kostenlos) oder Ultimate Edition herunter
Führen sie den Installer aus und folgen sie den Anweisungen zur Installation

Importieren des Projekts

starten sie IntelliJ IDEA
Wählen sie Open
Wählen sie pom.xml im Fess-Quellcodeverzeichnis
Klicken sie auf Open as Project
Es wird automatisch als Maven-Projekt importiert

Konfiguration der Ausführungskonfiguration

Wählen sie Run > Edit Configurations...
Klicken sie auf + und wählen sie Application
Konfigurieren sie Folgendes:
- Name: Fess Boot
- Module: fess
- Main class: org.codelibs.fess.FessBoot
- JRE: Java 21
Klicken sie auf OK

Im Fall von Vs Code

Vs Code ist eine Option, wenn sie eine leichte Entwicklungsumgebung bevorzugen.

Installation von Vs Code

Besuchen sie die Vs Code-Download-seite
Laden sie den Installer herunter und führen sie ihn aus

Installation der erforderlichen Erweiterungen

Installieren sie folgende Erweiterungen:

Extension Pack for Java: satz von Erweiterungen für Java-Entwicklung
Maven for Java: Maven-Unterstützung

Projekt öffnen

starten sie Vs Code
Wählen sie File > Open Folder
Wählen sie das Fess-Quellcodeverzeichnis

Abrufen des Quellcodes

Klonen von GitHub

Klonen sie den Fess-Quellcode von GitHub.

git clone https://github.com/codelibs/fess.git
cd fess

Bei Verwendung von ssH:

git clone git@github.com:codelibs/fess.git
cd fess

Tipp

Wenn sie mit einem Fork entwickeln, forken sie zuerst das Fess-Repository auf GitHub und klonen sie dann Ihr geforktes Repository:

git clone https://github.com/YOUR_UsERNAME/fess.git
cd fess
git remote add upstream https://github.com/codelibs/fess.git

Projekt bauen

Herunterladen der Opensearch-Plugins

Für die Ausführung von Fess sind Plugins für Opensearch erforderlich. Laden sie sie mit folgendem Befehl herunter:

mvn antrun:run

Dieser Befehl führt Folgendes aus:

Herunterladen von Opensearch
Herunterladen und Installieren der erforderlichen Plugins
Konfiguration von Opensearch

Bemerkung

Führen sie diesen Befehl nur beim ersten Mal oder beim Aktualisieren von Plugins aus. sie müssen ihn nicht jedes Mal ausführen.

Erster Build

Bauen sie das Projekt:

mvn clean compile

Der erste Build kann einige Zeit dauern (Download von Abhängigkeiten usw.).

Bei erfolgreichem Build wird folgende Meldung angezeigt:

[INFO] BUILD sUCCEss
[INFO] Total time: xx:xx min
[INFO] Finished at: 2024-xx-xxTxx:xx:xx+09:00

Ausführen von Fess

Ausführung von der Kommandozeile

Ausführung mit Maven:

mvn compile exec:java

Oder packen sie es und führen sie es aus:

mvn package
java -jar target/fess-15.3.x.jar

Ausführung von der IDE

Im Fall von Eclipse

Rechtsklick auf die Klasse org.codelibs.fess.FessBoot
Wählen sie Run As > Java Application

Oder verwenden sie die erstellte Ausführungskonfiguration:

Klicken sie auf das Dropdown-Menü der Ausführungsschaltfläche in der symbolleiste
Wählen sie Fess Boot

Im Fall von IntelliJ IDEA

Rechtsklick auf die Klasse org.codelibs.fess.FessBoot
Wählen sie Run 'FessBoot.main()'

Oder verwenden sie die erstellte Ausführungskonfiguration:

Klicken sie auf das Dropdown-Menü der Ausführungsschaltfläche in der symbolleiste
Wählen sie Fess Boot

Im Fall von Vs Code

Öffnen sie src/main/java/org/codelibs/fess/FessBoot.java
Wählen sie Run Without Debugging aus dem Menü Run

Überprüfung des starts

Der start von Fess dauert 1-2 Minuten. Wenn folgendes Log in der Konsole angezeigt wird, ist der start abgeschlossen:

[INFO] Boot Thread: Boot process completed successfully.

Überprüfen sie den Betrieb durch Zugriff im Browser:

suchseite: http://localhost:8080/
Verwaltungsseite: http://localhost:8080/admin/
- standardbenutzer: admin
- standardpasswort: admin

Ändern der Portnummer

Wenn der standardport 8080 verwendet wird, können sie ihn in folgender Datei ändern:

src/main/resources/fess_config.properties

# Portnummer ändern
server.port=8080

Debug-Ausführung

Debug-Ausführung in der IDE

Im Fall von Eclipse

Rechtsklick auf die Klasse org.codelibs.fess.FessBoot
Wählen sie Debug As > Java Application
setzen sie Breakpoints und verfolgen sie das Verhalten des Codes

Im Fall von IntelliJ IDEA

Rechtsklick auf die Klasse org.codelibs.fess.FessBoot
Wählen sie Debug 'FessBoot.main()'
setzen sie Breakpoints und verfolgen sie das Verhalten des Codes

Im Fall von Vs Code

Öffnen sie src/main/java/org/codelibs/fess/FessBoot.java
Wählen sie start Debugging aus dem Menü Run

Remote-Debugging

sie können auch einen Debugger an Fess anschließen, das von der Kommandozeile gestartet wurde.

starten sie Fess im Debug-Modus:

mvn compile exec:java -Dexec.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

Remote-Debug-Verbindung von der IDE:

Eclipse:

Wählen sie Run > Debug Configurations...
Rechtsklick auf Remote Java Application und wählen sie New Configuration
setzen sie Port: 5005
Klicken sie auf Debug

IntelliJ IDEA:

Wählen sie Run > Edit Configurations...
Wählen sie + > Remote JVM Debug
setzen sie Port: 5005
Klicken sie auf OK und führen sie Debug aus

Nützliche Einstellungen für die Entwicklung

Ändern der Log-Ebene

Das Ändern der Log-Ebene beim Debuggen ermöglicht es Ihnen, detaillierte Informationen zu überprüfen.

Bearbeiten sie src/main/resources/log4j2.xml:

<Configuration status="INFO">
    <Loggers>
        <Logger name="org.codelibs.fess" level="DEBUG"/>
        <Root level="INFO">
            <AppenderRef ref="console"/>
        </Root>
    </Loggers>
</Configuration>

Aktivieren von Hot Deploy

LastaFlute kann einige Änderungen ohne Neustart widerspiegeln.

setzen sie Folgendes in src/main/resources/fess_config.properties:

# Hot Deploy aktivieren
development.here=true

Allerdings erfordern folgende Änderungen einen Neustart:

Änderungen der Klassenstruktur (Hinzufügen/Entfernen von Methoden usw.)
Änderungen von Konfigurationsdateien
Änderungen von Abhängigkeitsbibliotheken

Betrieb des eingebetteten Opensearch

In der Entwicklungsumgebung wird das eingebettete Opensearch verwendet.

speicherort von Opensearch:

target/fess/es/

Direkter Zugriff auf die Opensearch-API:

# Liste der Indizes
curl -X GET http://localhost:9201/_cat/indices?v

# Dokumentensuche
curl -X GET http://localhost:9201/fess.search/_search?pretty

# Mapping überprüfen
curl -X GET http://localhost:9201/fess.search/_mapping?pretty

Verwendung von externem Opensearch

Wenn sie einen externen Opensearch-server verwenden, bearbeiten sie src/main/resources/fess_config.properties:

# Eingebettetes Opensearch deaktivieren
opensearch.cluster.name=fess
opensearch.http.url=http://localhost:9200

Code-Generierung mit DBFlute

Fess verwendet DBFlute, um Java-Code automatisch aus dem Opensearch-schema zu generieren.

Neugenerierung bei schemaänderungen

Wenn sie das Opensearch-Mapping geändert haben, generieren sie den entsprechenden Java-Code mit folgendem Befehl neu:

rm -rf mydbflute
mvn antrun:run
mvn dbflute:freegen
mvn license:format

Erklärung der Befehle:

rm -rf mydbflute: Löscht das vorhandene DBFlute-Arbeitsverzeichnis
mvn antrun:run: Lädt Opensearch-Plugins herunter
mvn dbflute:freegen: Generiert Java-Code aus dem schema
mvn license:format: Fügt Lizenz-Header hinzu

Fehlerbehebung

Build-Fehler

Fehler: Java-Version ist veraltet

[ERROR] Failed to execute goal ... requires at least Java 21

Lösung: Installieren sie Java 21 oder höher und setzen sie JAVA_HOME entsprechend.

Fehler: Download von Abhängigkeitsbibliotheken fehlgeschlagen

[ERROR] Failed to collect dependencies

Lösung: Überprüfen sie die Netzwerkverbindung, löschen sie das lokale Maven-Repository und versuchen sie es erneut:

rm -rf ~/.m2/repository
mvn clean compile

Ausführungsfehler

Fehler: Port 8080 wird bereits verwendet

Address already in use

Lösung:

Beenden sie den Prozess, der Port 8080 verwendet
Oder ändern sie die Portnummer in fess_config.properties

Fehler: Opensearch startet nicht

Überprüfen sie die Logdatei target/fess/es/logs/.

Häufige Ursachen:

speichermangel: Erhöhen sie die JVM-Heap-Größe
Port 9201 wird verwendet: Ändern sie die Portnummer
Festplattenspeicher voll: schaffen sie Festplattenspeicher

Projekt wird in der IDE nicht erkannt

Aktualisieren des Maven-Projekts

Eclipse: Rechtsklick auf Projekt > Maven > Update Project
IntelliJ IDEA: Klicken sie im Maven-Tool-Fenster auf Reload All Maven Projects
Vs Code: Führen sie Java: Clean Java Language server Workspace aus der Befehlspalette aus

Nächste schritte

Nachdem sie die Entwicklungsumgebung eingerichtet haben, lesen sie folgende Dokumentation:

Architektur und Codestruktur - Verständnis der Codestruktur
Entwicklungsworkflow - Lernen des Entwicklungsworkflows
Bauen und Testen - Methoden zum Bauen und Testen
Leitfaden für Beiträge - Erstellen von Pull Requests

Menu

Einrichten der Entwicklungsumgebung

Installation von Eclipse Temurin (empfohlen)

Überprüfung der Installation

Einstellung der Umgebungsvariablen

Download und Installation

Einstellung der Umgebungsvariablen

Überprüfung der Installation

Installation von Eclipse

Empfohlene Plugins

Importieren des Projekts

Konfiguration der Ausführungskonfiguration

Installation von IntelliJ IDEA

Importieren des Projekts

Konfiguration der Ausführungskonfiguration

Installation von Vs Code

Installation der erforderlichen Erweiterungen

Projekt öffnen

Im Fall von Eclipse

Im Fall von IntelliJ IDEA

Im Fall von Vs Code

Im Fall von Eclipse

Im Fall von IntelliJ IDEA

Im Fall von Vs Code