fess-setup Command

bin/fess-setup (bin\fess-setup.bat on Windows) is included with the Fess ZIP package. It installs what Fess needs but does not bundle: OpenSearch with the plugins Fess requires, Node.js for the Playwright plugins, Fess plugins, and static themes. It also reports on an installation.

Run it from the Fess directory. Without arguments, it prints the list of commands.

Exit Codes

Code	Meaning
`0`	The command succeeded.
`1`	The command failed: for example, a download failed, the requested version does not exist, OpenSearch publishes no build for this platform, or `check` found a problem.
`2`	The command line is wrong: an unknown command, or a missing argument such as a plugin name.

Installing OpenSearch and Node.js

install opensearch

Downloads the OpenSearch version this Fess supports into opensearch/ in the Fess directory, installs the four plugins Fess requires (opensearch-analysis-fess, opensearch-analysis-extension, opensearch-minhash and opensearch-configsync), and appends the following settings to its config/opensearch.yml:

configsync.config_path, set to the config/dictionary directory of that OpenSearch
plugins.security.disabled: true

It also removes opensearch-security-analytics and opensearch-performance-analyzer, bundled plugins that Fess does not use, as the OpenSearch in the Docker image does not have them either. A plugin the download does not include is skipped.

A setting that opensearch.yml already has is not added again, and plugins.security.disabled: true is not added when the file has any plugins.security.* setting. When the OpenSearch directory already exists, the download is skipped, so running the command again on an existing installation only adds the settings that are missing.

The command prints each setting it added, and then whether bin/fess.in.sh finds this OpenSearch on its own. It does when this is the only OpenSearch with a config/dictionary directory under opensearch/ in the Fess directory: bin/fess.in.sh (bin\fess.in.bat on Windows) then sets FESS_DICTIONARY_PATH to that directory, and nothing else needs to be configured for an OpenSearch on the same host. Otherwise the command prints the SEARCH_ENGINE_HTTP_URL and FESS_DICTIONARY_PATH values to set, as described in Linux Installation (Detailed Procedure) or Windows Installation (Detailed Procedure).

Option	Description
`--dest <dir>`	The directory to extract OpenSearch into, instead of `opensearch/` in the Fess directory. `bin/fess.in.sh` does not look for OpenSearch outside that directory.
`--version <version>`	The OpenSearch version to install. The plugins are installed at the same version.
`--keep-bundled-plugins`	Keeps the bundled plugins (`opensearch-security-analytics` and `opensearch-performance-analyzer`) instead of removing them, leaving the download as shipped.

OpenSearch publishes official builds for Linux and Windows only. On other platforms, such as macOS, the command exits with code 1 before downloading anything and suggests installing OpenSearch with Homebrew and adding the plugins with install opensearch-plugins, or using Docker.

Warning

With plugins.security.disabled: true, OpenSearch accepts requests without authentication. OpenSearch listens only on the loopback address unless network.host is set. Before it listens on any other address, configure the security plugin instead; see Security Configuration.

install opensearch-plugins

Installs the four plugins Fess requires into an OpenSearch you already have, in place of running its bin/opensearch-plugin install four times. --opensearch-home is the OpenSearch installation directory and is required. --version sets the plugin version, which must match the OpenSearch version.

This command does not change opensearch.yml. Add configsync.config_path and the other settings yourself, as described in Linux Installation (Detailed Procedure) or Windows Installation (Detailed Procedure).

install nodejs

Downloads Node.js, which the Playwright plugins need (fess-crawler-playwright for the Playwright crawler and fess-thumbnail-playwright for thumbnails), into nodejs/ in the Fess directory. bin/fess.in.sh (bin\fess.in.bat on Windows) finds it there and sets PLAYWRIGHT_NODEJS_PATH. With --dest outside the Fess directory, the command prints the PLAYWRIGHT_NODEJS_PATH line to add to bin/fess.in.sh instead. --version selects another Node.js version. See Advanced Crawler Configuration for the Playwright crawler.

Managing Plugins

These commands work on the plugin directory app/WEB-INF/plugin of the Fess installation. Restart Fess after installing, upgrading or removing plugins. Plugins can also be managed from the System > Plugin page in the administration screen; see Plugin.

install plugin, list plugins, list installed, upgrade plugins, remove plugin and check accept --dest <dir>. It names the plugin directory to use instead of app/WEB-INF/plugin: the directory that holds the plugin jars itself, not its parent. A relative path is resolved from the current directory, not from the Fess directory. For install opensearch and install nodejs, --dest is instead the directory the archive is extracted into.

install plugin, list plugins and upgrade plugins accept --repository <url>. It takes the version list, the jars and their checksums from that one Maven repository, such as an internal mirror, instead of the default release and snapshot repositories and GitHub.

--repository also accepts a URL that starts with file:///. On a server with no route to the Internet, put a copy of the Maven repository on the server and name that directory. Name the directory that contains the directory of each plugin (<name>/maven-metadata.xml and so on), the place that corresponds to https://maven.codelibs.org/release/org/codelibs/fess/ of the default repository. Versions are resolved and checksums are verified the same way as with an HTTP repository.

A scheme other than http, https and file, or a URL without a scheme, is refused with a one-line error.

