Skip to content

Environment variables ​

Most deployments only set a few variables.

  • SM_DATABASE_URL selects the database. SQLite is the default.
  • SM_REDIS_URL connects shared rate limiting and background tasks to Redis when used.
  • SM_USERS_BOOTSTRAP_* seeds the first local accounts. See Users module for the specific variables.
  • SM_ENVIRONMENT, SM_DEBUG and SM_VITE_DEV_URL describe how the process runs.

Edit deployment settings such as mail credentials, feature flags and storage backends in the admin UI. The tables below cover the framework, bundled modules and repository tools. See Configuration for an overview.

The root signing key is generated and stored when SM_SECRET_KEY is unset. Users reset and verification keys are derived from it; no secret env variable is required.

Framework ​

VariableDefaultNotes
SM_DATABASE_URLsqlite+aiosqlite:///./app.dbAsync database URL. For PostgreSQL, use postgresql+asyncpg://user:pw@host:5432/db. Relative SQLite paths resolve against the project root.
SM_REDIS_URLunsetEnables shared Redis rate limits and leases and seeds both the Celery broker and result backend. Without it the host uses in-process rate limits and database-backed leases.
SM_ENVIRONMENTdevelopmentdevelopment and testing bypass production secret checks. Any value other than development enables strict module discovery.
SM_DEBUGfalseEnables debug mode, including tracebacks in HTTP responses.
SM_VITE_DEV_URLhttp://localhost:5050Vite HMR origin for development. Host and scaffolded Vite configs derive their port and origin from this URL. smpy dev supplies its selected URL to both children.
SM_VITE_PORTunsetDeprecated Vite-only fallback when SM_VITE_DEV_URL is absent: SM_VITE_PORT=5201 npm run dev still works. Prefer uv run smpy dev --port 8201 --vite-port 5201 to keep API and Vite URLs aligned; direct API launches need their matching SM_VITE_DEV_URL.
SM_SECRET_KEYgenerated when unsetSession signing key. If unset, the framework reuses the stored key or generates and saves one. A fresh DB without the settings table uses a temporary key until persistence is possible. An explicit key wins and stays out of the DB. Production rejects the literal placeholder change-me-in-production.
SM_MODULES_ENABLEDunsetJSON array of metadata names or explicit ep:<entry_point_name> selectors. Unset loads all installed modules. An empty array loads none.
SM_PROJECT_ROOTdiscoveredOverrides project-root discovery for .env and relative SQLite paths. Otherwise discovery walks up from the working directory and stops at repository or home-directory boundaries.

The repository's Docker entrypoint generates and exports a process-local signing key when absent. This bypasses the framework's DB-backed key, so set a stable key when using that entrypoint and sharing sessions across restarts or replicas.

Module-enabled allow-list ​

bash
export SM_MODULES_ENABLED='["Users","Dashboard"]'

Use ModuleMeta.name or an explicit ep:<entry_point_name> selector, case-insensitively. Unqualified items always match metadata names. Include any required dependencies and restart after changing the allow-list. To skip disabled plugins before import, every item must use ep: (for example ["ep:auth","ep:users","ep:background_tasks"]). Mixed lists are supported, but discovery loads all candidates to resolve any unqualified metadata name. An ep: selector with no installed entry point fails strict discovery and warns in development; unknown metadata names only warn. See Discovery. A comma-separated string fails settings validation.

Host settings (HostSettings) ​

Host settings resolve env → DB → default. The fields appear under Host in the admin settings editor. A boot setting takes effect after restart. Runtime settings can change live unless pinned by the environment. See Settings.

