Development Environment Setup

This page provides detailed instructions for setting up a Fess development environment. It guides you step by step from choosing an IDE to obtaining source code, running, and debugging.

System Requirements

The following hardware requirements are recommended for the development environment.

Hardware Requirements

CPU: 4 cores or more
Memory: 8GB or more (16GB recommended)
Disk: 20GB or more of free space

Note

During development, Fess itself and the embedded OpenSearch run simultaneously, so ensure sufficient memory and disk space.

Software Requirements

OS: Windows 10/11, macOS 11 or later, Linux (Ubuntu 20.04 or later, etc.)
Java: JDK 21 or later
Maven: 3.x or later
Git: 2.x or later
IDE: Eclipse, IntelliJ IDEA, VS Code, etc.

Installing Required Software

Installing Java

Java 21 or later is required for Fess development.

Installing Eclipse Temurin (Recommended)

Eclipse Temurin (formerly AdoptOpenJDK) is recommended.

Visit Adoptium
Download the LTS version of Java 21
Follow the installer instructions to install

Verifying Installation

Execute the following in a terminal or command prompt:

java -version

If successful, you will see output similar to:

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)

Setting Environment Variables

Linux/macOS:

Add the following to ~/.bashrc or ~/.zshrc:

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

Windows:

Open “Edit the system environment variables”
Click “Environment Variables”
Add JAVA_HOME: C:\Program Files\Eclipse Adoptium\jdk-21.x.x.x-hotspot
Add %JAVA_HOME%\bin to PATH

Installing Maven

Install Maven 3.x or later.

Download and Installation

Visit the Maven download page
Download the Binary zip/tar.gz archive
Extract and place in an appropriate location

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:

Extract the ZIP file
Place in C:\Program Files\Apache\maven or similar location

Setting Environment Variables

Linux/macOS:

Add the following to ~/.bashrc or ~/.zshrc:

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

Windows:

Add MAVEN_HOME: C:\Program Files\Apache\maven
Add %MAVEN_HOME%\bin to PATH

Verifying Installation

mvn -version

If successful, you will see output similar to:

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

Installing Git

If Git is not installed, install it from:

Windows: Git for Windows
macOS: brew install git or Git download page
Linux: sudo apt install git (Ubuntu/Debian) or sudo yum install git (RHEL/CentOS)

Verify installation:

git --version

IDE Setup

For Eclipse

Eclipse is the IDE recommended in the official Fess documentation.

Installing Eclipse

Visit the Eclipse download page
Download “Eclipse IDE for Enterprise Java and Web Developers”
Run the installer and follow the instructions

Recommended Plugins

Eclipse includes the following plugins by default:

Maven Integration for Eclipse (m2e)
Eclipse Java Development Tools

Importing the Project

Launch Eclipse
Select File > Import
Select Maven > Existing Maven Projects
Specify the Fess source code directory
Click Finish

Setting Run Configuration

Select Run > Run Configurations...
Right-click Java Application and select New Configuration
Configure the following:
- Name: Fess Boot
- Project: fess
- Main class: org.codelibs.fess.FessBoot
Click Apply

For IntelliJ IDEA

IntelliJ IDEA is also a widely used IDE.

Installing IntelliJ IDEA

Visit the IntelliJ IDEA download page
Download Community Edition (free) or Ultimate Edition
Run the installer and follow the instructions

Importing the Project

Launch IntelliJ IDEA
Select Open
Select the pom.xml in the Fess source code directory
Click Open as Project
It will be automatically imported as a Maven project

Setting Run Configuration

Select Run > Edit Configurations...
Click the + button and select Application
Configure the following:
- Name: Fess Boot
- Module: fess
- Main class: org.codelibs.fess.FessBoot
- JRE: Java 21
Click OK

For VS Code

VS Code is also an option if you prefer a lightweight development environment.

Installing VS Code

Visit the VS Code download page
Download and run the installer

Installing Required Extensions

Install the following extensions:

Extension Pack for Java: A set of extensions required for Java development
Maven for Java: Maven support

Opening the Project

Launch VS Code
Select File > Open Folder
Select the Fess source code directory

Obtaining Source Code

Cloning from GitHub

Clone the Fess source code from GitHub.

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

If using SSH:

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

Tip

If you want to fork and develop, first fork the Fess repository on GitHub, then clone your forked repository:

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

Building the Project

Downloading OpenSearch Plugins

Plugins for OpenSearch are required to run Fess. Download them with the following command:

mvn antrun:run

This command performs the following:

Downloads OpenSearch
Downloads and installs required plugins
Configures OpenSearch

Note

This command only needs to be executed the first time or when updating plugins. You don’t need to run it every time.

Initial Build

Build the project:

mvn clean compile

The initial build may take some time (downloading dependency libraries, etc.).

If the build is successful, you will see messages like:

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

Running Fess

Running from Command Line

Run using Maven:

mvn compile exec:java

Or, package and then run:

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

