Skip to content

docs: add a page for readers choosing a file server search tool - #523

Merged
marevol merged 1 commit into
masterfrom
docs/file-server-search-page
Sep 7, 2026
Merged

docs: add a page for readers choosing a file server search tool#523
marevol merged 1 commit into
masterfrom
docs/file-server-search-page

Conversation

@marevol

@marevol marevol commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

Why

The documentation has nothing for a reader who is still deciding.

Someone who wants to know whether Fess can search their file server at all, what it will read out of the files, and whether it will expose documents they are not allowed to see has to assemble that from the crawler reference, the role reference and a tutorial — and the first two are written for someone who has already installed it.

The existing overview pages do not close that gap either:

  • use-cases is organised by industry
  • comparison is organised by product
  • the 23-part guide teaches how to build something once the choice is already made

Hence a new page rather than a rewrite of either. It follows the shape of supported-files: narrow subject, concrete lists, no narrative.

What the page covers

  • Which protocols the file crawler speaks, and which one to pick for Windows shares
  • How the file server's own access permissions carry into search results
  • The prerequisite that decides deployment scope: the document carries a group name, so the person searching has to carry it too. Permission-aware search needs Active Directory or LDAP; indexing only the folders everyone may read does not
  • Which file formats can be read, and where that stops (scans, image-only PDFs)
  • What actually drives sizing, beyond a file count
  • Where to go next — Quick Start for running it, guide-04 for building it

Verification

Everything technical is taken from the source rather than described from memory:

  • protocol table — crawler.file.protocols (file,smb,smb1,ftp,s3,gcs)
  • SMB range — DialectVersion in the jcifs client, SMB1 through SMB 3.1.1
  • permission inheritance — PermissionHelper#getSmbRoleTypeList takes the allowed and denied SID entries off the crawl metadata and resolves them to roles via SambaHelper#getAccountId
  • the (allow) / (deny) prefixes, and the smb.role.from.file, file.role.from.file, ftp.role.from.file and smb.available.sid.types defaults — fess_config.properties

Mechanical checks:

  • All 42 outbound links resolve (200). They point at /stable/ rather than a version tree, so the page does not rot at the next release
  • Each of the seven translations was parsed with doctitle_xform=False — the setting Sphinx uses, and the one that makes this check non-vacuous. Confirmed: the heading rules hold the section structure together (12 sections each), no inline markup broke against an adjacent CJK or Hangul character, and no system messages
  • No title outgrows the width a search result shows, site suffix included

Notes

  • Language parity is preserved: all seven trees get the page and the guide.rst entry
  • Pre-existing and left alone: use-cases.rst emits several "Title underline too short" warnings, and articles across the repo still carry 47 absolute links pinned to old version trees (some as old as 15.5), including one to config-role.html, which is now security-role.html

The documentation has nothing for somebody still deciding. A reader who wants
to know whether Fess can search their file server at all, what it will read out
of the files, and whether it will expose documents they are not allowed to see
has to assemble that from the crawler reference, the role reference and a
tutorial, and the first two are written for someone who has already installed
it.

The existing overview pages do not close that gap either. use-cases is
organised by industry, comparison by product, and the 23-part guide teaches how
to build something once the choice is made. Hence a new page rather than a
rewrite of either.

It follows the shape of supported-files -- narrow subject, concrete lists, no
narrative -- and covers the protocols the file crawler speaks, how the file
server's own access permissions carry into search results, which formats can be
read and where that stops, what drives sizing, and where to go next.

Everything technical is taken from the source rather than described from memory:

- the protocol table is crawler.file.protocols (file, smb, smb1, ftp, s3, gcs)
- the SMB range is DialectVersion in the jcifs client, SMB1 through SMB 3.1.1
- permission inheritance is PermissionHelper#getSmbRoleTypeList, which takes the
  allowed and denied SID entries off the crawl metadata and resolves them to
  roles via SambaHelper#getAccountId; the (allow) and (deny) prefixes and the
  smb.role.from.file, file.role.from.file, ftp.role.from.file and
  smb.available.sid.types defaults are read from fess_config.properties

The page states the prerequisite that decides how far a first deployment can
reach, and that a feature list tends to leave out: the document carries a group
name, so the person searching has to carry it too, which means permission-aware
search needs Active Directory or LDAP. Indexing only the folders everyone may
read does not.

Links point at /stable/ instead of a version tree so the page does not rot at
the next release; all 42 of them resolve. Each translation was parsed with
doctitle_xform=False, the setting Sphinx uses, to confirm the heading rules hold
the section structure together, that no inline markup broke against an adjacent
CJK or Hangul character, and that no title outgrows the width a search result
shows.
@marevol marevol self-assigned this Sep 7, 2026
@marevol
marevol merged commit 844bcb5 into master Sep 7, 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