Installation

You can install Sovrium on your own machine or run it on a cloud host. Pick the path that fits where your app will run.

Prerequisites

None. Sovrium ships as a self-contained binary: no runtime, no package manager, nothing to install first.

Tables and authentication work out of the box on an embedded SQLite database. PostgreSQL 15+ is optional and unlocks advanced features (raw SQL, vector search).

Local installation

Choose the method that matches your operating system.

# Install script (macOS, Linux)
curl -fsSL https://sovrium.com/install | sh

# Homebrew (macOS, Linux)
brew install sovrium/tap/sovrium

# Scoop (Windows)
scoop bucket add sovrium https://github.com/sovrium/scoop-bucket
scoop install sovrium

# Docker
docker pull ghcr.io/sovrium/sovrium:latest

After installing, the sovrium command is available from anywhere.

Cloud installation

Run Sovrium on a managed host without provisioning a server yourself. Any platform that runs a long-lived container will do: point it at the published ghcr.io/sovrium/sovrium image. Render, Railway, Heroku, Platform.sh, and Fly.io all run Sovrium this way. Scalingo can too, or you can deploy there from source with the Sovrium buildpack, which downloads the released, checksum-verified binary — see Deploy on Scalingo.

Whichever host you pick, set BASE_URL (required) and SOVRIUM_ENCRYPTION_KEY. Sovrium generates its own encryption key when none is given, but a managed host rebuilds the container filesystem on every deploy, so a self-generated key would not survive one unless it lands on a persistent volume — on a managed host, set it explicitly. There is only one secret to look after: the session-signing secret is derived from the encryption key, so you never set AUTH_SECRET alongside it. Generate one with sovrium secret generate, or with openssl rand -hex 32 if you do not have the binary to hand yet. DATABASE_URL is optional — Sovrium defaults to embedded SQLite — and so are the SMTP_* variables for sending email.

Vercel is not supported, because it is serverless: it offers no persistent server or container, and Sovrium needs a long-running process to serve your app and store its data.

Docker on your own server

To run Sovrium on a VPS or any host you control, start the container directly and place it behind a reverse proxy:

docker run -p 3000:3000 \
  -v "$PWD/app.yaml:/app/app.yaml:ro" \
  -v sovrium-data:/data \
  -e SOVRIUM_DATA_DIR=/data \
  -e NODE_ENV=production \
  -e SOVRIUM_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e BASE_URL="https://app.example.com" \
  ghcr.io/sovrium/sovrium:latest start /app/app.yaml

Two mounts, and both matter. The first gives the container your config; the second is where it keeps state. SOVRIUM_DATA_DIR has to point at that second mount — Sovrium writes to ./.sovrium by default, which inside the container is /app/.sovrium, so a data volume without this variable persists nothing. That includes the encryption key, which is why it is passed in above: with the volume wired up you could drop it and let Sovrium keep its own key on the volume instead.

Sovrium accepts either entry file, app.yaml or app.ts, so a guide that shows one works just as well with the other. See Deploy with Docker for the full production walkthrough.

Verify installation

Run the help command to check that Sovrium is installed correctly:

sovrium --help

Create a config file

Sovrium reads a YAML or JSON configuration file. Create an app.yaml with the simplest valid config:

name: my-app

Database setup

Sovrium uses an embedded SQLite database by default — tables and auth work with zero configuration. Set DATABASE_URL only to choose the SQLite file location or to switch to PostgreSQL:

# Default: embedded SQLite — no DATABASE_URL needed

# Optional — choose where the SQLite file lives:
export DATABASE_URL="file:./data/app.db"

# Optional — use PostgreSQL for advanced features:
export DATABASE_URL="postgresql://user:password@localhost:5432/myapp"

Next steps

• Quick Start — build and run your first app.
• Core Concepts — the anatomy of a Sovrium app.
• Configuration Files — YAML, JSON, TypeScript, and $ref.