Upgrade Procedure

This page describes the procedures for upgrading Fess from a previous version to the latest release.

Warning

Important Notes Before Upgrade

• Always create a backup before upgrading

• It is strongly recommended to validate the upgrade in a test environment first

• Services will be stopped during the upgrade, so schedule appropriate maintenance time

• Configuration file formats may have changed depending on the version

Supported Versions

This upgrade procedure supports upgrades between the following versions:

• Fess 14.x → Fess 15.7

• Fess 15.x → Fess 15.7

Note

When upgrading from older versions (13.x or earlier), a phased upgrade may be necessary. For details, check the release notes.

Pre-Upgrade Preparation

Verify Version Compatibility

Verify the compatibility between the upgrade target version and the current version.

• Release Notes

• Upgrade Guide

Plan Downtime

The upgrade process requires system shutdown. Plan downtime considering the following:

• Backup time: 10 minutes to several hours (depending on data volume)

• Upgrade time: 10 to 30 minutes

• Verification time: 30 minutes to 1 hour

• Reserve time: 30 minutes

Recommended Maintenance Time: Total 2 to 4 hours

Step 1: Data Backup

Back up all data before upgrading.

Configuration Data Backup

1. Backup from Admin Screen

   Log in to the admin screen and click “System Info” → “Backup”.

   The backup page lists the following configuration data as individual items. Click each link to download it (these are individual files per item, not a single ZIP):

   • fess_basic_config.bulk - Basic configuration (general settings)

   • fess_config.bulk - Crawl settings, scheduler, labels, key matches, and other configuration

   • fess_user.bulk - Users, roles, and groups

   • system.properties - System settings

   • fess.json / doc.json - Index settings (mappings)

   Note

   Log data such as search logs and click logs (search_log.ndjson, click_log.ndjson, favorite_log.ndjson, user_info.ndjson) can also be downloaded from the same page. They are not needed if you only want to back up the configuration.

2. Configuration File Backup

   TAR.GZ/ZIP version:

   $ cp /path/to/fess/app/WEB-INF/conf/system.properties /backup/
   $ cp /path/to/fess/app/WEB-INF/classes/fess_config.properties /backup/
   

   RPM/DEB version:

   $ sudo cp /etc/fess/system.properties /backup/
   $ sudo cp /etc/fess/fess_config.properties /backup/
   

3. Customized Configuration Files

   If you have customized configuration files, back up those as well:

   $ cp /path/to/fess/app/WEB-INF/classes/log4j2.xml /backup/
   

Index Data Backup

Back up OpenSearch index data.

Method 1: Use Snapshot Feature (Recommended)

Back up the index using OpenSearch snapshot feature.

Note

To register a filesystem (fs) repository, you must first specify the backup destination directory in path.repo in OpenSearch’s opensearch.yml and restart OpenSearch.

1. Configure repository:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup" -H 'Content-Type: application/json' -d'
   {
     "type": "fs",
     "settings": {
       "location": "/backup/opensearch/snapshots"
     }
   }'
   

2. Create snapshot:

   $ curl -X PUT "http://localhost:9200/_snapshot/fess_backup/snapshot_1?wait_for_completion=true"
   

3. Verify snapshot:

   $ curl -X GET "http://localhost:9200/_snapshot/fess_backup/snapshot_1"
   

Method 2: Backup Entire Directory

Stop OpenSearch and back up the data directory.

$ sudo systemctl stop opensearch
$ sudo tar czf /backup/opensearch-data-$(date +%Y%m%d).tar.gz /var/lib/opensearch/data
$ sudo systemctl start opensearch

Docker Version Backup

OpenSearch data is stored in Docker volumes. compose-opensearch3.yaml defines two volumes: search01_data for index data and search01_dictionary for dictionary files.

Note

The actual volume names are prefixed with the Compose project name (by default, the name of the directory containing the Compose files). Check the exact names with:

$ docker volume ls

Stop the containers, then back up the volumes:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml stop
$ docker run --rm -v search01_data:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-data-backup.tar.gz /data
$ docker run --rm -v search01_dictionary:/data -v $(pwd):/backup ubuntu tar czf /backup/search01-dictionary-backup.tar.gz /data
$ docker compose -f compose.yaml -f compose-opensearch3.yaml start

Step 2: Stop Current Version

Stop Fess and OpenSearch.

TAR.GZ/ZIP version:

$ kill <fess_pid>
$ kill <opensearch_pid>

RPM/DEB version (systemd):

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Docker version:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml down

Step 3: Install New Version

The procedure varies depending on the installation method.

TAR.GZ/ZIP Version

1. Download and extract the new version:

   $ wget https://github.com/codelibs/fess/releases/download/fess-15.7.0/fess-15.7.0.tar.gz
   $ tar -xzf fess-15.7.0.tar.gz
   

2. Copy configuration from the old version:

   $ cp /path/to/old-fess/app/WEB-INF/conf/system.properties /path/to/fess-15.7.0/app/WEB-INF/conf/
   $ cp /path/to/old-fess/bin/fess.in.sh /path/to/fess-15.7.0/bin/
   

3. Verify configuration differences and adjust as necessary

RPM/DEB Version

Install the new version package:

# RPM
$ sudo rpm -Uvh fess-15.7.0.rpm

# DEB
$ sudo dpkg -i fess-15.7.0.deb

Note

Configuration files (/etc/fess/*) are automatically retained. However, if new configuration options have been added, manual adjustment may be necessary.

Docker Version

1. Obtain Compose files for the new version:

   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.7.0/compose/compose.yaml
   $ wget https://raw.githubusercontent.com/codelibs/docker-fess/v15.7.0/compose/compose-opensearch3.yaml
   

2. Pull new images:

   $ docker compose -f compose.yaml -f compose-opensearch3.yaml pull
   

Step 4: Upgrade OpenSearch (If Necessary)

If you are also upgrading OpenSearch, follow these procedures.

Note

This procedure applies when you are managing OpenSearch manually on a TAR.GZ/ZIP or RPM/DEB installation. For the Docker version, pulling the new image in Step 3 updates OpenSearch and its plugins together, so this step is not required.

Warning

Be careful when performing major version upgrades of OpenSearch. Index compatibility issues may occur.

1. Install the new version of OpenSearch

2. Reinstall plugins:

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

   Note

   The version of these plugins must match the version of OpenSearch you use. Fess 15.7 supports OpenSearch 3.7.0. Installation fails if the versions do not match.

3. Start OpenSearch:

   $ sudo systemctl start opensearch.service
   

Step 5: Start New Version

TAR.GZ/ZIP version:

$ cd /path/to/fess-15.7.0
$ ./bin/fess -d

RPM/DEB version:

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Docker version:

$ docker compose -f compose.yaml -f compose-opensearch3.yaml up -d

Step 6: Verify Operation

1. Check Logs

   Verify there are no errors:

   $ tail -f /path/to/fess/logs/fess.log
   

2. Access Web Interface

   Access http://localhost:8080/ in a browser.

3. Log in to Admin Screen

   Access http://localhost:8080/admin and log in with the administrator account.

4. Check the Version

   In the admin UI, click “System Info” → “Config Info” and confirm that fess.version shown under “System Properties” reflects the new version.

5. Verify Search Operation

   Execute a search on the search screen and verify results are returned normally.

Step 7: Recreate Index (Recommended)

For major version upgrades, it is recommended to recreate the index.

1. Verify existing crawl schedules

2. Execute “Default Crawler” from “System” → “Scheduler”

3. Wait for crawl to complete

4. Verify search results

Rollback Procedure

If the upgrade fails, you can rollback with the following procedure.

Step 1: Stop New Version

$ sudo systemctl stop fess.service
$ sudo systemctl stop opensearch.service

Step 2: Restore Old Version

Restore configuration files and data from backup.

For RPM/DEB version:

$ sudo rpm -Uvh --oldpackage fess-<old-version>.rpm

Or:

$ sudo dpkg -i fess-<old-version>.deb

Step 3: Restore Data

Restore from snapshot:

$ curl -X POST "http://localhost:9200/_snapshot/fess_backup/snapshot_1/_restore?wait_for_completion=true"

Or restore directory from backup:

$ sudo systemctl stop opensearch
$ sudo rm -rf /var/lib/opensearch/data/*
$ sudo tar xzf /backup/opensearch-data-backup.tar.gz -C /
$ sudo systemctl start opensearch

Note

Configuration data downloaded from the admin screen (*.bulk files) can be re-imported after starting Fess via the upload feature on the “System Info” → “Backup” page.

Step 4: Start and Verify Service

$ sudo systemctl start opensearch.service
$ sudo systemctl start fess.service

Verify operation and confirm it has returned to normal.

Frequently Asked Questions

Q: Can I upgrade without downtime?

A: Upgrading Fess requires service shutdown. To minimize downtime, consider the following:

• Verify procedures in a test environment first

• Create backups in advance

• Secure sufficient maintenance time

Q: Do I need to upgrade OpenSearch too?

A: Each version of Fess requires a specific version of OpenSearch. Fess 15.7 requires OpenSearch 3.7.0. The Fess OpenSearch plugins such as opensearch-analysis-fess must exactly match the OpenSearch version, so if you upgrade OpenSearch, also update the plugins to the corresponding version (3.7.0).

Q: Do I need to recreate the index?

A: For minor version upgrades, it is usually not necessary, but for major version upgrades, recreation is recommended.

Q: Search results are not displayed after upgrade

A: Verify the following:

1. Verify OpenSearch is running

2. Verify indexes exist (curl http://localhost:9200/_cat/indices)

3. Re-run crawl

Next Steps

After the upgrade is complete:

• Startup, Shutdown, and Initial Setup - Verify startup and initial configuration

• Security Configuration - Review security configuration

• Check release notes for new features