Every variable the server, the worker and the CLI read (packages/server/src/config.ts;
.env.example has the same list with comments). Empty values count as unset. An invalid value
stops the process at start with one line naming every bad variable.
the database. Set it.postgresql://user:password@host:5432/db (or postgres://…): PostgreSQL, every feature. file:<path> (relative to the working directory) or file:///abs/path.db: SQLite, one server process (and one worker on the same host) — see SQLite. :memory:: SQLite in memory, for tests. The server migrates it at start; the CLI uses the same
VOLA_DATABASE_URL_TEST
postgresql://vola:vola@localhost:5432/vola_test
the test suites only (the same forms)
VOLA_REDIS_URL
(unset)
Redis: the job queue, file events across processes, unlock tokens, the share-password counter. Unset: one process, synchronous jobs, in-process events, no keyrings
VOLA_HOST / VOLA_PORT
0.0.0.0 / 8300
the listener
VOLA_PREFIX
/vola
the path every route is mounted under
VOLA_PUBLIC_URL
(unset)
the origin clients reach the server on (https://files.example.com), used to build a share link’s url; unset: the request’s Host and protocol. Set it behind a proxy
VOLA_TRUST_PROXY
false
take the client address from X-Forwarded-For (the demo routes’ rate limit, the logs). Only behind a proxy that sets it
VOLA_LOG_LEVEL
info
pino: fatalerrorwarninfodebugtracesilent; JSON on stdout; secret headers redacted at every level
auto: jobs go to the worker when Redis is set; 1: insist (without Redis one ERROR line, then synchronous); 0: always synchronous — thumbnails render inline on /thumb, OCR does not run. Use 0 when Redis is there but no worker process runs, or /thumb answers 202 forever
VOLA_WORKER_CONCURRENCY
2
jobs one worker process runs at once
VOLA_QUEUE_PREFIX
vola
the Redis key prefix of the queue; server and worker must agree; several deployments may share one Redis with different prefixes
VOLA_OCR_ENABLED
auto
auto: an OCR job per eligible upload, run when tesseract is installed (otherwise SKIPPED with one WARN); 1: the worker refuses to start without tesseract; 0: no OCR job is ever created
VOLA_OCR_LANGS
eng+srp+deu
tesseract’s -l, codes of the OcrLanguages vocabulary; an unknown or uninstalled code stops the worker at start
VOLA_OCR_MAX_PAGES
20
pages of a PDF the OCR reads, from the first
VOLA_OCR_TIMEOUT_S
120
seconds one page (or image) may take
VOLA_STATS_TTL_MIN
60
minutes a statistics snapshot may age before the worker’s refresh-stats job recomputes it (the job runs every half TTL); without a worker a read past the TTL recomputes
the key file of the tenant provider — one base64 32-byte key per line, the first active. vola keys-generate. The worker reads it too. Back it up (below)
the pepper file of the keyring provider — the Argon2 secret of every PIN and recovery key, same format. vola pepper-generate. The worker does not need it. Back it up with the key file
VOLA_UNLOCK_TTL_S
150
seconds an unlock token lives without a request (5 … 86400); every request that carries it starts the count again
VOLA_ENC_INLINE_DERIVE_MAX_BYTES
26214400 (25 MiB)
the largest encrypted file a thumbnail or OCR pass is made of (the plaintext is decrypted into memory); larger files get no derivative; 0 turns derivatives of encrypted files off
the memento API base (https://memento.example.com/memento). Both or neither with the key
VOLA_MEMENTO_API_KEY
(unset)
a memento key with the write scope. With both set, destructive and security-relevant operations become memento events (AUDIT.md); the worker pushes them (give it the same two variables), or the server does, fire-and-forget, without Redis