Linux へのインストール (詳細手順)

このページでは、Linux 環境への Fess のインストール手順を説明します。 ZIP、RPM、DEB の各パッケージ形式に対応しています。

注釈

Fess は検索エンジンを同梱していません。OpenSearch サーバーを別途用意する必要があり、 以下の手順で構築します。

前提条件

  • システム要件 に記載されているシステム要件を満たしていること

  • Java 21 がインストールされていること

  • OpenSearch 3.8.0 を利用可能な状態にすること（または新規インストール）

インストール方法の選択

Linux 環境では、以下のインストール方法から選択できます：

方式 推奨環境 特徴
ZIP 開発環境、カスタマイズが必要な環境 任意のディレクトリに展開可能
RPM RHEL、CentOS、Fedora 系 systemd によるサービス管理が可能
DEB Debian、Ubuntu 系 systemd によるサービス管理が可能

OpenSearch 実行のためのシステム設定

OpenSearch を Linux 上で安定して動作させるには、以下のカーネルパラメーターおよびリソース制限を設定します。 これらは主に TAR.GZ 版（OpenSearch を手動でインストールする場合）で必要です。 RPM / DEB 版では OpenSearch および Fess のパッケージが systemd 経由でファイルディスクリプター数などを設定しますが、vm.max_map_count はホスト側のカーネル設定のため、いずれの方式でも確認してください。

仮想メモリーの最大マップ数

OpenSearch は多数のメモリーマップを使用するため、vm.max_map_count を 262144 以上に設定します。

一時的に設定する場合:

$ sudo sysctl -w vm.max_map_count=262144

永続的に設定する場合:

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

ファイルディスクリプター数

OpenSearch を手動で実行する場合（TAR.GZ 版）は、OpenSearch を実行するユーザーのファイルディスクリプター数の上限を 65535 以上に設定します。

/etc/security/limits.conf に以下を追加します（opensearch は OpenSearch を実行するユーザー名に置き換えてください）:

opensearch  -  nofile  65535

注釈

RPM / DEB 版では、systemd のサービス定義でファイルディスクリプター数の上限が設定されるため、この設定は不要です。

ZIP 版でのインストール

ステップ 1: OpenSearch のインストール

重要

OpenSearch は root では起動できないため、一般ユーザーで導入して実行してください。以下の bin/fess-setup も同じユーザーで実行し、展開されるファイルの所有者をそのユーザーにしてください。 root での起動がすでに拒否された場合は、 起動、停止、初期設定 を参照してください。

Tip

Fess に同梱の bin/fess-setup で、以下の手順 1〜3 をまとめて実行できます。OpenSearch を Fess のディレクトリの opensearch/ に取得・展開し、必要なプラグインを導入したうえで、その config/opensearch.yml に configsync.config_path と plugins.security.disabled: true を追加します。先にステップ 2 のとおり Fess の ZIP を展開しておいてください。

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

この方法で導入した OpenSearch は bin/fess.in.sh が見つけて FESS_DICTIONARY_PATH を自動で設定するため、OpenSearch を同じホストで動かす限り、ステップ 2 の「Fess の設定」で変更は必要ありません。コマンドは、追加した設定と、 bin/fess.in.sh がこのインストールを見つけられるかどうかを表示します。OpenSearch を localhost 以外のアドレスで待ち受けさせる前に、手順 3 の警告を確認してください。

手順を個別に確認したい場合や、既存の OpenSearch を使う場合は、以下に従ってください。 既存の OpenSearch にプラグインだけを入れる場合は bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch を使用します。 すべてのコマンドについては fess-setup コマンド を参照してください。

注釈

OpenSearch には macOS 向けの公式配布がないため、macOS では bin/fess-setup install opensearch はエラーで終了します。Homebrew で OpenSearch を導入して bin/fess-setup install opensearch-plugins でプラグインを入れるか、代わりに Docker でのインストール (詳細) を使用してください:

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

そのうえで、手順 3 のとおりに OpenSearch を設定し、ステップ 2 の「Fess の設定」のとおりに FESS_DICTIONARY_PATH を設定してください。

  1. OpenSearch のダウンロード

    Download OpenSearch から TAR.GZ 版をダウンロードします。

    $ 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

    注釈

    この例では OpenSearch 3.8.0 を使用しています。 Fess 15.9 は OpenSearch 3.8.0 に対応しています。

  2. OpenSearch プラグインのインストール

    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

    重要

    プラグインのバージョンは OpenSearch のバージョンと一致させる必要があります。 上記の例では、すべて 3.8.0 を指定しています。

  3. OpenSearch の設定

    config/opensearch.yml に以下の設定を追加します。

    # 設定同期用のパス（絶対パスで指定）
configsync.config_path: /path/to/opensearch-3.8.0/data/config/

