/get-started/embedded/
Embed it with volaPlugin
If your application is already on Fastify, vola can live in the same process, with one database and one deploy. The database can be your PostgreSQL or a SQLite file next to the application.
pnpm add @vol-a/server @vol-a/core fastifyimport { connect, loadConfig, runMigrations, volaPlugin } from "@vol-a/server";import Fastify from "fastify";
// vola inside the Fastify application you already have, under /vola. Every VOLA_* variable is read// by loadConfig(); VOLA_DATABASE_URL picks the database: postgresql://… or a SQLite file:<path>.// The worker is a separate process, `node node_modules/@vol-a/server/dist/worker.js`.const app = Fastify({ logger: true });const config = loadConfig();const database = connect(config.databaseUrl);await runMigrations(database.db); // on SQLite this creates the file on the first start
app.get("/", async () => ({ service: "my-app" }));await app.register(volaPlugin, { prefix: "/vola", config, db: database.db });app.addHook("onClose", async () => database.close());
for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => void app.close());await app.listen({ host: "0.0.0.0", port: 3000 });loadConfig() reads every VOLA_* variable and validates it; Environment variables lists them.
Pick the database
Section titled “Pick the database”VOLA_DATABASE_URL decides: postgresql://… for PostgreSQL, file:<path> for one SQLite file. connect() picks the driver from the URL, and runMigrations() brings the database up to date, creating the SQLite file on the first start. The application code is the same for both. This run used SQLite:
export VOLA_DATABASE_URL=file:data/app.db # SQLite: one file, no database service# export VOLA_DATABASE_URL=postgresql://vola:secret@localhost:5432/vola # or PostgreSQLexport VOLA_STORAGE_PATH=data/storagenode server.tsIn a second terminal:
curl -s localhost:3000/; echocurl -s localhost:3000/vola/health/ready; echols data{"service":"my-app"}{"status":"ok","checks":{"database":"ok"}}app.dbapp.db-shmapp.db-walstorageOn SQLite your application is the one server process the file allows: do not also run server.js on it. vola CLI commands next to it are fine, and a worker on the same host is too. connect() opens one database per process. The onClose hook closes it, so after a clean stop only app.db and storage remain. The rest is in Run it on a SQLite file and the SQLite guide.
Things to run beside it
Section titled “Things to run beside it”The worker is a separate process. With VOLA_REDIS_URL set, thumbnails and OCR are rendered off the request path, so without a worker /thumb keeps answering 202. Without Redis, thumbnails render inline on /thumb and OCR does not run. Run node node_modules/@vol-a/server/dist/worker.js with the same environment. It needs VOLA_REDIS_URL, the same VOLA_DATABASE_URL and VOLA_STORAGE_PATH and, for encrypted files, the same key file. On SQLite it must run on the same host, opening the same file. PDF thumbnails and OCR need pdftoppm and tesseract on the machine.
Options you can pass. Besides prefix, config and db, the plugin takes redis, storage, events, audit, encryption, decorateRow and extend. The package README describes them.
v1.1.0released built 402bea0