Skip to main content
A Quivr deployment runs one quivr binary as three commands, next to four services and the plugins you choose. Every process reads the same JSON configuration file; you run quivr migrate first, then keep quivr api and quivr worker running.
Quivr is at the evaluation stage: its API is v0 and may change. Do not run it in production yet.

​
What a deployment runs

make dev runs all of these on one machine, with the service versions pinned in deploy/compose/compose.yaml. The Quickstart walks through it.

​
The configuration file

QUIVR_CONFIG holds the path of a JSON file. Give api, worker and migrate the same file, except for addresses such as probe_listen. It must set:
  • database_url, temporal_address, weaviate_url and s3: where the four services are;
  • cursor_key: a stable secret of at least 32 bytes that signs change-feed cursors;
  • keys: the API keys and what each may do. You create keys here; give plugins:admin only to operator keys;
  • plugins: at least one ingestion plugin and one retrieval plugin, normally the first-party core.ingest and core.retrieve. The api refuses to start without both, and the worker without an ingestion plugin. core.ingest also needs a Text Embeddings Inference server for its model; see First-party plugins.
The file holds the database URL, storage credentials and API keys, so keep it readable only by Quivr’s processes. The Configuration reference lists every field, and Pin a plugin shows how to add one. A change to this file takes effect when the processes restart. Plugin changes made through the API, such as activating a new version, apply while Quivr runs; see Upgrade or switch a plugin.

​
Start order

For example, not run:
  1. quivr migrate updates the database schema, creates the storage bucket when it is missing, and prepares the search index. It gives up after 30 seconds when storage or the search index does not answer; run it again once they do.
  2. quivr api refuses to start while migrations are pending, with database/schema unavailable; run migrate.
  3. quivr worker started before the migrations waits for them for up to migration_wait (5 minutes by default), then exits.
To deploy a new quivr binary, run its quivr migrate first, then restart api and worker on it. A binary older than the database schema refuses to start, with database schema is newer than this binary. The CLI reference lists the commands’ exit codes.

​
Check that it is ready

Each api and worker serves three probes on its probe_listen address, 127.0.0.1:8081 by default. Give each process its own address, and keep it private. The probes open only once startup is done: a worker still waiting for migrations answers none of them, so give a liveness check at least migration_wait before it restarts the process. The api becomes ready once its schema check passes and its ingestion plugin has answered a first query, or after 5 seconds; the first searches are then only slower. The worker also checks that Temporal, object storage and the search index answer. A plugin that is down does not stop either process. Background work that needs it waits and retries; a search that needs it fails with 503 search_unavailable.

​
Example deployments

  • Local: make dev, in the Quickstart.
  • Hosted, single node: the repository’s Railway example runs the demo app and Quivr as single-replica services, without high availability.

​
Next