Fess: A Self-Hosted Search Server That Crawls First and Indexes Second

The problem Fess targets: crawling heterogeneous sources without writing a connector

Most search projects assume you already have documents in a store you control. Fess inverts that. The README describes a built-in crawler that collects documents from web sites, file systems and data stores such as databases and CSV files, with support for Microsoft Office, PDF and ZIP archives. The audience is an IT team that has been asked to make an intranet searchable, where the content is spread across a CMS, a shared drive and a handful of SaaS tools, and where nobody wants to write and maintain a per-source ingestion pipeline.

That framing matters because it sets the boundary. Fess is not a library you embed in an application, and it is not a hosted search API. It is a server you install, point at sources through a browser-based administration UI, and let crawl on a schedule. The README points to separate configuration guides for web, file and data store targets, and says you register crawling targets on those pages and then start the crawler from the Scheduler page. So the unit of work is a crawl configuration, not a code change.

The secondary audience is site owners. Fess Site Search is described as a free alternative to Google Site Search that you embed in your own website, with an FSS JS Generator documented separately. That is a different use case from intranet search, but it runs on the same server.

How the pieces fit: OpenSearch underneath, a crawler and admin UI on top

The architecture visible in the material is a Java application that uses OpenSearch as its search engine backend. The README is explicit that prior OpenSearch knowledge is not required because Fess is configured through the administration UI, but it also states the dependency plainly: Docker images bundle OpenSearch, and for other installations you set it up separately. That sentence is the most operationally important one in the whole document. You are running two systems, and only one of them is Fess.

Around that core, the project exposes four extension surfaces. Data store connectors are separate repositories named fess-ds-*, covering Confluence and Jira, Box, CSV, generic databases, Dropbox, Elasticsearch, Git, Gitbucket, G Suite, JSON, Office 365, S3, Salesforce, SharePoint and Slack. Ingest plugins handle Logger and NDJSON. Script plugins add Groovy and OGNL, which is how you would express custom logic without forking the server. Theme plugins, collected in fess-themes, are described as self-contained single-page apps installed by uploading a ZIP in the admin UI.

The search side is not just keyword matching. The feature list includes faceting, sorting and search suggestions, plus role- and permission-based filtering of results. Authentication integrations cover LDAP, OpenID Connect, SAML, SPNEGO and Microsoft Entra ID, and the UI and text analysis cover 20 or more languages. The topics list also mentions semantic search and RAG, and the repository carries an mcp topic, but the README body does not document a retrieval pipeline or an MCP server in any detail. Treat those as directions the project is moving in rather than features you can evaluate from the README alone.

Getting it running: ZIP, Docker, or a Maven build from source

There are three documented paths, and they cost very different amounts of effort. The quickest is the ZIP download from the Releases page, which the README demonstrates with three commands: unzip fess-<version>.zip, cd fess-<version>, then ./bin/fess. DEB and RPM packages exist for the same releases. The Docker route is lighter still if you want the bundled OpenSearch: images are published on ghcr.io, and a Compose file lives in the codelibs/docker-fess repository under compose.

Once running, the search UI is at http://localhost:8080/ and the admin UI at http://localhost:8080/admin/. The README states the default username and password are admin/admin. That default is worth flagging without drama: it is normal for a self-hosted product, and it is also the first thing to change if the admin port is reachable beyond localhost.

Building from source is the heavier path and is documented for contributors. You need Java 21 or later and Maven. Clone the repository, then run mvn antrun:run to download OpenSearch plugins into the plugins directory. To run or debug, you start org.codelibs.fess.FessBoot in your IDE and open localhost:8080. Packaging uses mvn package, which writes the release file into target/releases, with mvn rpm:rpm and mvn jdeb:jdeb for the two native package formats. If you touch the persistence layer, the code generation steps are mvn dbflute:download once, then mvn dbflute:freegen and mvn license:format.

Integration tests need a live server. The README says to build with mvn antrun:run and mvn package, unzip the release, start bin/fess in the background, and wait up to 60 seconds. Readiness is checked with curl -s "http://localhost:8080/api/v1/health", which returns a JSON response when ready. Test data for SearchApiTests comes from cloning https://github.com/codelibs/fess-testdata.git to /tmp/fess-testdata. The suite runs with mvn test -P integrationTests plus -Dtest.fess.url and -Dtest.search_engine.url properties, and a single case can be selected with -Dtest=SearchApiTests. The fact that the test harness needs a cloned fixture repository and a running OpenSearch on a separate URL tells you something about the shape of the project: it is integration-heavy, not a pure unit-tested library.

The Java 21 requirement and the separate OpenSearch install are the real adoption costs