VariableDefaultNotes
SM_MULTI_TENANTfalseEnable tenant isolation. Restart required.
SM_DEFAULT_TENANT""Fixed tenant in single-tenant mode. Blank uses the default tenant ID for new rows. Restart required.
SM_TENANT_HEADER""Tenant lookup header in multi-tenant mode. Blank disables header lookup. Restart required.
SM_AUTH_PROVIDERusersAuth provider to activate when both Users and Keycloak are installed. Restart required.
SM_AUTH_PUBLIC_PATHS[]JSON array of anonymous-access path prefixes. Modules can declare method-aware public routes with register_public_routes. Restart required.
SM_I18N_DEFAULT_LOCALEenDefault locale. Must be in the supported locales. Restart required.
SM_I18N_SUPPORTED_LOCALES["en"]JSON array of enabled locales. Restart required.
SM_I18N_COOKIE_NAMElocaleLocale preference cookie name. Restart required.
SM_MAINTENANCE_MODEfalseServe a 503 to everyone except admins. Runtime.
SM_MAINTENANCE_MESSAGE""Optional maintenance notice. Runtime.
SM_PUBLIC_BASE_URL""Shared public origin for canonical and og:url links, account emails and invitation links. users.base_url and tenants.public_base_url inherit it when blank. Never derived from the request Host. Runtime.
SM_LOGIN_REDIRECT_URL/dashboard/Where every auth provider sends a user after sign-in; falls back to another view when the Dashboard module is absent. Runtime.
SM_NATIVE_LINK_PREFIXES[]JSON array of path prefixes whose links use full browser navigation. Runtime.
SM_LOG_LEVELINFOApplication logging threshold. Restart required.
SM_LOG_FORMATjsonStructured json or readable text. Restart required.
SM_TRUSTED_PROXYunsetComma-separated trusted proxy IPs or CIDRs. * trusts any peer. A trusted TLS terminator can supply the client IP and original request scheme for logs and auth callbacks. Restart required.
SM_FORWARDED_HOST_ALLOWLIST[]JSON array of allowed forwarded hosts, such as ["app.example.com","*.example.org"]. Entries may include ports. Requires SM_TRUSTED_PROXY. Restart required.
SM_SESSION_COOKIE_SECUREunsetSecure flag for both the session cookie and the users auth cookie. Unset enables it outside development and testing. Restart required.
SM_MAX_REQUEST_BODY_BYTES10485760Global request body limit in bytes. 0 disables the guard. Applies live after a settings save.
SM_RATE_LIMIT_PUBLIC120/minutePer-IP budget for anonymous requests to public routes. Blank or off disables it. Applies live after a settings save.
SM_RATE_LIMIT_AUTHENTICATED""Per-IP budget for signed-in traffic, using the same syntax. Blank disables it. Applies live after a settings save.
SM_API_TITLESimpleModuleOpenAPI title. Restart required.
SM_API_VERSIONhost version, or 0.0.0OpenAPI version. Restart required.
SM_API_DESCRIPTION""OpenAPI description. Restart required.
SM_OPENAPI_PUBLICfalseExpose /api/openapi.json anonymously outside development. Restart required.

CORS ​

These apply to the host's /api/ policy and take effect live after a settings save. See CORS for module policies and precedence.

VariableDefaultNotes
SM_CORS_ALLOW_ORIGINS[]JSON array of allowed origins. Empty leaves the host API policy disabled. A wildcard requires credentials to be disabled.
SM_CORS_ALLOW_CREDENTIALStruePermit credentialed requests.
SM_CORS_ALLOW_METHODS["GET","POST","PUT","PATCH","DELETE"]JSON array of allowed methods.
SM_CORS_ALLOW_HEADERS["Authorization","Content-Type","X-CSRF-Token"]JSON array of allowed request headers.
SM_CORS_EXPOSE_HEADERS[]JSON array of response headers available to browser scripts.
SM_CORS_MAX_AGE600Preflight cache time in seconds.

DB connection pool ​

VariableDefaultNotes
SM_DB_POOL_SIZE10SQLAlchemy pool size per process.
SM_DB_MAX_OVERFLOW20Extra connections per process beyond the pool size.
SM_DB_POOL_PRE_PINGtrueTest connections before use.
SM_DB_POOL_RECYCLE1800Connection recycling interval in seconds.
SM_DB_POOL_TIMEOUT30Seconds waiting for a pooled connection.
SM_DB_CONNECT_TIMEOUT10Driver connection timeout in seconds.
SM_DB_STATEMENT_TIMEOUT_MS0PostgreSQL statement timeout. Zero omits the startup parameter.
SM_DB_IDLE_IN_TX_TIMEOUT_MS0PostgreSQL idle-in-transaction timeout. Zero omits the startup parameter.

Total possible web connections are workers × (SM_DB_POOL_SIZE + SM_DB_MAX_OVERFLOW). See database tuning for worker pools and PgBouncer.

Sentry (optional) ​

Install simple_module_hosting[sentry]. These settings are read at startup before the DB opens. See Sentry.

VariableDefaultNotes
SM_SENTRY_DSNunsetEnables error reporting in the web and Celery worker processes.
SM_SENTRY_ENVIRONMENTSM_ENVIRONMENTSentry environment tag.
SM_SENTRY_TRACES_SAMPLE_RATE0.0Performance trace sampling, from 0.0 to 1.0.

