Linux Installation (Detailed Procedure)

This page describes the installation procedure for Fess on Linux environments. It covers the ZIP, RPM, and DEB package formats.

Note

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

Prerequisites

  • The system requirements described in System Requirements are met

  • Java 21 is installed

  • OpenSearch 3.8.0 is available for use (or is newly installed)

Choosing an Installation Method

For Linux environments, you can choose from the following installation methods:

Method Recommended Environments Features
ZIP Development environments, environments requiring customization Can be extracted to any directory
RPM RHEL, CentOS, Fedora systems Service management via systemd possible
DEB Debian, Ubuntu systems Service management via systemd possible

System Configuration for Running OpenSearch

To run OpenSearch stably on Linux, configure the following kernel parameters and resource limits. These are mainly required for the TAR.GZ version (when installing OpenSearch manually). For the RPM / DEB versions, the OpenSearch and Fess packages configure settings such as the file descriptor limit via systemd, but since vm.max_map_count is a host-level kernel setting, be sure to check it regardless of which installation method you use.

Maximum Map Count for Virtual Memory

Because OpenSearch uses a large number of memory maps, set vm.max_map_count to 262144 or higher.

To set this temporarily:

$ sudo sysctl -w vm.max_map_count=262144

To set this persistently:

$ echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
$ sudo sysctl -p

File Descriptor Limit

When running OpenSearch manually (TAR.GZ version), set the file descriptor limit for the user running OpenSearch to 65535 or higher.

Add the following to /etc/security/limits.conf (replace opensearch with the username that runs OpenSearch):

opensearch  -  nofile  65535

Note

For the RPM / DEB versions, this setting is not necessary because the file descriptor limit is configured in the systemd service definition.

Installation with ZIP Version

Step 1: Install OpenSearch

Important

Install and run OpenSearch as a regular user, not as root: OpenSearch refuses to start as root. Run bin/fess-setup below as that user as well, so that the files it extracts belong to that user. See Startup, Shutdown, and Initial Setup if a start as root has already been refused.

Tip

bin/fess-setup, included with Fess, performs steps 1 to 3 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.

$ cd /path/to/fess-15.9.0
$ bin/fess-setup install opensearch

bin/fess.in.sh finds an OpenSearch installed this way and sets FESS_DICTIONARY_PATH on its own, 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.sh finds the installation. Read the warning in step 3 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 /path/to/opensearch. See fess-setup Command for all commands.

Note

OpenSearch publishes no macOS build, so on macOS bin/fess-setup install opensearch exits with an error. Install OpenSearch with Homebrew and add the plugins with bin/fess-setup install opensearch-plugins, or use Docker Installation (Detailed Guide) instead:

$ brew install opensearch
$ bin/fess-setup install opensearch-plugins --opensearch-home $(brew --prefix opensearch)

Then configure that OpenSearch as in step 3, and set FESS_DICTIONARY_PATH as described in “Configure Fess” in Step 2.

  1. Download OpenSearch

    Download the TAR.GZ version from Download OpenSearch.

    $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.8.0/opensearch-3.8.0-linux-x64.tar.gz
$ tar -xzf opensearch-3.8.0-linux-x64.tar.gz
$ cd opensearch-3.8.0

    Note

    This example uses OpenSearch 3.8.0. Fess 15.9 supports OpenSearch 3.8.0.

  2. Install OpenSearch Plugins

    Install the plugins required by Fess.

    $ cd /path/to/opensearch-3.8.0
$ ./bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
$ ./bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
$ ./bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash: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.

  3. Configure OpenSearch

    Add the following settings to config/opensearch.yml.

    # Path for configuration synchronization (specify an absolute path)
configsync.config_path: /path/to/opensearch-3.8.0/data/config/

# Disable the security plugin (development environments 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. When enabling the security plugin on OpenSearch 2.12 or later, you must set the administrator password (environment variable OPENSEARCH_INITIAL_ADMIN_PASSWORD) at the first startup. For details, refer to Security Configuration.

    Tip

    Adjust other settings, such as the cluster name and network settings, according to your environment. Example configuration:

    cluster.name: fess-cluster
node.name: fess-node-1
network.host: 0.0.0.0
discovery.type: single-node

    Tip

    The OpenSearch heap size is configured with -Xms / -Xmx in config/jvm.options. As a guideline, use no more than half of the available physical memory and less than 32GB, and it is recommended to specify the same value for -Xms and -Xmx.