# セキュリティプラグインの無効化（開発環境のみ）
plugins.security.disabled: true

    警告

    セキュリティに関する重要な注意

    plugins.security.disabled: true は、開発環境やテスト環境でのみ使用してください。 本番環境では、OpenSearch のセキュリティプラグインを有効にし、適切な認証・認可設定を行ってください。 OpenSearch 2.12 以降でセキュリティプラグインを有効にする場合は、初回起動時に管理者パスワード（環境変数 OPENSEARCH_INITIAL_ADMIN_PASSWORD）の設定が必要です。 詳細は セキュリティ設定 を参照してください。

    Tip

    クラスター名やネットワーク設定など、その他の設定は環境に応じて調整してください。 設定例:

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

    Tip

    OpenSearch のヒープサイズは config/jvm.options の -Xms / -Xmx で設定します。 利用可能な物理メモリの半分以下、かつ 32GB 未満を目安に、-Xms と -Xmx には同じ値を指定することを推奨します。

ステップ 2: Fess のインストール

  1. Fess のダウンロードと展開

    ダウンロードサイト から ZIP 版をダウンロードします。

    $ 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. Fess の設定

    OpenSearch への接続情報は bin/fess.in.sh にあります。 bin/fess-setup install opensearch で Fess のディレクトリの opensearch/ に導入し、同じホストで動かしている OpenSearch であれば、このファイルを変更する必要はありません。 SEARCH_ENGINE_HTTP_URL の既定値は http://localhost:9200 で、 FESS_DICTIONARY_PATH にはその OpenSearch の config/dictionary ディレクトリが設定されます。

    次のいずれかに当てはまる場合は、 bin/fess.in.sh を編集します。

    • OpenSearch を上記の手順 1〜3 や Homebrew など別の方法で導入した場合、または --dest で Fess のディレクトリの外に導入した場合

    • Fess のディレクトリの opensearch/ に、 bin/fess-setup で導入した OpenSearch が 2 つ以上ある場合（2 つのバージョンなど）。 bin/fess.in.sh はどれを使うか判断できないため、警告を表示して FESS_DICTIONARY_PATH を設定しません

    • OpenSearch を別のホストやポートで実行している場合

    $ vi bin/fess.in.sh

    ファイルの先頭付近にある FESS_DICTIONARY_PATH の行のコメント（先頭の #）を解除してパスを設定し、必要に応じて SEARCH_ENGINE_HTTP_URL の行の URL を変更します。

    変更前（既定の状態、コメント行は省略）:

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

    変更後:

    SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://localhost:9200}
