Developer Documentation Overview

Overview

This section explains extension development for Fess. It provides information for extending Fess, including plugin development, custom connector creation, and theme customization.

Target Audience

Developers who want to create custom features for Fess
Developers who want to create plugins
Developers who want to understand the Fess source code

Prerequisites

Basic knowledge of Java 21
Basics of Maven (build system)
Experience with web application development
Basic knowledge of OpenSearch (Fess uses OpenSearch as its search engine)

Development Environment

Recommended Environment

JDK: OpenJDK 21 or higher
IDE: IntelliJ IDEA / Eclipse / VS Code
Build Tool: Maven (the build does not enforce a minimum version, but a recent 3.x release that supports Java 21 is recommended)
Git: Version control
OpenSearch: Search engine backend (when launching from the IDE, the required modules and plugins are downloaded during the build)

Setup

Fess is built as a Maven project. During development, the easiest way is to launch it from an IDE.

Get the source code:

Import into the IDE:

Import the cloned directory into your IDE as a Maven project.
Download the OpenSearch modules and plugins:

The first time only, run the following command to fetch the search engine’s modules and plugins into the plugins directory.
```
mvn antrun:run
```
Start the development server (from the IDE):

Run or debug org.codelibs.fess.FessBoot in your IDE, then open http://localhost:8080/ in your browser. The admin screen is at http://localhost:8080/admin/ (default account: admin / admin).
Build the package (create a distribution):

If you need a distribution package, run the package goal. The artifact is generated in target/releases (add -DskipTests to skip unit tests).
```
mvn package
```
After extracting the generated distribution, the bin/fess startup script becomes available.
```
unzip target/releases/fess-*.zip
./fess-*/bin/fess
```

Note

The bin/fess startup script is included in the distribution packages (zip/rpm/deb). Simply running mvn package in the source tree does not generate bin/fess at the root of the repository. For development from source, either run FessBoot in your IDE as described above, or use bin/fess from an extracted distribution.

Architecture Overview

Fess consists of the following major components:

Component Structure

Component	Description
Web Layer	MVC implementation using the LastaFlute framework
Service Layer	Business logic
Data Access Layer	Type-safe OpenSearch access using DBFlute (ESFlute/FreeGen)
Crawler	Content collection using the fess-crawler library
Search Engine	Full-text search using OpenSearch

Major Frameworks

LastaFlute: Web framework (actions, forms, validation)
DBFlute: Data access framework. The type-safe access classes for OpenSearch (Bhv / ConditionBean) are generated by DBFlute’s FreeGen feature together with ESFlute templates (regenerate with mvn dbflute:freegen)
Lasta Di: Dependency injection container

Directory Structure

fess/
├── src/main/java/org/codelibs/fess/
│   ├── app/
│   │   ├── web/         # Controllers (Action)
│   │   ├── service/     # Services
│   │   ├── logic/       # Logic
│   │   └── pager/       # Pagination
│   ├── api/             # REST API (api/v2, etc.)
│   ├── helper/          # Helper classes
│   ├── crawler/         # Crawler related
│   ├── indexer/         # Index processing
│   ├── opensearch/      # OpenSearch access (ESFlute/FreeGen generated)
│   ├── llm/             # LLM integration
│   ├── ds/              # DataStore connectors
│   ├── ingest/          # Ingest (data processing during indexing)
│   ├── script/          # Script engine
│   ├── entity/          # Entities
│   └── mylasta/         # LastaFlute configuration (DI, messages, type-safe settings)
├── src/main/resources/
│   ├── fess_config.properties  # Configuration
│   └── fess_*.xml              # DI configuration (app.xml, fess_ds.xml, etc.)
└── src/main/webapp/
    └── WEB-INF/view/    # JSP templates

Extension Points

Fess provides the following extension points:

Plugins

You can add features using plugins.

DataStore Plugin: Crawl from new data sources (extend AbstractDataStore)
Script Engine Plugin: Support for new scripting languages (implement ScriptEngine)
Web App Plugin: Extend the web interface (override Lasta Di components and merge resources)
Ingest Plugin: Process data during indexing (extend Ingester)

Details: Plugin Architecture

Note

The Fess core is packaged as a war. When building a plugin locally, if Fess cannot be resolved as a dependency, temporarily change <packaging> in pom.xml to jar, run mvn clean install -DskipTests, and then change it back to war.

Themes

You can customize the design of the search screen.

Details: Theme Development Guide

Configuration

Many behaviors can be customized via fess_config.properties.

Details: Introduction to Configuration

Plugin Development

For details on plugin development, see the following:

Plugin Architecture - Plugin architecture
Data Store Plugin Development - DataStore plugin development
Script Engine Plugin - Script engine plugin
Web App Plugin - Web app plugin
Ingest Plugin - Ingest plugin

Theme Development

Theme Development Guide - Theme customization

Best Practices

Coding Standards

Follow the existing Fess code style
Format code with mvn formatter:format
Add license headers with mvn license:format

Testing

Unit tests (*Test.java): Run as mvn test under the default build profile
Integration tests (*Tests.java): Run via mvn test -P integrationTests. Running integration tests requires a running Fess server and OpenSearch

Logging

Uses Log4j2
logger.debug() / logger.info() / logger.warn() / logger.error()
Do not log sensitive information