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