FESS_DICTIONARY_PATH=/path/to/opensearch-3.8.0/data/config/

    注釈

    • FESS_DICTIONARY_PATH には、OpenSearch の opensearch.yml で指定した configsync.config_path と同じパスを設定してください。設定しないと、 Fess はインデックスを作成できず、起動しません。

    • OpenSearch を別のホストで実行している場合は、 SEARCH_ENGINE_HTTP_URL の行の URL をそのホストに変更してください。例: SEARCH_ENGINE_HTTP_URL=${SEARCH_ENGINE_HTTP_URL:-http://192.168.1.100:9200} 。このとき FESS_DICTIONARY_PATH には、そのサーバーの configsync.config_path を設定します。

    • ファイルを編集する代わりに、 Fess を起動する環境で両方の変数を export することもできます。export した SEARCH_ENGINE_HTTP_URL はファイルの URL より優先され、export した FESS_DICTIONARY_PATH はファイルの行がコメントのままであれば使用されます。

    • 新たに SEARCH_ENGINE_HTTP_URL=... の行を追加するのではなく、既存の行を編集してください。

    Tip

    Fess のヒープサイズを変更するには、bin/fess.in.sh の FESS_MIN_MEM (既定: 256m) と FESS_MAX_MEM (既定: 2g) を編集するか、環境変数 FESS_HEAP_SIZE を設定します。

  3. インストールの確認

    設定ファイルが正しく編集されたことを確認します:

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

    OpenSearch の起動後は、 bin/fess-setup check で、OpenSearch に接続できるか、 Fess が必要とするプラグインが導入されているか、 configsync が応答するかを確認できます。失敗した項目がなければ終了コード 0 で終了します。OpenSearch が http://localhost:9200 にない場合は --url を指定してください。

ステップ 3: 起動

起動手順については、起動、停止、初期設定 を参照してください。

RPM 版でのインストール

RPM 版は、Red Hat Enterprise Linux、CentOS、Fedora などの RPM ベースの Linux ディストリビューションで使用します。

ステップ 1: OpenSearch のインストール

  1. OpenSearch RPM のダウンロードとインストール

    Download OpenSearch から RPM パッケージをダウンロードしてインストールします。

    $ 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

    または、リポジトリを追加してインストールすることもできます。 詳細は Installing OpenSearch を参照してください。

  2. OpenSearch プラグインのインストール

    $ 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. OpenSearch の設定

    /etc/opensearch/opensearch.yml に以下の設定を追加します。

    $ sudo vi /etc/opensearch/opensearch.yml

    追加する設定:

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

    警告

    本番環境では plugins.security.disabled: true を使用しないでください。 セキュリティ設定 を参照して、適切なセキュリティ設定を行ってください。

ステップ 2: Fess のインストール

  1. Fess RPM のインストール

    ダウンロードサイト から RPM パッケージをダウンロードしてインストールします。

    $ 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. Fess の設定

    RPM 版では、環境変数の設定ファイル /etc/sysconfig/fess を編集します。 このファイルはパッケージのアップグレード時も保持されます（/usr/share/fess/bin/fess.in.sh はアップグレード時に上書きされるため、直接編集しないでください）。

    $ sudo vi /etc/sysconfig/fess

    OpenSearch への接続情報を設定します。既定値は以下のとおりです。必要に応じて変更してください:

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

    注釈

    FESS_DICTIONARY_PATH は、opensearch.yml の configsync.config_path と同じパスを指定してください。

  3. サービスの登録と有効化

    systemd を使用してサービスを有効化します（RHEL 8 以降、CentOS 8 以降では systemd が標準です）:

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

    注釈

    Fess のサービスは OpenSearch のサービスに依存しているため、OpenSearch を先に起動する必要があります。

    注釈

    systemd を使用しない従来の環境では、chkconfig で Fess を登録できます:

    $ sudo /sbin/chkconfig --add fess

ステップ 3: 起動

起動手順については、起動、停止、初期設定 を参照してください。

DEB 版でのインストール

DEB 版は、Debian、Ubuntu などの DEB ベースの Linux ディストリビューションで使用します。

ステップ 1: OpenSearch のインストール

  1. OpenSearch DEB のダウンロードとインストール

    Download OpenSearch から DEB パッケージをダウンロードしてインストールします。

    $ 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

    または、リポジトリを追加してインストールすることもできます。 詳細は Installing OpenSearch を参照してください。

  2. OpenSearch プラグインのインストール

    $ 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. OpenSearch の設定

    /etc/opensearch/opensearch.yml に以下の設定を追加します。

    $ sudo vi /etc/opensearch/opensearch.yml

    追加する設定:

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

    警告

    本番環境では plugins.security.disabled: true を使用しないでください。 セキュリティ設定 を参照して、適切なセキュリティ設定を行ってください。

ステップ 2: Fess のインストール

  1. Fess DEB のインストール

    ダウンロードサイト から DEB パッケージをダウンロードしてインストールします。

    $ 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. Fess の設定

    DEB 版では、環境変数の設定ファイル /etc/default/fess を編集します。 このファイルはパッケージのアップグレード時も保持されます（/usr/share/fess/bin/fess.in.sh はアップグレード時に上書きされるため、直接編集しないでください）。

    $ sudo vi /etc/default/fess

    OpenSearch への接続情報を設定します。既定値は以下のとおりです。必要に応じて変更してください:

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

    注釈

    FESS_DICTIONARY_PATH は、opensearch.yml の configsync.config_path と同じパスを指定してください。

  3. サービスの登録と有効化

    systemd を使用してサービスを有効化します:

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

    注釈

    Fess のサービスは OpenSearch のサービスに依存しているため、OpenSearch を先に起動する必要があります。

ステップ 3: 起動

起動手順については、起動、停止、初期設定 を参照してください。

インストール後の確認

インストールが完了したら、以下を確認してください：

  1. 設定ファイルの確認

    • OpenSearch の設定ファイル（opensearch.yml）

    • Fess の設定ファイル

      • ZIP 版: bin/fess.in.sh

      • RPM 版: /etc/sysconfig/fess

      • DEB 版: /etc/default/fess

  2. ディレクトリのパーミッション

    設定で指定したディレクトリ（configsync.config_path / FESS_DICTIONARY_PATH）が存在し、適切な権限が設定されていることを確認します。

    ZIP 版の場合:

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

    RPM/DEB 版の場合:

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

  3. カーネルパラメーターの確認

    $ sysctl vm.max_map_count

    値が 262144 以上であることを確認します。

  4. Java のバージョン確認

    $ java -version

    Java 21 以降がインストールされていることを確認します。

次のステップ

インストールが完了したら、以下のドキュメントを参照してください：

よくある質問

Q: OpenSearch のバージョンは他のバージョンでも動作しますか？

A: Fess は特定のバージョンの OpenSearch に依存しています。 プラグインの互換性を確保するため、推奨されるバージョン（3.8.0）を使用することを強く推奨します。 他のバージョンを使用する場合は、プラグインのバージョンも適切に調整する必要があります。

Q: 複数の Fess インスタンスで同じ OpenSearch を共有できますか？

A: 可能ですが、推奨されません。各 Fess インスタンスには専用の OpenSearch クラスターを用意することを推奨します。 複数の Fess インスタンスで OpenSearch を共有する場合は、インデックス名の衝突に注意してください。

Q: OpenSearch をクラスター構成にする方法は？

A: OpenSearch の公式ドキュメント Cluster formation を参照してください。 クラスター構成にする場合は、discovery.type: single-node の設定を削除し、適切なクラスター設定を追加する必要があります。