Users module ​

Edit signup, OAuth/OIDC sign-in and other Users configuration in the admin settings editor. The variables below seed accounts or supply signing secrets.

VariableDefaultNotes
SM_USERS_BOOTSTRAP_EMAILunsetCreates the first admin if the users table is empty.
SM_USERS_BOOTSTRAP_PASSWORDunsetPassword paired with the admin email.
SM_USERS_BOOTSTRAP_PASSWORD_GENERATEDunsetInternal entrypoint marker. 1 logs generated credentials when the bootstrap admin is created.
SM_USERS_BOOTSTRAP_USER_EMAILunsetOptionally seeds a second account without admin privileges.
SM_USERS_BOOTSTRAP_USER_PASSWORDunsetPassword paired with the second account's email.

The Users setting oauth_microsoft_discovery_url is honored only when SM_ENVIRONMENT is explicitly development or testing.

Keycloak and OIDC modules ​

These variables seed defaults when each module's settings class is imported. Stored settings take precedence. See Keycloak and OIDC.

VariableDefaultNotes
SM_KEYCLOAK_SERVER_URL""Keycloak server base URL.
SM_KEYCLOAK_REALM""Realm name.
SM_KEYCLOAK_CLIENT_ID""OAuth client ID.
SM_KEYCLOAK_CLIENT_SECRET""OAuth client secret.
SM_KEYCLOAK_TRUST_TENANT_CLAIMfalseAllow a verified token's tenant claim to supply tenant context.
SM_OIDC_PROVIDERgenericProvider preset used for discovery and claims defaults.
SM_OIDC_DISCOVERY_URL""OpenID Connect discovery document URL. An explicit URL wins over the preset-derived URL.
SM_OIDC_TENANT_ID""Identity provider tenant ID used by presets such as Entra to derive discovery.
SM_OIDC_CLIENT_ID""OIDC client ID.
SM_OIDC_CLIENT_SECRET""OIDC client secret.
SM_OIDC_ROLES_CLAIM_PATHprovider presetClaim path used to extract roles.

Background tasks (Celery) ​

The settings fields below resolve env → DB → default. Prefer SM_REDIS_URL for Redis connectivity (generated app, worker and beat files use only this connection variable) and the BackgroundTasks admin editor for tuning. Restart affected web, worker and beat processes for changes to their startup configuration. See Background tasks.

Connection, routing and worker settings ​

VariableDefaultNotes
SM_BG_TASKS_BROKER_URLredis://localhost:6379/0Per-field override for non-Redis transports or separate connections; takes precedence over SM_REDIS_URL. Production rejects a localhost broker.
SM_BG_TASKS_RESULT_BACKENDredis://localhost:6379/1Per-field override for non-Redis backends or separate connections; takes precedence over SM_REDIS_URL. Production rejects a localhost result backend.
SM_BG_TASKS_TASK_DEFAULT_QUEUEdefaultQueue for tasks without an explicit route.
SM_BG_TASKS_TASK_ROUTES_OVERRIDE{}JSON object mapping task patterns to queues or supported route options.
SM_BG_TASKS_VISIBILITY_TIMEOUT_SECONDSunsetOverride the Redis visibility timeout.
SM_BG_TASKS_WORKER_MAX_TASKS_PER_CHILDunsetRecycle a child after this many tasks.
SM_BG_TASKS_WORKER_MAX_MEMORY_PER_CHILD_KBunsetChild memory threshold for recycling, in KiB.
SM_BG_TASKS_TASK_REJECT_ON_WORKER_LOSTunsetRequeue tasks when the executing worker child is lost.
SM_BG_TASKS_TASK_SOFT_TIME_LIMITunsetSoft task limit in seconds.
SM_BG_TASKS_TASK_TIME_LIMITunsetHard task limit in seconds. Must exceed the soft limit when both are set.
SM_BG_TASKS_WORKER_CONCURRENCYunsetOverride worker concurrency.
SM_BG_TASKS_TASK_ALWAYS_EAGERfalseExecute tasks synchronously in the calling process.
SM_BG_TASKS_TASK_EAGER_PROPAGATEStrueReraise task exceptions in eager mode.
SM_BG_TASKS_BROADCAST_INVALIDATIONStrueBroadcast cache invalidations across processes when the broker uses Redis.
SM_BG_TASKS_INVALIDATION_CHANNELsimple_module.invalidation.<installation_id>Optional explicit channel; env wins over a DB override. Otherwise derived from the stable system-scoped host.installation_id row. The default also publishes/listens on the legacy global channel until 0.1.0 for rolling upgrades; see invalidation.
SM_BG_TASKS_DB_POOL_SIZE2Pool size for each worker engine.
SM_BG_TASKS_DB_MAX_OVERFLOW3Overflow connections per worker engine.
SM_BG_TASKS_DB_RECYCLE1800Worker connection recycling interval in seconds.
SM_BG_TASKS_DB_STATEMENT_TIMEOUT_MSunsetOverride the host PostgreSQL statement timeout for workers. Zero omits it.

