Configuration

The server takes every setting as a command-line flag or a QUIVER_* environment variable. There is no config file, but it reads a .env file at startup.

Precedence: flags, then environment variables, then .env, then the defaults. The .env file is looked for in the working directory and its parents; when one is loaded, the server logs loaded environment file. Copy .env.example to start.

quiver --help
QUIVER_HTTP_PORT=8080 quiver --data-dir /var/lib/quiver

Network

Flag	Environment	Default	Meaning
`--host`	`QUIVER_HOST`	`127.0.0.1`	the address both APIs bind to
`--http-port` (alias `--port`)	`QUIVER_HTTP_PORT`	`6900`	REST port
`--grpc-port`	`QUIVER_GRPC_PORT`	`6901`	gRPC port
`--disable-http`	`QUIVER_DISABLE_HTTP`	off	don't start the REST API
`--disable-grpc`	`QUIVER_DISABLE_GRPC`	off	don't start the gRPC API
`--max-body-mb`	`QUIVER_MAX_BODY_MB`	`64`	the largest REST JSON body, in MiB
`--cors`	`QUIVER_CORS`	off	allow cross-origin REST requests from any origin

Storage

Flag	Environment	Default	Meaning
`--data-dir`	`QUIVER_DATA_DIR`	`./quiver-data`	collections, snapshots and the lock file
`--storage`	`QUIVER_STORAGE`	`file`	engine for new collections: `file`, `rocksdb` or `memory`
`--in-memory`	`QUIVER_IN_MEMORY`	off	keep everything in memory and touch no disk at all
`--fsync`	`QUIVER_FSYNC`	off	fsync after every write: slower, but safe against power loss

--storage picks the engine for collections created from now on; each collection remembers its own, so a data directory can mix engines. --storage memory still uses the data directory for its lock file and snapshots, while --in-memory uses no directory at all. See storage & durability.

Authentication

Flag	Environment	Default	Meaning
`--keys-file`	`QUIVER_KEYS_FILE`	none	a JSON file of named keys with roles and optional collection scopes
`--api-key`	`QUIVER_API_KEY`	none	one read-write key
`--readonly-api-key`	`QUIVER_READONLY_API_KEY`	none	one read-only key

The three combine. With none of them, authentication is off. See security & API keys.

TLS

Flag	Environment	Default	Meaning
`--tls-cert`	`QUIVER_TLS_CERT`	none	PEM certificate chain; serve both APIs over TLS (needs `--tls-key`)
`--tls-key`	`QUIVER_TLS_KEY`	none	PEM private key for `--tls-cert`
`--tls-client-ca`	`QUIVER_TLS_CLIENT_CA`	none	PEM CA certificates; clients must present a certificate they signed (mutual TLS)

See security.

Snapshots

Flag	Environment	Default	Meaning
`--snapshot-dir`	`QUIVER_SNAPSHOT_DIR`	`DATA_DIR/snapshots`	where archives are kept
`--snapshot-interval`	`QUIVER_SNAPSHOT_INTERVAL`	`0` (never)	snapshot every changed collection this often, in seconds
`--snapshot-keep`	`QUIVER_SNAPSHOT_KEEP`	`5`	snapshots kept per collection; `0` keeps all
`--expiry-interval`	`QUIVER_EXPIRY_INTERVAL`	`60`	delete expired points this often, in seconds; `0` never does (reads hide them either way)

See snapshots & backups.

Logging

The log goes to standard output. RUST_LOG sets its filter, info by default: RUST_LOG=debug, or per module, such as RUST_LOG=info,quiver_db=debug. Requests are traced by tower_http at the debug level, and responses with a 5xx status are logged as errors.

Booleans

On the command line, --in-memory, --fsync, --cors, --disable-http and --disable-grpc are plain switches. Their environment variables accept 1, true, yes or on (in any case) and 0, false, no or off; anything else stops the server:

error: invalid value 'maybe' for '--fsync': value was not a boolean

Checks at startup

The server refuses to start, with a message, when:

--disable-http and --disable-grpc are both set;
--storage rocksdb is asked of a build without the rocksdb feature;
--snapshot-interval is set with --in-memory but without --snapshot-dir;
the keys file cannot be read, or two keys are the same, or one is empty;
--tls-cert or --tls-key is given without the other, or the TLS files cannot be read or parsed;
the data directory is already open in another process;
a collection's files are corrupt (see storage).

It warns, and carries on, when it listens on an address other than loopback without any API key, or with API keys but without TLS, and when it runs --in-memory.

Health checks

quiver --healthcheck, given the same settings as the running server (flags, QUIVER_* variables or .env), asks that server's GET /health and exits 0 if it answers 200, or prints why not and exits 1. It connects over loopback when the server binds an unspecified address such as 0.0.0.0, and checks the gRPC port instead when the REST API is disabled. With --tls-cert it speaks TLS (without verifying the certificate); with --tls-client-ca as well, it only checks that the port accepts connections. The Docker image uses it.

quiver --healthcheck && echo healthy

Shutting down

On SIGINT (Ctrl+C) or SIGTERM the server stops accepting connections, gives requests in flight 10 seconds to finish, stops the snapshot scheduler, and checkpoints every collection before it exits.

The terminal UI

quiver-tui has its own flags and variables, QUIVER_URL, QUIVER_API_KEY, QUIVER_CA_CERT, QUIVER_CLIENT_CERT and QUIVER_EMBEDDING_*, listed on the terminal UI page. It does not read .env.