Running from IDE

For Eclipse

Right-click the org.codelibs.fess.FessBoot class
Select Run As > Java Application

Or, use the created run configuration:

Click the dropdown of the run button in the toolbar
Select Fess Boot

For IntelliJ IDEA

Right-click the org.codelibs.fess.FessBoot class
Select Run 'FessBoot.main()'

Or, use the created run configuration:

Click the dropdown of the run button in the toolbar
Select Fess Boot

For VS Code

Open src/main/java/org/codelibs/fess/FessBoot.java
Select Run Without Debugging from the Run menu

Verifying Startup

Fess startup takes 1-2 minutes. Startup is complete when you see logs like the following in the console:

[INFO] Boot Thread: Boot process completed successfully.

Access the following in a browser to verify operation:

Search screen: http://localhost:8080/
Admin screen: http://localhost:8080/admin/
- Default user: admin
- Default password: admin

Changing the Port Number

If the default port 8080 is in use, you can change it in the following file:

src/main/resources/fess_config.properties

# Change port number
server.port=8080

Debug Execution

Debug Execution in IDE

For Eclipse

Right-click the org.codelibs.fess.FessBoot class
Select Debug As > Java Application
Set breakpoints to trace code execution

For IntelliJ IDEA

Right-click the org.codelibs.fess.FessBoot class
Select Debug 'FessBoot.main()'
Set breakpoints to trace code execution

For VS Code

Open src/main/java/org/codelibs/fess/FessBoot.java
Select Start Debugging from the Run menu

Remote Debugging

You can also attach a debugger to Fess started from the command line.

Start Fess in debug mode:

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

Connect remote debugger from IDE:

Eclipse:

Select Run > Debug Configurations...
Right-click Remote Java Application and select New Configuration
Set Port: 5005
Click Debug

IntelliJ IDEA:

Select Run > Edit Configurations...
Select + > Remote JVM Debug
Set Port: 5005
Click OK and run Debug

Useful Development Settings

Changing Log Level

Changing the log level during debugging allows you to see detailed information.

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

Enabling Hot Deploy

LastaFlute can reflect some changes without restarting.

Configure the following in src/main/resources/fess_config.properties:

# Enable hot deploy
development.here=true

However, the following changes require a restart:

Changes to class structure (adding/removing methods, etc.)
Changes to configuration files
Changes to dependency libraries

Operating Embedded OpenSearch

In the development environment, an embedded OpenSearch is used.

OpenSearch location:

target/fess/es/

Direct access to OpenSearch API:

# List indices
curl -X GET http://localhost:9201/_cat/indices?v

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

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

Using External OpenSearch

To use an external OpenSearch server, edit src/main/resources/fess_config.properties:

# Disable embedded OpenSearch
opensearch.cluster.name=fess
opensearch.http.url=http://localhost:9200

Code Generation with DBFlute

Fess uses DBFlute to automatically generate Java code from OpenSearch schemas.

Regenerating When Schema Changes

If you change the OpenSearch mapping, regenerate the corresponding Java code with the following commands:

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

Explanation of each command:

rm -rf mydbflute: Remove existing DBFlute working directory
mvn antrun:run: Download OpenSearch plugins
mvn dbflute:freegen: Generate Java code from schema
mvn license:format: Add license headers

Troubleshooting

Build Errors

Error: Java version is old

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

Solution: Install Java 21 or later and set JAVA_HOME appropriately.

Error: Failed to download dependencies

[ERROR] Failed to collect dependencies

Solution: Check network connection, clear Maven local repository and retry:

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

Runtime Errors

Error: Port 8080 is already in use

Address already in use

Solution:

Terminate the process using port 8080
Or, change the port number in fess_config.properties

Error: OpenSearch won’t start

Check the log files in target/fess/es/logs/.

Common causes:

Insufficient memory: Increase JVM heap size
Port 9201 in use: Change port number
Insufficient disk space: Free up disk space

Project Not Recognized in IDE

Update Maven Project

Eclipse: Right-click project > Maven > Update Project
IntelliJ IDEA: Click Reload All Maven Projects in the Maven tool window
VS Code: Run Java: Clean Java Language Server Workspace from the command palette

Next Steps

After completing the development environment setup, refer to the following documents:

Architecture and Code Structure - Understanding code structure
Development Workflow - Learning the development workflow
Build and Test - Build and test methods
Contribution Guide - Creating pull requests

Menu

Development Environment Setup

Installing Eclipse Temurin (Recommended)

Verifying Installation

Setting Environment Variables

Download and Installation

Setting Environment Variables

Verifying Installation

Installing Eclipse

Recommended Plugins

Importing the Project

Setting Run Configuration

Installing IntelliJ IDEA

Importing the Project

Setting Run Configuration

Installing VS Code

Installing Required Extensions

Opening the Project

For Eclipse

For IntelliJ IDEA

For VS Code

For Eclipse

For IntelliJ IDEA

For VS Code