In short
- A deployment is one namespace on S3, any number of writer processes and any number of reader processes; S3 is the only coordination channel. A single host may keep the namespace in a local directory instead.
- This page covers the topology, a minimal production setup, the two container images and how to schedule the writer.
- Read it when you move from the quickstart to a real bucket and a real embeddings model.
Monitoring, maintenance, restore and upgrades of a running deployment are in operations.
For an experimental serverless reader, see Run the reader on AWS Lambda.
Topology
Writers on different hosts take expiring leases per source and sync kind; one committer at a time holds the namespace lease, and readers only read.
- Writer hosts run the full build (or the
fyrrimage) with the provider packages and their credentials. - Reader hosts run the reader-only build (or the
fyrr-readerimage): one stdio process per user, or one HTTP service for many users. They need the embeddings endpoint for live query embeddings and a private mirror directory sized byreader.mirror_max_bytes.
A single host can use a local directory instead of S3
(uri = "file:///var/lib/fyrr", see local storage).
The writer and readers then coordinate through that directory, so they all
run on that host as the same user; it cannot be shared with other hosts,
also not over a network file system. Use S3 as soon as a second host needs
the namespace.
When a writer runs as PID 1 in the full image, it also reaps orphaned processes during worker cleanup. Run unrelated processes in separate containers.
Minimal production setup
Moving from the quickstart to a deployment changes four things: a real bucket, a real embeddings model, a reader without the writer, and a writer that runs on its own.
-
Bucket. Create an S3 bucket (or a prefix in one). Writers need read, write and delete access to the prefix; readers never write to S3, so give them read-only credentials. Without
access_key_id, credentials come from AWS environment variables, web identity, container credentials or instance metadata; AWS shared profile files are not loaded. -
Configuration. One file, shared by writers and readers:
[namespace] name = "acme" [storage] uri = "s3://acme-fyrr/prod" region = "eu-central-1" [embedding] endpoint = "https://embeddings.example.com/v1" # any OpenAI-compatible /embeddings API model = "BAAI/bge-m3" dimensions = 1024 api_key = { env = "FYRR_EMBEDDING_API_KEY" } reader_live = true # embed queries; off serves lexical only # Millionths of a US dollar. The cap applies per reader process, per # `writer sync` run (split evenly across its sources) and per source run # under `writer serve`. [embedding.spend] limit_microusd = 50000000 max_call_microusd = 2000 # your bound on one embeddings request [identity] hashing_key = { env = "FYRR_IDENTITY_KEY" } # the same value on every host encryption_key = { env = "FYRR_ENCRYPTION_KEY" } # 64 hexadecimal characters [reader] mirror_path = "/var/lib/fyrr/mirror" # default: $XDG_CACHE_HOME/fyrr/<namespace> [[sources]] id = "handbook" type = "local-files" permissions = "fixed" readers = ["grp:engineering"] [sources.scope] paths = ["/srv/handbook"]For one user over stdio, add
stdio_userandstdio_readersto[identity]; for many users over HTTP, add a directory,[identity.oidc]and[reader.http]as in HTTP login and users. The embedding model and dimensions bind the namespace; see upgrades. -
Writer. On a host with the full build or the
fyrrimage, runfyrr writer namespace createonce, thenfyrr writer serveas a service (scheduling). -
Reader. Run the
fyrr-readerimage (or the reader-only build) with the same file. Over HTTP it listens on plain HTTP: put a TLS-terminating proxy in front of it (start the reader). Check readiness withfyrr reader checkor/readyz, which answers health probes under anyHostwith the status code alone.
Downloadable binaries
Bare release binaries are dynamically linked Linux executables for x86-64
(linux-x86_64) and 64-bit ARM (linux-aarch64); Linux is the only
supported platform. Each platform's manifest-<platform>.txt has binary_runtime
sections that list the maximum required
GLIBC symbol version, ELF interpreter and shared libraries. Local assembly
inherits the build host's ABI; official releases use Ubuntu 24.04
release jobs. The manifest records the actual build provenance and runtime
requirements. A GLIBC version alone does not guarantee compatibility:
the interpreter and all required libraries must also be available.
The full binary additionally needs the matching CPython shared library
listed in needed (3.13 in the standard build) and the matching connector
SDK wheel with its provider extras. Install these in a
Python environment, expose its library directory through the system loader
or LD_LIBRARY_PATH, and set VIRTUAL_ENV when using that environment's
providers. Release binaries embed no RPATH or RUNPATH. The fyrr image
includes this runtime and the bundled providers.
The release job executes the exported binaries in the pinned runtime images before uploading artifacts; it also checks SDK provider discovery. Reader-only binaries require no Python.
Images
Tagged releases publish ghcr.io/fyrr-ai/fyrr:<version> and
ghcr.io/fyrr-ai/fyrr-reader:<version> as multi-arch images for
linux/amd64 and linux/arm64; <version>-amd64 and <version>-arm64
name one architecture. The release also carries each image as an archive
per platform.
docker/Dockerfile builds both images from the repository root; every base
image is pinned by digest. Both carry the LICENSE and NOTICE files under
/usr/share/doc/fyrr/. Release images package the binaries of the release
job; a build from a checkout compiles them in the pinned builder stage.
| Target | Base | User | Content |
|---|---|---|---|
fyrr-reader | distroless cc-debian13:nonroot | 65532 | the reader-only binary; no Python, no shell |
fyrr | python:3.13.17-slim-trixie | 10001 | the full binary, the connector SDK with the bundled providers' extras, and fyrr-entrypoint |
docker build --file docker/Dockerfile --target fyrr-reader --tag fyrr-reader:local .
docker build --file docker/Dockerfile --target fyrr --tag fyrr:local .
docker run --rm -v "$PWD/fyrr.toml:/etc/fyrr/fyrr.toml:ro" fyrr-reader:local --config /etc/fyrr/fyrr.toml config check --no-env--no-env skips the check that every referenced environment variable is
set; pass the variables with -e and drop it to check them too.
scripts/images builds and tests both images, including a real publication
on the local S3 fixture and docker/compose.yaml. The first build compiles
Lance in release mode and takes a while.
To package binaries you already built instead of compiling, name their
directory; it must hold fyrr and fyrr-reader, built for the runtime
images' glibc or older:
docker build --file docker/Dockerfile --target fyrr --tag fyrr:local \
--build-arg BINARIES=prebuilt --build-context release=path/to/binaries .Providers in the image
From a checkout, discover providers with
VIRTUAL_ENV=$PWD/connectors/.venv target/debug/fyrr writer providers.
To try a wheel locally, build it as below, install it with
uv pip install --no-deps --python connectors/.venv/bin/python --target /tmp/site target/example-wheels/*.whl,
then add PYTHONPATH=/tmp/site to the discovery command.
External providers are installed without rebuilding fyrr, either in a derived image or from a mounted wheel directory:
uv build --wheel --out-dir target/example-wheels examples/markdown-provider
docker build -f examples/derived-image/Dockerfile --build-arg FYRR_IMAGE=fyrr:local -t my-fyrr target/example-wheels
docker run --rm -e FYRR_PROVIDER_WHEELS=/wheels -v "$PWD/target/example-wheels:/wheels:ro" fyrr:local writer providerswriter providers exits 1 when an installed provider is refused (for example
one requiring another SDK series); a source on a refused provider fails
config check with status 78.
Scheduling
The simplest writer is one long-running process:
fyrr writer serve --jobs 4 --timeout 10mIt syncs each source's kinds when their configured intervals are due, pulls
the directory on its interval, and commits every
writer.commit.coalescing_timer (60 s). SIGINT or SIGTERM stops the
workers, finishes the current commit group and releases the lease. It does
not run maintenance: schedule fyrr writer maintain next to it.
Sync, directory pulls and commits can also run from cron, except for a SCIM
directory, whose freshness only writer serve with the administration
listener attests:
*/5 * * * * fyrr writer sync --due
*/5 * * * * fyrr writer sync --directory --due # with a snapshot or keycloak directory
*/2 * * * * fyrr writer commit
0 */6 * * * fyrr writer maintainSeveral sync processes may run at once, but not on the same source and
kind: the second one reports sync_busy for it and exits 1. commit,
maintain and sync --directory share the namespace lease, so whichever
starts second exits 75 at once (see the exit statuses). A killed
worker resumes from its durable cursor after its source/kind lease expires
(up to writer.commit.lease_ttl after the last renewal). A cursor advances only
after its envelope is durable; an interrupted current batch can be replayed.
Completed envelopes remain pending and can be committed independently. Replayed
text can reuse vectors already persisted in embedding.local_cache; in-flight
embedding requests may still have been billed and are not refunded. Provider
cursor semantics also apply: local-files scans the tree again and skips known
raw-byte revisions. --full deliberately resets the provider cursor, but keeps
durable envelopes and reusable vectors.
The per-source worker limit stays --timeout 10m for all syncs, including
--full. For an initial embedding-heavy corpus, allow enough time explicitly:
fyrr writer sync --full --timeout 1h
fyrr writer commitA timeout exits 1 with worker_failure: timeout after <N>ms; increase --timeout.
Only the configured duration is printed; provider exceptions remain private.
Restart with a larger timeout after the lease expires; do not delete pending
envelopes or the vector cache.