Windows Installation (Detailed Procedure)

This page describes the installation procedure for Fess on Windows environments. It covers the installation method using ZIP packages.

Note

Fess does not bundle a search engine. An OpenSearch server is required, and the steps below set one up.

Prerequisites

System requirements described in System Requirements are met
Java 21 is installed
OpenSearch 3.8.0 is available (or new installation)
Windows environment variable JAVA_HOME is configured appropriately

Verify Java Installation

Open Command Prompt or PowerShell and verify the Java version with the following command.

For Command Prompt:

For PowerShell:

Verify that Java 21 or later is displayed.

Environment Variable Configuration

Set JAVA_HOME Environment Variable

Set the directory where Java is installed as JAVA_HOME.

Example:
```
JAVA_HOME=C:\Program Files\Eclipse Adoptium\jdk-21.0.1.12-hotspot
```
Add to PATH Environment Variable

Add %JAVA_HOME%\bin to the PATH environment variable.

Tip

How to configure environment variables:

Open “Settings” from the Start menu
Click “System” → “About” → “Advanced system settings”
Click the “Environment Variables” button
Configure in “System variables” or “User variables”

Step 1: Install OpenSearch

Tip

bin\fess-setup, included with Fess, performs the steps below in one command. It downloads and extracts OpenSearch into opensearch\ in the Fess directory, installs the required plugins, and adds configsync.config_path and plugins.security.disabled: true to its config\opensearch.yml. Extract the Fess ZIP first, as described in Step 2.

bin\fess.in.bat finds an OpenSearch installed this way and passes its config\dictionary directory to Fess, so “Configure Fess” in Step 2 needs no change as long as OpenSearch runs on the same host. The command prints the settings it added and whether bin\fess.in.bat finds the installation. Read the warning in “Configure OpenSearch” before OpenSearch listens on any address other than localhost.

Follow the steps below to work through them individually, or when using an OpenSearch you already have. To install only the plugins into an existing OpenSearch, use bin\fess-setup install opensearch-plugins --opensearch-home C:\opensearch-3.8.0. See fess-setup Command for all commands.

Download OpenSearch

Download the ZIP package for Windows from Download OpenSearch.
Extract the downloaded ZIP file to any directory.

Example:
```
C:\opensearch-3.8.0
```
Note

It is recommended to select a directory that does not contain Japanese characters or spaces in the path.

Install OpenSearch Plugins

Open Command Prompt with administrator privileges and execute the following commands.

C:\> cd C:\opensearch-3.8.0
C:\opensearch-3.8.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
C:\opensearch-3.8.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
C:\opensearch-3.8.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0
C:\opensearch-3.8.0> bin\opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0

Important

Plugin versions must match the OpenSearch version. In the example above, all are specified as 3.8.0.

Configure OpenSearch

Open config\opensearch.yml with a text editor and add the following settings.

# Configuration synchronization path (specify absolute path)
configsync.config_path: C:/opensearch-3.8.0/data/config/

# Disable security plugin (development environment only)
plugins.security.disabled: true

Warning

Important Security Notice

Use plugins.security.disabled: true only in development or test environments. In production environments, enable the OpenSearch security plugin and configure appropriate authentication and authorization. For details, refer to Security Configuration.

Note

On Windows, use / instead of \ for path separators. Write C:/opensearch-3.8.0/data/config/ instead of C:\opensearch-3.8.0\data\config\.

Tip

Other recommended settings:

Tip

The OpenSearch heap size is configured via -Xms / -Xmx in config\jvm.options. It is recommended to set both -Xms and -Xmx to the same value, targeting no more than half of available physical memory and less than 32 GB.

Step 2: Install Fess

Download Fess

Download the ZIP package for Windows from the download site.
Extract the downloaded ZIP file to any directory.

Example:
```
C:\fess-15.9.0
```
Note

It is recommended to select a directory that does not contain Japanese characters or spaces in the path.

Configure Fess

With an OpenSearch that bin\fess-setup install opensearch installed into opensearch\ in the Fess directory and that runs on the same host, nothing needs to be configured here. Otherwise, for example when OpenSearch was installed by the steps above, runs on another host, or opensearch\ holds more than one OpenSearch installed by bin\fess-setup, configure the connection as follows.

Open bin\fess.in.bat with a text editor. Near the end of this file, the settings for connecting to an external OpenSearch cluster are already present as commented-out lines.