Step 2: Install Fess

  1. Download and Extract Fess

    Download the ZIP version from the download site.

    $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.zip
$ unzip fess-15.9.0.zip
$ cd fess-15.9.0

  2. Configure Fess

    The connection information to OpenSearch is in bin/fess.in.sh. With an OpenSearch that bin/fess-setup install opensearch installed into opensearch/ in the Fess directory and that runs on the same host, this file needs no change: SEARCH_ENGINE_HTTP_URL defaults to http://localhost:9200, and FESS_DICTIONARY_PATH is set to the config/dictionary directory of that OpenSearch.

    Edit bin/fess.in.sh in any of the following cases:

    • OpenSearch was installed another way, such as by steps 1 to 3 above or with Homebrew, or with --dest outside the Fess directory.

    • opensearch/ in the Fess directory holds more than one OpenSearch installed by bin/fess-setup, for example two versions. bin/fess.in.sh cannot tell which one is in use, so it prints a warning and leaves FESS_DICTIONARY_PATH unset.

    • OpenSearch runs on another host or port.

    $ vi bin/fess.in.sh

    Near the top of the file, remove the leading # from the FESS_DICTIONARY_PATH line and set the path, and change the URL in the SEARCH_ENGINE_HTTP_URL line if needed.

    Before (default state, comment lines omitted):

    SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200}
#FESS_DICTIONARY_PATH=/var/lib/opensearch/config/

    After:

    SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200}
FESS_DICTIONARY_PATH=/path/to/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. Without it, Fess cannot create its indices and does not start.

    • If OpenSearch is running on a different host, change the URL in the SEARCH_ENGINE_HTTP_URL line to that host. Example: SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200}. FESS_DICTIONARY_PATH is then the configsync.config_path of that server.

    • Instead of editing the file, both variables can be exported in the environment Fess is started from. An exported SEARCH_ENGINE_HTTP_URL takes precedence over the URL in the file, and an exported FESS_DICTIONARY_PATH is used as long as its line in the file stays commented out.

    • Rather than adding a new SEARCH_ENGINE_HTTP_URL=... line, edit the existing one.

    Tip

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

  3. Verify Installation

    Verify that the configuration file has been edited correctly:

    $ grep "SEARCH_ENGINE_HTTP_URL" bin/fess.in.sh
$ grep "FESS_DICTIONARY_PATH" bin/fess.in.sh

    Once OpenSearch is running, bin/fess-setup check reports whether it is reachable, whether it has the plugins Fess requires, and whether configsync responds. It exits with code 0 when no check failed. Pass --url when OpenSearch is not at http://localhost:9200.

Step 3: Startup

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

Installation with RPM Version

The RPM version is used on RPM-based Linux distributions such as Red Hat Enterprise Linux, CentOS, and Fedora.

Step 1: Install OpenSearch

  1. Download and Install OpenSearch RPM

    Download the RPM package from Download OpenSearch and install it.

    $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.8.0/opensearch-3.8.0-linux-x64.rpm
$ sudo rpm -ivh opensearch-3.8.0-linux-x64.rpm

    Alternatively, you can add a repository and install from it. For details, refer to Installing OpenSearch.

  2. Install OpenSearch Plugins

    $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0

  3. Configure OpenSearch

    Add the following settings to /etc/opensearch/opensearch.yml.

    $ sudo vi /etc/opensearch/opensearch.yml

    Settings to add:

    configsync.config_path: /var/lib/opensearch/data/config/
plugins.security.disabled: true

    Warning

    Do not use plugins.security.disabled: true in production environments. Refer to Security Configuration for appropriate security configuration.

Step 2: Install Fess

  1. Install Fess RPM

    Download the RPM package from the download site and install it.

    $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.rpm
$ sudo rpm -ivh fess-15.9.0.rpm

  2. Configure Fess

    For the RPM version, edit the environment variable configuration file /etc/sysconfig/fess. This file is preserved across package upgrades (do not edit /usr/share/fess/bin/fess.in.sh directly, since it is overwritten during upgrades).

    $ sudo vi /etc/sysconfig/fess

    Configure the connection information to OpenSearch. The default values are as follows. Change them as needed:

    SEARCH_ENGINE_HTTP_URL=http://localhost:9200
FESS_DICTIONARY_PATH=/var/lib/opensearch/config/

    Note

    Set FESS_DICTIONARY_PATH to the same path as configsync.config_path in opensearch.yml.

  3. Register and Enable the Service

    Enable the services using systemd (systemd is the standard on RHEL 8 and later, and CentOS 8 and later):

    $ sudo systemctl daemon-reload