The per-field broker and result backend variables remain supported for other transports. They log a deprecation warning when set to Redis URLs.

Tracking, retained logs and durable events ​

VariableDefaultNotes
SM_BG_TASKS_STUCK_AFTER_SECONDS300Mark running tasks stuck after this long without a heartbeat.
SM_BG_TASKS_STUCK_SWEEP_INTERVAL_SECONDS60Interval between stuck-task sweeps.
SM_BG_TASKS_PURGE_INTERVAL_SECONDS86400Interval between retention sweeps.
SM_BG_TASKS_RETENTION_DAYS14Days to keep terminal task execution records.
SM_BG_TASKS_LOG_SINK_ENABLEDfalsePersist application and task log lines in the database.
SM_BG_TASKS_LOG_SINK_LEVELINFOMinimum level for retained logs.
SM_BG_TASKS_LOG_RETENTION_DAYS7Days to keep retained logs.
SM_BG_TASKS_OUTBOX_MODEceleryDurable delivery runner, either celery or inprocess.
SM_BG_TASKS_OUTBOX_MAX_ATTEMPTS8Delivery attempts before an outbox row is marked dead.
SM_BG_TASKS_OUTBOX_SWEEP_INTERVAL_SECONDS5Interval between outbox polls.
SM_BG_TASKS_OUTBOX_LEASE_SECONDS300How long a worker owns its claimed delivery before another can reclaim it.
SM_BG_TASKS_OUTBOX_HANDLER_TIMEOUT_SECONDSunsetHandler deadline per attempt. Unset uses the lease duration minus a safety margin.

Execution tracking mode and publish tracking are configured in the admin editor.

Per-process environment settings ​

VariableDefaultNotes
SM_BG_TASKS_CELERY_OVERRIDES{}JSON object of supported raw Celery configuration overrides. Serializer, import and code-loading keys are rejected.
SM_BG_TASKS_WORKER_QUEUESunsetComma-separated queues for this worker. Also scopes the modules it loads.
SM_BG_TASKS_INCLUDE_MODULESunsetComma-separated Python package names to include even without a queue match.
SM_BG_TASKS_EXCLUDE_MODULESunsetComma-separated Python package names to exclude. Exclusion takes precedence over inclusion.

File storage module ​

File storage settings are DB-backed. Edit them under Files in the admin settings editor. The defaults use the filesystem backend and ./uploads. See File storage for S3 and custom backends.

Patterns ​

Formats and precedence ​

Use JSON for Pydantic list and object settings. The trusted proxy and per-worker queue and module filters explicitly use comma-separated strings. Pydantic booleans are case-insensitive and accept true, 1, yes or on for true and false, 0, no or off for false. Unrecognized values fail validation.

For env-readable host settings, process variables take precedence over the project .env, then stored overrides, then defaults. Module settings that use DbBackedSettings resolve from stored values and defaults. The smpy settings import-from-env migration command can import legacy SM_<MODULE>_<FIELD> values into the DB.

Repository tools and tests ​

VariableDefaultNotes
SM_APP_PORT8000Published host port for the repository Docker run targets.
SM_TEST_DATABASE_URLin-memory SQLite; local PostgreSQL sm_test for make test-py-pgDatabase used by the pytest fixtures and the Postgres Make target.
SM_MIGRATIONS_PG_URLlocal PostgreSQL sm_migrations_checkDisposable database used by make migrations-roundtrip-pg.
SM_TEST_REDIS_URLunsetExternal Redis URL for tests that need Redis.
SM_TEST_REAL_PASSWORD_HASHINGunsetAny nonempty value keeps real password hashing costs in tests.
SM_TEST_SEPARATE_COMPILE_CACHESunsetAny nonempty value disables sharing of compiled SQL between in-memory SQLite test engines.
SM_LOADTEST_COOKIEunsetSession cookie supplied to the Locust load test.

Released under the MIT License.