Skip to content

/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.

  1. Make a directory and install the server and the command line:

    mkdir my-vola && cd my-vola
    npm install @vol-a/server @vol-a/cli
  2. 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.db is an absolute one:

    export VOLA_DATABASE_URL=file:data/vola.db # the database, one file
    export VOLA_STORAGE_PATH=data/storage # the bytes
    export VOLA_PORT=8310 # the default is 8300
  3. Create the database. The server would also migrate at start; vola migrate creates the file and its directory now:

    npx vola migrate
    ls data
    What it printed
    migrations applied
    vola.db
  4. 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:write
    What it printed
    created tenant acme (Acme Inc) id=01a1dfdb
    created key vola_live… "backend" for tenant acme
    id 01a1dfdb
    scopes files:read, files:write, folders:read, folders:write, shares:write
    Plaintext key (shown ONCE — store it now, it cannot be recovered):
    vola_live_...
  5. Start the server. Its log is JSON on stdout. Without VOLA_REDIS_URL, thumbnails render on the first /thumb request and OCR does not run. The two warnings about lookups.yaml and menu.yaml are expected: both files are optional.

    node node_modules/@vol-a/server/dist/server.js
    What 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"}
  6. 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 printed
    curl -s localhost:8310/vola/health/ready; echo
    echo "Hello from SQLite" > hello.txt
    export 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 data
    What it printed
    {"status":"ok","checks":{"database":"ok"}}
    {
    "filename": "hello.txt",
    "size": 18,
    "mime_type": "text/plain",
    "kind": "text"
    }
    Hello from SQLite
    storage
    vola.db
    vola.db-shm
    vola.db-wal

    vola.db-wal and vola.db-shm are part of the database while the server has it open. Stop the server with Ctrl-C: it closes the file cleanly, and only vola.db and storage remain.

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.js with 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.

  • 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_URL first: Environment variables.

v1.1.0released built 402bea0