Skip to content

/reference/environment/

Environment variables

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.

variable default
VOLA_DATABASE_URL postgresql://vola:vola@localhost:5432/vola 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: fatal error warn info debug trace silent; JSON on stdout; secret headers redacted at every level
variable default
VOLA_STORAGE_PATH var/storage (image: /data/storage) the content-addressable store: blobs/, tmp/, uploads/. Back it up with the database
VOLA_MAX_UPLOAD_BYTES 536870912 (512 MiB) the largest file one upload may carry (multipart and tus); over it 413 file_too_large
VOLA_UPLOAD_TTL_HOURS 24 hours an unfinished resumable upload is kept before its part file and row are swept
variable default
VOLA_WORKER_ENABLED auto 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
variable default
VOLA_KEY_FILE /run/secrets/vola.key (compose: /run/secrets/vola/vola.key) 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)
VOLA_PEPPER_FILE /run/secrets/vola.pepper (compose: /run/secrets/vola/vola.pepper) 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
variable default
VOLA_WS_HEARTBEAT_MS 30000 a WebSocket ping this often (≥ 1000); a client that missed the last one is cut off
VOLA_WS_MAX_BUFFERED 1000 unwritten messages a slow client may pile up before it is closed with 4008
variable default
VOLA_LOOKUPS_PATH lookups.yaml at the repository root (image: /app/config/lookups.yaml) the controlled vocabulary served by GET /lookups; missing → an empty vocabulary with a warning
VOLA_TRANSLATIONS_PATH i18n/translations.csv next to the lookups the label sheet
VOLA_RECORD_CANDIDATES true record values the vocabulary does not know, for review (vola lookups candidates)
VOLA_CANDIDATES_DIR var/candidates next to the lookups (image: /data/candidates) where they are recorded
VOLA_MENU_PATH menu.yaml at the repository root (image: /app/config/menu.yaml) the examples site’s sidebar, served as the menu UDC collection; missing → no menu collection
variable default
VOLA_MEMENTO_URL (unset) 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
variable default
VOLA_UI_DIR (unset) (image: /app/ui) a built single-page app served at / and /en/ with an index.html fallback; unset: the API only
VOLA_EXAMPLES false the demo routes under /examples (EXAMPLES-SITE.md); true needs both keys below
VOLA_DEMO_API_KEY / VOLA_DEMO_WRITE_KEY (unset) the visitor’s read-only key and the server’s write key (vola demo-keys prints a pair); stored by the server at its start
VOLA_DEMO_TENANT demo the demo tenant, created when missing
VOLA_DEMO_INSTANCE_TYPE / VOLA_DEMO_INSTANCE_ID demo / 00000000-0000-4000-8000-000000000001 the one instance the site shows
VOLA_DEMO_MAX_UPLOAD_BYTES 5242880 (5 MiB) the write proxy’s upload cap
VOLA_DEMO_TTL_HOURS 24 a visitor’s uploads, keyrings and folders are purged after this
VOLA_DEMO_RATE_LIMIT 60 writes one address may make per ten minutes
VOLA_DEMO_PURGE_INTERVAL_MIN 15 how often the purge runs; 0 never
VOLA_URL, VOLA_DEMO_ASSETS http://localhost:8300/vola, apps/examples/assets (image: /app/demo-assets) vola demo-seed: the server and the pack

docker-compose.yaml additionally reads POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT, POSTGRES_BIND, REDIS_PORT, REDIS_BIND, VOLA_HOST_PORT, VOLA_IMAGE, VOLA_SECRETS_DIR and COMPOSE_PROFILES.

v1.1.1released built 519e3dc