$ sudo systemctl enable opensearch.service
$ sudo systemctl enable fess.service

    Note

    Because the Fess service depends on the OpenSearch service, OpenSearch must be started first.

    Note

    On legacy environments that do not use systemd, you can register Fess with chkconfig:

    $ sudo /sbin/chkconfig --add fess

Step 3: Startup

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

Installation with DEB Version

The DEB version is used on DEB-based Linux distributions such as Debian and Ubuntu.

Step 1: Install OpenSearch

  1. Download and Install OpenSearch DEB

    Download the DEB package from Download OpenSearch and install it.

    $ wget https://artifacts.opensearch.org/releases/bundle/opensearch/3.8.0/opensearch-3.8.0-linux-x64.deb
$ sudo dpkg -i opensearch-3.8.0-linux-x64.deb

    Alternatively, you can add a repository and install from it. For details, refer to Installing OpenSearch.

  2. Install OpenSearch Plugins

    $ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-fess:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-analysis-extension:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-minhash:3.8.0
$ sudo /usr/share/opensearch/bin/opensearch-plugin install org.codelibs.opensearch:opensearch-configsync:3.8.0

  3. Configure OpenSearch

    Add the following settings to /etc/opensearch/opensearch.yml.

    $ sudo vi /etc/opensearch/opensearch.yml

    Settings to add:

    configsync.config_path: /var/lib/opensearch/data/config/
plugins.security.disabled: true

    Warning

    Do not use plugins.security.disabled: true in production environments. Refer to Security Configuration for appropriate security configuration.

Step 2: Install Fess

  1. Install Fess DEB

    Download the DEB package from the download site and install it.

    $ wget https://github.com/codelibs/fess/releases/download/fess-15.9.0/fess-15.9.0.deb
$ sudo dpkg -i fess-15.9.0.deb

  2. Configure Fess

    For the DEB version, edit the environment variable configuration file /etc/default/fess. This file is preserved across package upgrades (do not edit /usr/share/fess/bin/fess.in.sh directly, since it is overwritten during upgrades).

    $ sudo vi /etc/default/fess

    Configure the connection information to OpenSearch. The default values are as follows. Change them as needed:

    SEARCH_ENGINE_HTTP_URL=http://localhost:9200
FESS_DICTIONARY_PATH=/var/lib/opensearch/config/

    Note

    Set FESS_DICTIONARY_PATH to the same path as configsync.config_path in opensearch.yml.

  3. Register and Enable the Service

    Enable the services using systemd:

    $ sudo systemctl daemon-reload
$ sudo systemctl enable opensearch.service
$ sudo systemctl enable fess.service

    Note

    Because the Fess service depends on the OpenSearch service, OpenSearch must be started first.

Step 3: Startup

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

Post-Installation Verification

After the installation is complete, verify the following:

  1. Verify Configuration Files

    • OpenSearch configuration file (opensearch.yml)

    • Fess configuration file

      • ZIP version: bin/fess.in.sh

      • RPM version: /etc/sysconfig/fess

      • DEB version: /etc/default/fess

  2. Directory Permissions

    Verify that the directories specified in the configuration (configsync.config_path / FESS_DICTIONARY_PATH) exist and have appropriate permissions set.

    For the ZIP version:

    $ ls -ld /path/to/opensearch-3.8.0/data/config/

    For the RPM/DEB versions:

    $ sudo ls -ld /var/lib/opensearch/data/config/

  3. Verify Kernel Parameters

    $ sysctl vm.max_map_count

    Verify that the value is 262144 or higher.

  4. Verify Java Version

    $ java -version

    Verify that Java 21 or later is installed.

Next Steps

After installation is complete, refer to the following documentation:

Frequently Asked Questions

Q: Will other versions of OpenSearch work?

A: Fess depends on a specific version of OpenSearch. To ensure plugin compatibility, it is strongly recommended to use the recommended version (3.8.0). If you use a different version, you must also adjust the plugin versions appropriately.

Q: Can multiple Fess instances share the same OpenSearch?

A: It is possible, but not recommended. We recommend providing a dedicated OpenSearch cluster for each Fess instance. If you share OpenSearch among multiple Fess instances, be careful of index name conflicts.

Q: How do I configure OpenSearch as a cluster?

A: Refer to the official OpenSearch documentation Cluster formation. For a cluster configuration, you must remove the discovery.type: single-node setting and add appropriate cluster settings.