The stated requirement is Java 21 or later for the ZIP, RPM and DEB packages, and OpenSearch as the backend. Neither is exotic, but together they narrow the field. If your organisation standardises on Java 17 for internal services, this is not a drop-in. If you already run Elasticsearch rather than OpenSearch, the README does not describe using it, and the project's own topics list it as an elasticsearch-alternative, which is a positioning statement rather than a compatibility guarantee.

The second cost is that the connector catalogue is a set of separate repositories, not a single artifact. Each fess-ds-* project has its own release cadence. That means an upgrade of Fess and an upgrade of, say, the SharePoint connector are two events you have to sequence, and the README does not describe a compatibility matrix between them. The Installation Guide is cited for supported versions, so that is where the answer lives, but the README itself leaves you to go find it.

The third cost is less visible. A crawler-based search server has a stateful lifecycle: crawl schedules, indexing runs and index state. The README mentions the Scheduler page and a health endpoint, and nothing else about monitoring, reindexing or index migration. For a small deployment that is fine. For a large one, the operational documentation you need is not in the README, and you should confirm it exists elsewhere before committing.

Where Fess is the wrong choice

If your content is already a stream of events, Fess is the wrong shape. The ingest plugin list is short, just Logger and NDJSON, and the primary ingestion model is crawling. A team that emits documents from an application would be better served by writing to OpenSearch directly and putting a query layer in front of it, because Fess's value is concentrated in the crawl configuration, permission filtering and admin UI, none of which you would use.

If your content lives in a source with no fess-ds-* connector, you are writing a plugin. The README lists the connector repositories and describes the plugin categories, but it does not document a plugin authoring guide in the material available here. Budget for reading the source of an existing connector rather than a specification.

If you need a managed service, this is self-hosted by definition. The Docker images reduce setup effort, not operational responsibility. Someone still owns the OpenSearch cluster, the crawl failures and the upgrade path.

And if your search corpus is small and static, a static site generator's built-in index or a client-side search library will do the job with none of the moving parts. Fess earns its complexity when there are multiple heterogeneous sources, access control requirements and a schedule.

How Fess differs from Elasticsearch plus a custom ingestion layer

The obvious alternative is to run OpenSearch or Elasticsearch yourself and write the crawlers and permission filters in application code. The difference is where the work lives. With a raw engine you own the document model, the analyser configuration, the access control filter and the scheduling. You get exactly the behaviour you specify and no more. With Fess you get a crawler, an admin UI, a REST API, role-based result filtering and a connector catalogue, and you accept the project's opinions about how documents are shaped and how crawls are scheduled.

That trade is favourable when your needs match the connector list. It turns unfavourable when they do not, because you end up writing a Fess plugin to reach a source you could have indexed directly. The other axis is the UI. Fess's administration surface is browser-based and the README treats that as the primary interface, with the REST API as a second option. If your team expects to manage search configuration as code in a repository, the UI-first model is friction, and the README does not describe an export or configuration-as-code path.

Fess Site Search is the narrower comparison. Against a hosted site search product, the difference is that you host the index and the crawler yourself, so the cost model shifts from a subscription to infrastructure plus maintenance.

Licence, releases and what an upgrade actually involves

Fess is Apache-2.0, and the README shows a licence header badge and a mvn license:format step in the source generation workflow, which suggests licence headers are kept consistent across files. Apache-2.0 permits commercial use and modification, and it includes a patent grant. It does not give you the OpenSearch licence, which is a separate project with its own terms, and it does not cover the fess-ds-* connectors, which are separate repositories you should check individually. None of this is legal advice; if the licence terms matter to your organisation, read LICENSE in the repository and the terms of each connector you install.

The release cadence visible in the material is roughly every six to eight weeks: 15.6.1 on 2026-05-02, 15.7.0 on 2026-06-25, and 15.8.0 on 2026-08-20. That is frequent enough that a pinned-version policy is worth having, and frequent enough that you should expect to be a few releases behind rather than current. The README does not describe an upgrade procedure for an existing installation, and it does not describe index migration between versions. That is the gap to close first: before you put data in, find out from the Installation Guide and the release notes how an in-place upgrade handles the existing index, because a crawler-based system with a large corpus makes a full re-crawl an expensive way to upgrade.

The MIGRATION.md file referenced in the README covers moving from another search provider, which is a different problem from upgrading Fess itself. Do not treat one as documentation for the other.

Editorial conclusion

Adopt Fess if you need to index a mix of web pages, file systems and SaaS data stores and you want that configuration done through a browser UI rather than in code, and if you can run Java 21 plus a separate OpenSearch backend. Do not adopt it if you need a managed service, if your content lives in a source with no connector in the fess-ds-* family, or if you cannot absorb a full-text engine's operational surface. Verify first that a supported OpenSearch version is available for your platform, that the connectors you need are published under codelibs, and that the default admin/admin credentials are changed before the admin UI is reachable from anywhere but localhost.

Official sources

1. codelibs/fess on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases