Configuración del Entorno de Desarrollo

Esta página explica en detalle el procedimiento para construir el entorno de desarrollo de Fess. Desde la selección del IDE hasta la obtención del código fuente, ejecución y depuración, se explica paso a paso.

Requisitos del sistema

se recomiendan los siguientes requisitos de hardware para el entorno de desarrollo.

Requisitos de Hardware

CPU: 4 núcleos o más
Memoria: 8GB o más (se recomienda 16GB)
Disco: 20GB o más de espacio libre

Nota

Durante el desarrollo, Fess y Opensearch integrado se ejecutan simultáneamente, por lo que asegure suficiente memoria y espacio en disco.

Requisitos de software

Os: Windows 10/11, macOs 11 o posterior, Linux (Ubuntu 20.04 o posterior, etc.)
Java: JDK 21 o posterior
Maven: 3.x o posterior
Git: 2.x o posterior
IDE: Eclipse, IntelliJ IDEA, Vs Code, etc.

Instalación de software Obligatorio

Instalación de Java

se requiere Java 21 o posterior para el desarrollo de Fess.

Instalación de Eclipse Temurin (Recomendado)

se recomienda Eclipse Temurin (anteriormente AdoptOpenJDK).

Acceda a Adoptium
Descargue la versión LTs de Java 21
Instale siguiendo las instrucciones del instalador

Verificación de Instalación

Ejecute lo siguiente en la terminal o símbolo del sistema:

java -version

si ve una salida como la siguiente, es exitoso:

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)

Configuración de Variables de Entorno

Linux/macOs:

Agregue lo siguiente a ~/.bashrc o ~/.zshrc:

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

Windows:

Abra «Editar las variables de entorno del sistema»
Haga clic en «Variables de entorno»
Agregue JAVA_HOME: C:\Program Files\Eclipse Adoptium\jdk-21.x.x.x-hotspot
Agregue %JAVA_HOME%\bin a PATH

Instalación de Maven

Instale Maven 3.x o posterior.

Descarga e Instalación

Acceda a la página de descarga de Maven
Descargue Binary zip/tar.gz archive
Extraiga y coloque en una ubicación apropiada

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:

Extraiga el archivo ZIP
Colóquelo en C:\Program Files\Apache\maven o similar

Configuración de Variables de Entorno

Linux/macOs:

Agregue lo siguiente a ~/.bashrc o ~/.zshrc:

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

Windows:

Agregue MAVEN_HOME: C:\Program Files\Apache\maven
Agregue %MAVEN_HOME%\bin a PATH

Verificación de Instalación

mvn -version

si ve una salida como la siguiente, es exitoso:

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

Instalación de Git

si Git no está instalado, instálelo desde lo siguiente.

Windows: Git para Windows
macOs: brew install git o página de descarga de Git
Linux: sudo apt install git (Ubuntu/Debian) o sudo yum install git (RHEL/CentOs)

Verificación de instalación:

git --version

Configuración del IDE

En caso de Eclipse

Eclipse es el IDE recomendado en la documentación oficial de Fess.

Instalación de Eclipse

Acceda a la página de descarga de Eclipse
Descargue «Eclipse IDE for Enterprise Java and Web Developers»
Ejecute el instalador y siga las instrucciones para instalar

Plugins Recomendados

Eclipse incluye los siguientes plugins por defecto:

Maven Integration for Eclipse (m2e)
Eclipse Java Development Tools

Importación del Proyecto

Inicie Eclipse
seleccione File > Import
seleccione Maven > Existing Maven Projects
Especifique el directorio del código fuente de Fess
Haga clic en Finish

Configuración de Ejecución

seleccione Run > Run Configurations...
Haga clic derecho en Java Application y seleccione New Configuration
Configure lo siguiente:
- Name: Fess Boot
- Project: fess
- Main class: org.codelibs.fess.FessBoot
Haga clic en Apply

En caso de IntelliJ IDEA

IntelliJ IDEA también es un IDE ampliamente utilizado.

Instalación de IntelliJ IDEA

Acceda a la página de descarga de IntelliJ IDEA
Descargue Community Edition (gratis) o Ultimate Edition
Ejecute el instalador y siga las instrucciones para instalar

Importación del Proyecto

Inicie IntelliJ IDEA
seleccione Open
seleccione pom.xml del directorio del código fuente de Fess
Haga clic en Open as Project
se importa automáticamente como proyecto Maven

