Skip to content

docs(15.9): move the install and upgrade guides to OpenSearch 3.9.0 and document the reindex an upgraded index needs - #564

Merged
marevol merged 1 commit into
mainfrom
docs/159-opensearch-390-and-reindex
Oct 3, 2026
Merged

marevol merged 1 commit into
mainfrom
docs/159-opensearch-390-and-reindex

Conversation

@marevol

@marevol marevol commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

Summary

Fess 15.9 now runs on OpenSearch 3.9.0 (codelibs/fess#3537), and bin/fess-setup install opensearch installs 3.9.0, but the 15.9 pages still told readers to set up OpenSearch 3.8.0 and its 3.8.0 plugins. This PR moves the 15.9 tree to 3.9.0 and adds the reindex step an index created by 15.8 needs. All seven languages (ja, en, de, es, fr, ko, zh-cn) are changed the same way.

OpenSearch 3.9.0

  • The OpenSearch version Fess 15.9 uses is now 3.9.0 in install, install-linux, install-windows, prerequisites, run, troubleshooting, uninstall and upgrade. This covers download URLs, paths, the fess-opensearch image tag and the supported-version statements.
  • Two kinds of sentence still say 3.8.0 on purpose:
    • "OpenSearch 3.8.0 and later refuse dictionaries outside the configuration directory": the behaviour started in 3.8.0.
    • The configsync 3.8.0 note in admin-index-backup: it describes older plugin versions.
  • The plugin install commands now use the URL form. Since 3.8.1, opensearch-analysis-fess, opensearch-analysis-extension, opensearch-minhash and opensearch-configsync are published only on maven.codelibs.org. opensearch-plugin install resolves the groupId:artifactId:version form against Maven Central only, so that form fails for 3.9.0.
    • Checked: the 3.9.0 zips return 200 on maven.codelibs.org and 404 on Maven Central, where the latest version is 3.8.0.
    • The commands now use the maven.codelibs.org URL, as the docker-fess opensearch/3.9 image does, and each command block says why.
  • Step 4 of the upgrade guide now notes that a snapshot taken on 3.9.0 cannot be restored to 3.8.0 or earlier.

Reindexing a document index created by 15.8

At startup, 15.9 adds missing fields to the configuration, log and user indices only (codelibs/fess#3517). It leaves the document index alone, so an index created by 15.8 does not get two 15.9 changes:

  • Owner fields (#3528): owner and last_modifier are mapped dynamically as text. As a result, owner:alice and facet.field=owner do not work.
  • Kana normalization (#3532): the normalization of kana variants and of dashes written as long vowels lives in the index analysis settings and in mapping.txt, so the existing index never receives it.

The new upgrade section "Applying New Fields and Kana Normalization to an Existing Document Index" says:

  • To apply both without crawling again, run Re-indexing with Replace Aliases and Reset Dictionaries on the Maintenance page.
  • Reset Dictionaries overwrites the dictionaries with the bundled files. That is how SearchEngineClient#createIndex uploads them. Anyone who edited synonyms or other dictionaries should download them first and apply them again afterwards.
  • Files indexed before the upgrade have no owner until they are fetched again. Incremental crawling skips unchanged files, so this needs one crawl with Check Last Modified turned off.

Step 7 and the "Do I need to recreate the index?" FAQ now link to this section. The option names follow the admin labels (labels.upgrade_reindex, labels.replace_aliases, labels.reset_dictionaries, labels.incremental_crawling) in each locale.

Verification

  • Plugin versions: the 3.9.0 zips of the four plugins return 200 on maven.codelibs.org. The OpenSearch 3.9.0 tar.gz, rpm, deb and Windows zip return 200 on artifacts.opensearch.org.
  • No regressions found by docutils: I parsed every changed file with docutils and compared it to main. Section structure, the number of system messages, and the counts of leftover raw `` and |Fess| are unchanged.
  • Cross-references: a minimal Sphinx build of each language's upgrade.rst resolves the new upgrade-reindex-new-fields label with no new warnings.
  • Behaviour: checked on a Fess 15.9 build on OpenSearch 3.9.0, using an index carried over from 15.8. Owner search and kana normalization did not work before Re-indexing with Reset Dictionaries and worked after it. An incremental crawl did not add owners to unchanged files; with Check Last Modified turned off, every file was fetched again.

…nd document the reindex an upgraded index needs

Fess 15.9 now runs on OpenSearch 3.9.0 (fess #3537), and fess-setup
install opensearch installs 3.9.0, but the 15.9 pages still told readers
to set up OpenSearch 3.8.0 and its 3.8.0 plugins.

- Replace the OpenSearch version Fess 15.9 uses with 3.9.0 in install,
  install-linux, install-windows, prerequisites, run, troubleshooting,
  uninstall and upgrade, in all seven languages: download URLs, paths,
  the fess-opensearch image tag and the supported-version statements.
  The "3.8.0 and later refuse dictionaries outside the configuration
  directory" sentences and the configsync 3.8.0 note in
  admin-index-backup describe older versions and are kept.
- Install the four Fess plugins by URL. From 3.8.1 on they are published
  to maven.codelibs.org only, and opensearch-plugin resolves the
  groupId:artifactId:version form against Maven Central only, so the
  old command form fails for 3.9.0. The commands now use the
  maven.codelibs.org URL, as the docker-fess image does, and a sentence
  under each command block says why.
- Step 4 of the upgrade guide notes that a snapshot taken on 3.9.0
  cannot be restored to 3.8.0 or earlier.
- Add the section "Applying New Fields and Kana Normalization to an
  Existing Document Index". At startup 15.9 adds fields to the
  configuration, log and user indices only, so a document index created
  by 15.8 keeps its old mapping: owner and last_modifier (#3528) get
  mapped dynamically as text, and the kana and long-vowel-dash
  normalization (#3532) is missing from its analysis settings and
  mapping.txt. The section explains that Re-indexing with Replace
  Aliases and Reset Dictionaries applies both without a crawl, warns
  that Reset Dictionaries overwrites edited dictionaries, and that
  files already indexed need one crawl with Check Last Modified off to
  get their owner. Step 7 and the "Do I need to recreate the index?"
  answer link to it.
@marevol marevol self-assigned this Oct 3, 2026
@marevol
marevol merged commit 5d77142 into main Oct 3, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant