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.

Terminal 
# .env

# Application
APP_SCHEMA='app.yaml'

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

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

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

PropertyDescription
APP_SCHEMAApp 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.

PropertyDescription
PORTServer port number (0–65535). 0 selects an available port. Default: 3000.
HOSTNAMEServer hostname. Default: localhost.
BASE_URLBase URL of the application (e.g., https://myapp.com). Used for authentication callback URLs and email links.
NODE_ENVRuntime environment. Set to "production" for secure cookies, CSRF checks, and strict SMTP validation. Default: development.

Database

PostgreSQL connection settings. Required when using tables or authentication.

PropertyDescription
DATABASE_URLPostgreSQL connection string (e.g., postgresql://user:password@localhost:5432/dbname). Required when the schema defines tables or auth.

Authentication

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

PropertyDescription
AUTH_SECRETSecret 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.

PropertyDescription
AUTH_ADMIN_EMAILEmail address for the default admin user.
AUTH_ADMIN_PASSWORDPassword for the default admin user. Must be at least 8 characters.
AUTH_ADMIN_NAMEDisplay 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.

PropertyDescription
{PROVIDER}_CLIENT_IDOAuth client ID from the provider's developer console.
{PROVIDER}_CLIENT_SECRETOAuth client secret from the provider's developer console. Keep this confidential.

Supported providers

Sovrium supports Google, GitHub, Microsoft, Slack, GitLab, and Facebook. For example, set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET for Google OAuth.

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.

PropertyDescription
SMTP_HOSTSMTP server hostname (e.g., smtp.gmail.com). Required in production.
SMTP_PORTSMTP server port. Default: 587.
SMTP_SECUREUse SSL/TLS connection. Default: false for port 587, true for port 465.
SMTP_USERSMTP authentication username.
SMTP_PASSSMTP authentication password or app-specific password.
SMTP_FROMDefault sender email address (e.g., noreply@yourdomain.com). Default: noreply@sovrium.com.
SMTP_FROM_NAMEDefault sender display name. Default: Sovrium.

Local development

When SMTP_HOST is not configured in development mode, Sovrium automatically falls back to Mailpit (localhost:1025). Install Mailpit to view sent emails in a local web UI.

Build

Options for the build command that generates a static site.

PropertyDescription
SOVRIUM_OUTPUT_DIROutput directory. Default: ./dist.
SOVRIUM_BASE_URLBase URL for sitemap generation and canonical links (e.g., https://example.com).
SOVRIUM_BASE_PATHPath prefix for subdirectory deployments (e.g., /my-app).
SOVRIUM_DEPLOYMENTDeployment target: github-pages or generic.
SOVRIUM_LANGUAGESComma-separated language codes to build (e.g., en,fr,de).
SOVRIUM_DEFAULT_LANGUAGEDefault language code (e.g., en).
SOVRIUM_GENERATE_SITEMAPGenerate sitemap.xml. Default: false.
SOVRIUM_GENERATE_ROBOTSGenerate robots.txt. Default: false.
SOVRIUM_HYDRATIONEnable client-side hydration. Default: false.
SOVRIUM_GENERATE_MANIFESTGenerate manifest.json for PWA. Default: false.
SOVRIUM_BUNDLE_OPTIMIZATIONOptimization strategy: split (code splitting) or none.
SOVRIUM_PUBLIC_DIRDirectory containing static assets to copy into the output.

Debug

Diagnostic and testing variables. Not needed in normal operation.

PropertyDescription
LOG_LEVELSet to "debug" for verbose logging (request logs, CSS compilation diagnostics). Default: follows NODE_ENV.
EFFECT_DEVTOOLSSet to "1" to enable Effect DevTools integration for runtime inspection.
RATE_LIMIT_WINDOW_SECONDSRate limit window in seconds. Used in tests for faster execution. Default: 60.
TypeScript APIOverview