Before (default state):

REM External opensearch cluster
REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200
REM set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch/config/dictionary

Remove the leading REM `` from the bottom two lines to uncomment them, and change the value of ``fess.dictionary.path to the configuration synchronization path for OpenSearch.

After:

REM External opensearch cluster
set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.search_engine.http_address=http://localhost:9200
set FESS_JAVA_OPTS=%FESS_JAVA_OPTS% -Dfess.dictionary.path=C:/opensearch-3.8.0/data/config/

Note

Set fess.dictionary.path to the same path specified for configsync.config_path in OpenSearch’s opensearch.yml.
If OpenSearch is running on a different host, change the hostname or IP address in fess.search_engine.http_address to the appropriate value.
Use / for path separators. Fess inserts the path into the index settings, where a \ is dropped, so a path written with \ is not found.
Do not add new set FESS_JAVA_OPTS=... lines; instead, uncomment and edit the existing commented lines. Specifying the same option more than once may cause unexpected behavior.

Tip

To change the Fess heap size, edit FESS_MIN_MEM (default: 256m) and FESS_MAX_MEM (default: 1g) in bin\fess.in.bat, or set the FESS_HEAP_SIZE environment variable.

Verify Installation

Verify that the configuration files have been edited correctly.

In Command Prompt:

Step 3: Startup

For startup procedures, refer to Startup, Shutdown, and Initial Setup.

Register as Windows Service (Optional)

By registering Fess as a Windows service, you can configure it to start automatically on system startup.

Fess ships with bin\service.bat for registering it as a Windows service. This script uses Apache Commons Daemon (procrun), so no third-party tools such as NSSM are required.

Note

Before running service.bat, verify that the JAVA_HOME environment variable is configured correctly.

Register Fess Service

Open Command Prompt with administrator privileges and execute the following commands.

Register the service:
```
C:\> cd C:\fess-15.9.0
C:\fess-15.9.0> bin\service.bat install
```
By default, the service is registered with the ID fess-service-x64 on 64-bit systems and fess-service-x86 on 32-bit systems. To specify a service ID explicitly, pass it as an argument: bin\service.bat install <ServiceID>.

Start and stop the service:

View and change service settings (GUI):

Remove the service:
```
C:\fess-15.9.0> bin\service.bat remove
```

Note

service.bat internally loads bin\fess.in.bat, so the external OpenSearch connection settings configured in the “Configure Fess” section are also applied to the service.
The default startup type is “Manual”. To start automatically at system boot, either set the environment variable FESS_START_TYPE to auto before registering the service, or change the startup type to “Automatic” in the Services management tool (services.msc) after registration.
service.bat registers only the Fess service. To register OpenSearch as a service, refer to the procedure provided by OpenSearch.

Firewall Configuration

Open the necessary ports in Windows Defender Firewall.

Open “Control Panel” → “Windows Defender Firewall” → “Advanced settings”
Create a new rule in “Inbound Rules”
- Rule type: Port
- Protocol and port: TCP, 8080
- Action: Allow the connection
- Name: Fess Web Interface

Or execute in PowerShell:

Troubleshooting

Port Conflict

If port 8080 or 9200 is already in use, you can check with the following command:

Change the conflicting port number or stop the conflicting process.

Path Length Limitation

Windows has a path length limitation. It is recommended to install in a path as short as possible.

Example:

Java Not Recognized

If the java -version command displays an error:

Verify that the JAVA_HOME environment variable is configured correctly
Verify that %JAVA_HOME%\bin is included in the PATH environment variable
Restart Command Prompt to reflect the settings

Next Steps

After installation is complete, refer to the following documentation:

Startup, Shutdown, and Initial Setup - Starting Fess and initial setup
Security Configuration - Security configuration for production environments
Troubleshooting - Troubleshooting

Frequently Asked Questions

Q: Is operation on Windows Server recommended?

A: Yes, operation on Windows Server is possible. When operating on Windows Server, register as a Windows service and configure appropriate monitoring.

Q: What is the difference between 64-bit and 32-bit versions?

A: Fess and OpenSearch support only the 64-bit version. They will not run on 32-bit Windows.

Q: How to handle paths containing non-ASCII characters?

A: Install in a path that does not contain non-ASCII characters or spaces whenever possible. If you must use a non-ASCII path, you need to properly escape the path in configuration files.