Environment Variables

Sovrium reads configuration from environment variables at startup. Set them in a .env file or your server environment. All variables are optional unless noted otherwise.

# .env

# Application
APP_SCHEMA='app.yaml'

# Server
PORT=3000
BASE_URL=http://localhost:3000

# Database (optional — defaults to embedded SQLite)
DATABASE_URL=file:./data/app.db

# Authentication
AUTH_SECRET=your-secret-key-here

# Default Admin
AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=secure-admin-password

# OAuth (Google example)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

Application

Core application configuration. APP_SCHEMA is the primary way to provide a schema without a file argument.

Variable	Description
APP_SCHEMA	App schema as inline JSON, inline YAML, or a remote URL. Alternative to passing a file path on the command line.

Server

Server networking options for the start command.

Variable	Description
PORT	Server port number (0–65535). 0 selects an available port. Default: 3000.
HOSTNAME	Server hostname. Default: localhost.
BASE_URL	Base URL of the application (e.g., https://myapp.com). Used for authentication callback URLs and email links.
NODE_ENV	Runtime environment. Set to "production" for secure cookies, CSRF checks, and strict SMTP validation. Default: development.

Database

Database connection settings. Optional — Sovrium defaults to embedded SQLite when unset.

Variable	Description
DATABASE_URL	Database connection string. Optional: unset uses embedded SQLite; a file: URL (e.g., file:./data/app.db) picks the SQLite file; a postgresql:// URL (e.g., postgresql://user:password@localhost:5432/dbname) switches to PostgreSQL.

Authentication

Variables for Better Auth integration. Required when the schema defines an auth section.

Variable	Description
AUTH_SECRET	Secret key for signing tokens and encrypting sessions. Must be a strong random string (32+ characters recommended).

Default Admin User

Optional variables to create a default admin user on first startup. All three must be set for the admin user to be created.

Variable	Description
AUTH_ADMIN_EMAIL	Email address for the default admin user.
AUTH_ADMIN_PASSWORD	Password for the default admin user. Must be at least 8 characters.
AUTH_ADMIN_NAME	Display name for the default admin user. Optional, defaults to "Admin".

OAuth Providers

Credentials for each OAuth provider configured in the auth schema. Replace {PROVIDER} with the uppercase provider name.

Variable	Description
{PROVIDER}_CLIENT_ID	OAuth client ID from the provider's developer console.
{PROVIDER}_CLIENT_SECRET	OAuth client secret from the provider's developer console. Keep this confidential.

Email (SMTP)

SMTP configuration for sending authentication emails (verification, password reset, magic link). In development, falls back to Mailpit on localhost:1025 if SMTP_HOST is not set.

Variable	Description
SMTP_HOST	SMTP server hostname (e.g., smtp.gmail.com). Required in production.
SMTP_PORT	SMTP server port. Default: 587.
SMTP_SECURE	Use SSL/TLS connection. Default: false for port 587, true for port 465.
SMTP_USER	SMTP authentication username.
SMTP_PASS	SMTP authentication password or app-specific password.
SMTP_FROM	Default sender email address (e.g., noreply@yourdomain.com). Default: noreply@sovrium.com.
SMTP_FROM_NAME	Default sender display name. Default: Sovrium.

Build

Options for the build command that generates a static site.

Variable	Description
SOVRIUM_OUTPUT_DIR	Output directory. Default: ./dist.
SOVRIUM_BASE_URL	Base URL for sitemap generation and canonical links (e.g., https://example.com).
SOVRIUM_BASE_PATH	Path prefix for subdirectory deployments (e.g., /my-app).
SOVRIUM_DEPLOYMENT	Deployment target: github-pages or generic.
SOVRIUM_LANGUAGES	Comma-separated language codes to build (e.g., en,fr,de).
SOVRIUM_DEFAULT_LANGUAGE	Default language code (e.g., en).
SOVRIUM_GENERATE_SITEMAP	Generate sitemap.xml. Default: false.
SOVRIUM_GENERATE_ROBOTS	Generate robots.txt. Default: false.
SOVRIUM_HYDRATION	Enable client-side hydration. Default: false.
SOVRIUM_GENERATE_MANIFEST	Generate manifest.json for PWA. Default: false.
SOVRIUM_BUNDLE_OPTIMIZATION	Optimization strategy: split (code splitting) or none.
SOVRIUM_PUBLIC_DIR	Directory containing static assets to copy into the output.

Debug

Diagnostic and testing variables. Not needed in normal operation.

Variable	Description
LOG_LEVEL	Set to "debug" for verbose logging (request logs, CSS compilation diagnostics). Default: follows NODE_ENV.
EFFECT_DEVTOOLS	Set to "1" to enable Effect DevTools integration for runtime inspection.
RATE_LIMIT_WINDOW_SECONDS	Rate limit window in seconds. Used in tests for faster execution. Default: 60.