Configuración de Ejecución

seleccione Run > Edit Configurations...
Haga clic en el botón + y seleccione Application
Configure lo siguiente:
- Name: Fess Boot
- Module: fess
- Main class: org.codelibs.fess.FessBoot
- JRE: Java 21
Haga clic en OK

En caso de Vs Code

Vs Code también es una opción si prefiere un entorno de desarrollo ligero.

Instalación de Vs Code

Acceda a la página de descarga de Vs Code
Descargue y ejecute el instalador

Instalación de Extensiones Necesarias

Instale las siguientes extensiones:

Extension Pack for Java: Conjunto de extensiones necesarias para desarrollo Java
Maven for Java: soporte de Maven

Abrir Proyecto

Inicie Vs Code
seleccione File > Open Folder
seleccione el directorio del código fuente de Fess

Obtención del Código Fuente

Clonar desde GitHub

Clone el código fuente de Fess desde GitHub.

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

si usa ssH:

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

Truco

si desarrolla bifurcando, primero bifurque el repositorio de Fess en GitHub, luego clone su repositorio bifurcado:

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

Construcción del Proyecto

Descarga de Plugins de Opensearch

se necesitan plugins para Opensearch para ejecutar Fess. Descárguelos con el siguiente comando:

mvn antrun:run

Este comando ejecuta lo siguiente:

Descarga de Opensearch
Descarga e instalación de plugins obligatorios
Configuración de Opensearch

Nota

Ejecute este comando solo la primera vez o al actualizar plugins. No necesita ejecutarlo cada vez.

Construcción Inicial

Construya el proyecto:

mvn clean compile

La construcción inicial puede llevar tiempo (descarga de bibliotecas de dependencias, etc.).

si la construcción es exitosa, aparecerá el siguiente mensaje:

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

Ejecución de Fess

Ejecución desde Línea de Comandos

Ejecute usando Maven:

mvn compile exec:java

O empaquete y luego ejecute:

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

Ejecución desde IDE

En caso de Eclipse

Haga clic derecho en la clase org.codelibs.fess.FessBoot
seleccione Run As > Java Application

O use la configuración de ejecución creada:

Haga clic en el menú desplegable del botón de ejecución en la barra de herramientas
seleccione Fess Boot

En caso de IntelliJ IDEA

Haga clic derecho en la clase org.codelibs.fess.FessBoot
seleccione Run 'FessBoot.main()'

O use la configuración de ejecución creada:

Haga clic en el menú desplegable del botón de ejecución en la barra de herramientas
seleccione Fess Boot

En caso de Vs Code

Abra src/main/java/org/codelibs/fess/FessBoot.java
seleccione Run Without Debugging desde el menú Run

Confirmación de Inicio

Fess tarda 1-2 minutos en iniciarse. si aparecen los siguientes registros en la consola, el inicio está completo:

[INFO] Boot Thread: Boot process completed successfully.

Verifique el funcionamiento accediendo a lo siguiente en el navegador:

Pantalla de búsqueda: http://localhost:8080/
Pantalla de administración: http://localhost:8080/admin/
- Usuario predeterminado: admin
- Contraseña predeterminada: admin

Cambiar Número de Puerto

si el puerto predeterminado 8080 está en uso, puede cambiarlo en el siguiente archivo:

src/main/resources/fess_config.properties

# Cambiar número de puerto
server.port=8080

Ejecución de Depuración

Depuración en IDE

En caso de Eclipse

Haga clic derecho en la clase org.codelibs.fess.FessBoot
seleccione Debug As > Java Application
Establezca puntos de interrupción y rastree el comportamiento del código

En caso de IntelliJ IDEA

Haga clic derecho en la clase org.codelibs.fess.FessBoot
seleccione Debug 'FessBoot.main()'
Establezca puntos de interrupción y rastree el comportamiento del código

En caso de Vs Code

Abra src/main/java/org/codelibs/fess/FessBoot.java
seleccione start Debugging desde el menú Run

Depuración Remota

También puede conectar un depurador a Fess iniciado desde la línea de comandos.

Inicie Fess en modo de depuración:

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

Conecte depuración remota desde IDE:

Eclipse:

seleccione Run > Debug Configurations...
Haga clic derecho en Remote Java Application y seleccione New Configuration
Configure Port: 5005
Haga clic en Debug

