/get-started/sqlite/
Run it on a SQLite file
vola runs on PostgreSQL or on a single SQLite file. On SQLite the server needs Node 24 and a local disk, nothing else: no Docker, no database service, no Redis. The driver is Node’s built-in node:sqlite, and the vola command line opens the same file directly.
-
Make a directory and install the server and the command line:
mkdir my-vola && cd my-volanpm install @vol-a/server @vol-a/cli -
Point vola at a database file and a storage directory. A relative
file:path is relative to the working directory;file:///var/lib/vola/vola.dbis an absolute one:export VOLA_DATABASE_URL=file:data/vola.db # the database, one fileexport VOLA_STORAGE_PATH=data/storage # the bytesexport VOLA_PORT=8310 # the default is 8300 -
Create the database. The server would also migrate at start;
vola migratecreates the file and its directory now:npx vola migratels dataWhat it printed migrations appliedvola.db -
Make a tenant and an API key for it. No server has to be running, because each command opens the file. The key is printed once; only its SHA-256 is stored:
npx vola create-tenant --slug acme --name "Acme Inc"npx vola create-key --tenant acme --name backend --env live \--scopes files:read,files:write,folders:read,folders:write,shares:writeWhat it printed created tenant acme (Acme Inc) id=01a1dfdbcreated key vola_live… "backend" for tenant acmeid 01a1dfdbscopes files:read, files:write, folders:read, folders:write, shares:writePlaintext key (shown ONCE — store it now, it cannot be recovered):vola_live_... -
Start the server. Its log is JSON on stdout. Without
VOLA_REDIS_URL, thumbnails render on the first/thumbrequest and OCR does not run. The two warnings aboutlookups.yamlandmenu.yamlare expected: both files are optional.node node_modules/@vol-a/server/dist/server.jsWhat it printed {"level":40,…,"msg":"lookups.yaml not found: the vocabulary is empty"}{"level":30,…,"reason":"no VOLA_REDIS_URL","effect":"thumbnails are rendered inline on /thumb; OCR does not run","msg":"background jobs disabled"}{"level":30,…,"key_file":"/run/secrets/vola.key","keyring":null,"msg":"encryption: tenant and caller providers (no Redis: no keyring provider)"}{"level":30,…,"msg":"audit disabled: VOLA_MEMENTO_URL / VOLA_MEMENTO_API_KEY are not set"}{"level":40,…,"msg":"menu.yaml not found: no menu collection"}{"level":30,…,"prefix":"/vola","storage":"…/my-vola/data/storage","redis":false,"msg":"vola configured"}{"level":30,…,"msg":"Server listening at http://127.0.0.1:8310"} -
In a second terminal, in the same directory, check it is ready, upload a file to an instance of your application (here a ticket) and read it back:
export KEY=vola_live_... # what create-key printedcurl -s localhost:8310/vola/health/ready; echoecho "Hello from SQLite" > hello.txtexport TICKET=$(uuidgen | tr A-F a-f)curl -s -H "Authorization: Bearer $KEY" -F file=@hello.txt \localhost:8310/vola/files/tickets/$TICKET | tee file.json | jq '{filename, size, mime_type, kind}'curl -s -H "Authorization: Bearer $KEY" localhost:8310/vola/files/tickets/$TICKET/$(jq -r .id file.json)ls dataWhat it printed {"status":"ok","checks":{"database":"ok"}}{"filename": "hello.txt","size": 18,"mime_type": "text/plain","kind": "text"}Hello from SQLitestoragevola.dbvola.db-shmvola.db-walvola.db-walandvola.db-shmare part of the database while the server has it open. Stop the server withCtrl-C: it closes the file cleanly, and onlyvola.dbandstorageremain.
What SQLite gives up
Section titled “What SQLite gives up”Every route, answer and error code is the same as on PostgreSQL, and so are the four encryption modes, real-time lists, the CLI and the OCR search. What changes is how far it scales:
- One server process on the file, on one host. Your own application counts as that process when it embeds the plugin. For more than one server, use PostgreSQL.
- At most one worker, on the same host. Add Redis and run
node node_modules/@vol-a/server/dist/worker.jswith the same variables to take thumbnails off the request path and to get OCR. - The file on a local disk. Never on NFS or SMB; the storage directory can be, the database cannot.
Files and storage has the features by database, and the SQLite guide has the rest: the worker, backups with VACUUM INTO, restores, upgrades and what not to do with the file.
What to do next
Section titled “What to do next”- Every route, with its answers and error codes: HTTP API.
- Call it from code with @vol-a/client, pointing it at
http://localhost:8310/vola. - Every variable the server reads,
VOLA_DATABASE_URLfirst: Environment variables.
v1.1.0released built 402bea0