docs: add a page for readers choosing a file server search tool - #523
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-casesis organised by industrycomparisonis organised by productHence 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
Verification
Everything technical is taken from the source rather than described from memory:
crawler.file.protocols(file,smb,smb1,ftp,s3,gcs)DialectVersionin the jcifs client, SMB1 through SMB 3.1.1PermissionHelper#getSmbRoleTypeListtakes the allowed and denied SID entries off the crawl metadata and resolves them to roles viaSambaHelper#getAccountId(allow)/(deny)prefixes, and thesmb.role.from.file,file.role.from.file,ftp.role.from.fileandsmb.available.sid.typesdefaults —fess_config.propertiesMechanical checks:
/stable/rather than a version tree, so the page does not rot at the next releasedoctitle_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 messagesNotes
guide.rstentryuse-cases.rstemits 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 toconfig-role.html, which is nowsecurity-role.html