Install & operate

Self-hosting

One process, zero runtime dependencies.

What you need#

Bun 1.3 or newer. Nothing else — the database is one embedded SQLite file and there is no second service to install.

bun install -g @vitrus-dev/cli

vitrus init                                   # creates ./vitrus.db and a secret salt
vitrus site add "My site" example.com         # prints your script tag
VITRUS_PASSWORD="a long secret" vitrus start  # ingest + dashboard on http://localhost:3000

The password guards the dashboard and the read API; the tracker and ingest stay public because your visitors' browsers call them. Without it, anyone who can reach the port can read your analytics, and vitrus start warns you.

Settings#

SettingDefaultWhat it does
--port3000Listen port: vitrus start --port 8080.
VITRUS_PASSWORD—Password for the dashboard and the read API. Set it.
VITRUS_DB./vitrus.dbDatabase file. Back up this one file.
OLLAMA_URLhttp://127.0.0.1:11434Local model for digest phrasing: vitrus digest SITE_ID --llm ollama:<model>.
VITRUS_LLM_KEY / VITRUS_LLM_URL—Bring your own key for an OpenAI-compatible endpoint: --llm openai:<model>.

No model is used unless you pass --llm to vitrus digest; the digest is written deterministically.

What the self-hosted server does not do yet#

The open-source core holds the whole engine, but the self-hosted server exposes less of it than the cloud. Today vitrus start does not:

  • mount the MCP module, or deliver the scheduled digest (run vitrus digest yourself);
  • accept server-side forwarded requests — the path that sees signed agents and crawlers that never run JavaScript;
  • take row filters, or render the sessions, users, journeys, goals and globe views;
  • have accounts, teams, roles, invitations, sign-in with Google or GitHub, or billing — those are the cloud.

The building blocks are in the core, and wiring them into vitrus start is on the roadmap. If you need them today, compare self-hosting with the cloud.

Reverse proxy and country data#

The country breakdown is read only from your proxy's header. We do not bundle a GeoIP database — a 60+ MB file with a monthly update cycle would break the one-command install on its own. Supported headers: Cloudflare (CF-IPCountry), Vercel, Fly, CloudFront, Netlify. With none of them the country table stays empty and the dashboard says why.

City, region and coordinates (the Globe's Timeline, Coordinates and Subdivisions modes) need one more step on Cloudflare: Rules → Settings → Managed Transforms → Add visitor location headers. That adds cf-ipcity, cf-region-code, cf-iplatitude and cf-iplongitude. Vercel and CloudFront send their equivalents without extra setup. Coordinates are rounded to 0.1° (about 11 km) before they are stored — city precision, which is all IP geolocation honestly has — and the IP itself is never stored. Without these headers the Globe works at country level and says what is missing.

Backups#

WAL mode means three files; do not copy them while the process is running:

sqlite3 /var/lib/vitrus/vitrus.db ".backup '/backup/vitrus.db'"
Something wrong or missing on this page? Open an issue or ask in Discussions.