# Installation

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

## Prerequisites

Tables and authentication work out of the box on an embedded SQLite database — no setup required. PostgreSQL 15+ is optional and unlocks advanced features (raw SQL, vector search). Running from source requires [Bun 1.3+](https://bun.sh).

## Local installation

Sovrium ships as a self-contained binary, so there is no separate runtime to install. Choose the method that matches your operating system.

```bash
# 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.

### One-click deploy

Each button below provisions a long-running server from the Sovrium image and walks you through the setup.

[![Deploy on Scalingo](https://cdn.scalingo.com/deploy/button.svg)](https://dashboard.scalingo.com/create/app?source=https://github.com/sovrium/sovrium)
[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/sovrium/sovrium)
[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https://github.com/sovrium/sovrium)
[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/sovrium/sovrium)

Each host prompts you for a few environment variables: `AUTH_SECRET` (required), `BASE_URL` (required), `DATABASE_URL` (optional — defaults to embedded SQLite), and `SMTP_*` (optional, for sending email). Render, Railway, and Heroku run the pre-built `ghcr.io/sovrium/sovrium` image; Scalingo deploys with the [Sovrium buildpack](https://github.com/sovrium/scalingo-buildpack), which downloads the released, checksum-verified binary.

Platform.sh, Fly.io, and Coolify also run Sovrium from the same image.

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:

```bash
docker run -p 3000:3000 \
  -e AUTH_SECRET="your-secret" \
  -e BASE_URL="https://app.example.com" \
  -v ./data:/app/data \
  ghcr.io/sovrium/sovrium:latest start app.yaml
```

The `-v` flag mounts a data volume so your SQLite database and uploads survive restarts.

## Verify installation

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

```bash
sovrium --help
```

## Create a config file

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

```yaml
name: my-app
```

:::callout
**YAML or JSON.** Sovrium supports both `.yaml`/`.yml` and `.json` files. YAML is recommended for readability.
:::

:::callout
**Authoring config in TypeScript?** Install the zero-dependency `@sovrium/types` package for IDE autocompletion (`bun add -d @sovrium/types`) and author with `defineConfig`. See [Configuration Files](/en/docs/configuration-files).
:::

## 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:

```bash
# 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"
```

:::callout
**SQLite by default.** Leave `DATABASE_URL` unset and Sovrium stores data in a local SQLite file. Use a `file:` URL to pick its location, or a `postgresql://` URL to switch engines. Pure static sites (pages and theme only) need no database at all.
:::

## Next steps

- [Quick Start](/en/docs/quick-start) — build and run your first app.
- [Core Concepts](/en/docs/concepts) — the anatomy of a Sovrium app.
- [Configuration Files](/en/docs/configuration-files) — YAML, JSON, TypeScript, and `$ref`.