install plugin

Installs one or more Fess plugins, for example fess-script-groovy or fess-ds-git. A name without a version installs the newest version built for this Fess. <name>:<version> pins the version of that plugin, and --version is the version for every name that has none of its own. The previously installed version of a plugin is deleted once the new one has been installed.

A jar comes from the plugin’s GitHub release, or from the Maven repository when the release has no such asset, and is checked against the SHA-1 checksum the Maven repository publishes. A development build of Fess also installs the snapshot builds of its own line, and prefers them.

See Plugin for examples.

Only the plugin types that Fess loads can be installed: names that start with fess-ds-, fess-ingest-, fess-script-, fess-webapp-, fess-thumbnail-, fess-crawler-, fess-llm-, fess-storage- or fess-sso-, the same ones list plugins shows. Any other name (fess-theme-*, or a library such as fess or fess-crawler) is refused with a one-line error and exit code 2 before anything is downloaded. If one of several names is refused, none of them is installed. Install a static theme with install theme.

list plugins

Lists the plugins published for this Fess, and marks the installed ones with (installed: <version>). Plugins that are installed but not published in the repository, such as a locally built jar, are listed separately. A development build of Fess lists the snapshot repository as well.

list installed

Lists the installed plugins and their versions, without contacting the repository.

upgrade plugins

Reinstalls every installed plugin at the version that fits this Fess. A plugin that is already at that version is left as it is. The plugins in app/WEB-INF/plugin are built for one Fess release, so run this command after upgrading Fess.

remove plugin

Deletes the installed jars of the named plugins. A name that is not installed is reported, and does not change the exit code.

Without Internet Access

install plugin, list plugins and upgrade plugins get plugins from repositories on the Internet. The install page under System > Plugin in the administration screen also gets the list of installable plugins from the repositories (plugin.repositories), so it cannot show the list where there is no outside access.

In such an environment, bring in the plugin jars:

Where there is Internet access, download the Fess ZIP package and the jars of the plugins you need. A jar can be downloaded from https://maven.codelibs.org/release/org/codelibs/fess/<name>/<version>/<name>-<version>.jar. Choose the version for this Fess (15.9.x for Fess 15.9).
In the target environment, extract the ZIP and put the jars in app/WEB-INF/plugin/. After Fess starts, you can also upload them on the “Local” tab of the plugin install page in the administration screen; see Plugin.
Start Fess. If you put the jars there while it was running, restart it.

Instead of bringing in each jar, you can also copy the needed part of the Maven repository (the org/codelibs/fess/<name>/ directories) to the server and install with install plugin and --repository file:///.... The checksums are verified in this case too.

Managing Themes

These commands work on the theme directory app/themes of the Fess installation. Restart Fess after installing or removing a theme, or click [Reload] on the System > Theme page. Themes can also be uploaded from that page; see Theme.

install theme, list themes and remove theme accept --dest <dir> in the same way, naming the theme directory to use instead of app/themes.

A theme’s version is the Fess line it targets, so 15.9.0 is a theme for Fess 15.9. A name without a version therefore resolves to the theme built for this Fess, the same way a plugin version does.

install theme

Installs one or more static themes, for example docuforge or voicebox. A name without a version installs the newest one built for this Fess. <name>:<version> pins the version of that theme, and --version is the version for every name that has none of its own.

The archive is checked against the SHA-1 checksum the Maven repository publishes, and extracted into app/themes/<name>. A theme already installed under that name is kept as a backup for the same period as one replaced from the administration screen (default 7 days, theme.upload.attic.retention.days).

The download, the extraction and the manifest check all happen before anything installed is touched, so a theme that is already there survives a failed install. An archive whose theme.yml names a different theme is rejected.

list themes

Lists the themes published for this Fess, and marks the installed ones with (installed: <version>). Themes that are installed but not listed by the repository are shown separately.

The list is read from the repository’s directory index, which is generated periodically. When it cannot be read, the command reports the URL it tried and still lists the installed themes: a theme can be installed by naming it whether or not the index lists it.

remove theme

Deletes the named themes from app/themes, keeping each as a backup for the retention period. A name that is not installed is reported, and does not change the exit code.

If a removed theme was the default, Fess falls back to the bundled bootstrap theme until another one is chosen.

Checking an Installation

list

Shows the components that install downloads, opensearch and nodejs, with the version of each.

check

Reports on the installation, one line per check, each marked OK, WARN or FAIL:

The search engine: whether it is reachable, its version (a warning when the nodes report different versions), whether the four plugins Fess requires are installed in it, and whether configsync responds.
Fess: whether the plugin directory exists and is writable, each installed plugin (a failure for a plugin built for another Fess release and for a plugin installed in two versions), and whether Node.js is installed in nodejs/ in the Fess directory.

The engine URL is --url, otherwise the SEARCH_ENGINE_HTTP_URL environment variable, otherwise http://localhost:9200. bin/fess-setup does not read bin/fess.in.sh, so pass --url when OpenSearch is somewhere else. A missing Node.js is only reported, unless --playwright is given, which makes it a failure.

The command exits with code 0 when no check failed, even if some produced warnings, and with code 1 otherwise.