IntelliJ IDEA:

seleccione Run > Edit Configurations...
seleccione + > Remote JVM Debug
Configure Port: 5005
Haga clic en OK y ejecute Debug

Configuraciones Útiles para el Desarrollo

Cambiar Nivel de Registro

Cambiar el nivel de registro al depurar permite verificar información detallada.

Edite 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>

Habilitar Hot Deploy

LastaFlute puede reflejar algunos cambios sin reiniciar.

Configure lo siguiente en src/main/resources/fess_config.properties:

# Habilitar hot deploy
development.here=true

sin embargo, se requiere reiniciar para los siguientes cambios:

Cambios en la estructura de clases (agregar/eliminar métodos, etc.)
Cambios en archivos de configuración
Cambios en bibliotecas de dependencias

Operación de Opensearch Integrado

En el entorno de desarrollo, se usa Opensearch integrado.

Ubicación de Opensearch:

target/fess/es/

Acceso directo a la API de Opensearch:

# Lista de índices
curl -X GET http://localhost:9201/_cat/indices?v

# Búsqueda de documentos
curl -X GET http://localhost:9201/fess.search/_search?pretty

# Verificar mapeo
curl -X GET http://localhost:9201/fess.search/_mapping?pretty

Usar Opensearch Externo

si usa un servidor Opensearch externo, edite src/main/resources/fess_config.properties:

# Deshabilitar Opensearch integrado
opensearch.cluster.name=fess
opensearch.http.url=http://localhost:9200

Generación de Código con DBFlute

Fess usa DBFlute para generar automáticamente código Java desde el esquema de Opensearch.

Regeneración cuando el Esquema Cambia

si cambia el mapeo de Opensearch, regenere el código Java correspondiente con el siguiente comando:

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

Explicación de cada comando:

rm -rf mydbflute: Eliminar directorio de trabajo de DBFlute existente
mvn antrun:run: Descargar plugins de Opensearch
mvn dbflute:freegen: Generar código Java desde esquema
mvn license:format: Agregar encabezado de licencia

solución de Problemas

Errores de Construcción

Error: Versión antigua de Java

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

solución: Instale Java 21 o posterior y configure JAVA_HOME apropiadamente.

Error: Falla en descarga de bibliotecas de dependencias

[ERROR] Failed to collect dependencies

solución: Verifique la conexión de red, limpie el repositorio local de Maven y vuelva a intentar:

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

Errores de Ejecución

Error: El puerto 8080 ya está en uso

Address already in use

solución:

Terminar proceso que usa el puerto 8080
O cambiar número de puerto en fess_config.properties

Error: Opensearch no se inicia

Verifique archivos de registro target/fess/es/logs/.

Causas comunes:

Memoria insuficiente: Aumentar tamaño del heap de JVM
Puerto 9201 en uso: Cambiar número de puerto
Espacio en disco insuficiente: Asegurar espacio en disco

IDE no Reconoce el Proyecto

Actualizar Proyecto Maven

Eclipse: Clic derecho en proyecto > Maven > Update Project
IntelliJ IDEA: Haga clic en Reload All Maven Projects en ventana de herramientas Maven
Vs Code: Ejecute Java: Clean Java Language server Workspace desde paleta de comandos

Próximos Pasos

Una vez completada la configuración del entorno de desarrollo, consulte los siguientes documentos:

Arquitectura y Estructura del Código - Comprender estructura del código
Flujo de Trabajo de Desarrollo - Aprender flujo de trabajo de desarrollo
Construcción y Pruebas - Métodos de construcción y prueba
Guía de Contribución - Crear pull requests

Menu

Configuración del Entorno de Desarrollo

Instalación de Eclipse Temurin (Recomendado)

Verificación de Instalación

Configuración de Variables de Entorno

Descarga e Instalación

Configuración de Variables de Entorno

Verificación de Instalación

Instalación de Eclipse

Plugins Recomendados

Importación del Proyecto

Configuración de Ejecución

Instalación de IntelliJ IDEA

Importación del Proyecto

Configuración de Ejecución

Instalación de Vs Code

Instalación de Extensiones Necesarias

Abrir Proyecto

En caso de Eclipse

En caso de IntelliJ IDEA

En caso de Vs Code

En caso de Eclipse

En caso de IntelliJ IDEA

En caso de Vs Code