Most deployments only set a few variables.
SM_DATABASE_URLselects the database. SQLite is the default.SM_REDIS_URLconnects 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_DEBUGandSM_VITE_DEV_URLdescribe 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.
| Variable | Default | Notes |
|---|---|---|
SM_DATABASE_URL |
sqlite+aiosqlite:///./app.db |
Async database URL. For PostgreSQL, use postgresql+asyncpg://user:pw@host:5432/db. Relative SQLite paths resolve against the project root. |
SM_REDIS_URL |
unset | Enables 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_ENVIRONMENT |
development |
development and testing bypass production secret checks. Any value other than development enables strict module discovery. |
SM_DEBUG |
false |
Enables debug mode, including tracebacks in HTTP responses. |
SM_VITE_DEV_URL |
http://localhost:5050 |
Vite 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_SECRET_KEY |
generated when unset | Session 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_ENABLED |
unset | JSON array of metadata names or explicit ep:<entry_point_name> selectors. Unset loads all installed modules. An empty array loads none. |
SM_PROJECT_ROOT |
discovered | Overrides 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.
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 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.
| Variable | Default | Notes |
|---|---|---|
SM_MULTI_TENANT |
false |
Enable 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_PROVIDER |
users |
Auth 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_LOCALE |
en |
Default locale. Must be in the supported locales. Restart required. |
SM_I18N_SUPPORTED_LOCALES |
["en"] |
JSON array of enabled locales. Restart required. |
SM_I18N_COOKIE_NAME |
locale |
Locale preference cookie name. Restart required. |
SM_MAINTENANCE_MODE |
false |
Serve 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_LEVEL |
INFO |
Application logging threshold. Restart required. |
SM_LOG_FORMAT |
json |
Structured json or readable text. Restart required. |
SM_TRUSTED_PROXY |
unset | Comma-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_SECURE |
unset | Secure flag for both the session cookie and the users auth cookie. Unset enables it outside development and testing. Restart required. |
SM_MAX_REQUEST_BODY_BYTES |
10485760 |
Global request body limit in bytes. 0 disables the guard. Applies live after a settings save. |
SM_RATE_LIMIT_PUBLIC |
120/minute |
Per-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_TITLE |
SimpleModule |
OpenAPI title. Restart required. |
SM_API_VERSION |
host version, or 0.0.0 |
OpenAPI version. Restart required. |
SM_API_DESCRIPTION |
"" |
OpenAPI description. Restart required. |
SM_OPENAPI_PUBLIC |
false |
Expose /api/openapi.json anonymously outside development. Restart required. |
These apply to the host's /api/ policy and take effect live after a settings save. See CORS for module policies and precedence.
| Variable | Default | Notes |
|---|---|---|
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_CREDENTIALS |
true |
Permit 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_AGE |
600 |
Preflight cache time in seconds. |
| Variable | Default | Notes |
|---|---|---|
SM_DB_POOL_SIZE |
10 |
SQLAlchemy pool size per process. |
SM_DB_MAX_OVERFLOW |
20 |
Extra connections per process beyond the pool size. |
SM_DB_POOL_PRE_PING |
true |
Test connections before use. |
SM_DB_POOL_RECYCLE |
1800 |
Connection recycling interval in seconds. |
SM_DB_POOL_TIMEOUT |
30 |
Seconds waiting for a pooled connection. |
SM_DB_CONNECT_TIMEOUT |
10 |
Driver connection timeout in seconds. |
SM_DB_STATEMENT_TIMEOUT_MS |
0 |
PostgreSQL statement timeout. Zero omits the startup parameter. |
SM_DB_IDLE_IN_TX_TIMEOUT_MS |
0 |
PostgreSQL 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.
Install simple_module_hosting[sentry]. These settings are read at startup
before the DB opens. See Sentry.
| Variable | Default | Notes |
|---|---|---|
SM_SENTRY_DSN |
unset | Enables error reporting in the web and Celery worker processes. |
SM_SENTRY_ENVIRONMENT |
SM_ENVIRONMENT |
Sentry environment tag. |
SM_SENTRY_TRACES_SAMPLE_RATE |
0.0 |
Performance trace sampling, from 0.0 to 1.0. |
Edit signup, OAuth/OIDC sign-in and other Users configuration in the admin settings editor. The variables below seed accounts or supply signing secrets.
signup_default_role (default user) selects an existing role for local
self-signup; oauth_signup_default_role (default blank) selects the role for
listed SSO provisioning providers. Both are DB-backed settings: blank or missing
roles grant nothing, missing roles log a warning, and neither creates a role.
Both refuse admin. See Users provisioning.
| Variable | Default | Notes |
|---|---|---|
SM_USERS_BOOTSTRAP_EMAIL |
unset | Creates the first admin if the users table is empty. |
SM_USERS_BOOTSTRAP_PASSWORD |
unset | Password paired with the admin email. |
SM_USERS_BOOTSTRAP_PASSWORD_GENERATED |
unset | Internal entrypoint marker. 1 logs generated credentials when the bootstrap admin is created. |
SM_USERS_BOOTSTRAP_USER_EMAIL |
unset | Optionally seeds a second account without admin privileges. |
SM_USERS_BOOTSTRAP_USER_PASSWORD |
unset | Password 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.
These variables seed defaults when each module's settings class is imported. Stored settings take precedence. See Keycloak and OIDC.
| Variable | Default | Notes |
|---|---|---|
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_CLAIM |
false |
Allow a verified token's tenant claim to supply tenant context. |
SM_OIDC_PROVIDER |
generic |
Provider 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_PATH |
provider preset | Claim path used to extract roles. |
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.
| Variable | Default | Notes |
|---|---|---|
SM_BG_TASKS_BROKER_URL |
redis://localhost:6379/0 |
Per-field override for non-Redis transports or separate connections; takes precedence over SM_REDIS_URL. Production rejects a localhost broker. |
SM_BG_TASKS_RESULT_BACKEND |
redis://localhost:6379/1 |
Per-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_QUEUE |
default |
Queue 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_SECONDS |
unset | Override the Redis visibility timeout. |
SM_BG_TASKS_WORKER_MAX_TASKS_PER_CHILD |
unset | Recycle a child after this many tasks. |
SM_BG_TASKS_WORKER_MAX_MEMORY_PER_CHILD_KB |
unset | Child memory threshold for recycling, in KiB. |
SM_BG_TASKS_TASK_REJECT_ON_WORKER_LOST |
unset | Requeue tasks when the executing worker child is lost. |
SM_BG_TASKS_TASK_SOFT_TIME_LIMIT |
unset | Soft task limit in seconds. |
SM_BG_TASKS_TASK_TIME_LIMIT |
unset | Hard task limit in seconds. Must exceed the soft limit when both are set. |
SM_BG_TASKS_WORKER_CONCURRENCY |
unset | Override worker concurrency. |
SM_BG_TASKS_TASK_ALWAYS_EAGER |
false |
Execute tasks synchronously in the calling process. |
SM_BG_TASKS_TASK_EAGER_PROPAGATES |
true |
Reraise task exceptions in eager mode. |
SM_BG_TASKS_BROADCAST_INVALIDATIONS |
true |
Broadcast cache invalidations across processes when the broker uses Redis. |
SM_BG_TASKS_INVALIDATION_CHANNEL |
simple_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_SIZE |
2 |
Pool size for each worker engine. |
SM_BG_TASKS_DB_MAX_OVERFLOW |
3 |
Overflow connections per worker engine. |
SM_BG_TASKS_DB_RECYCLE |
1800 |
Worker connection recycling interval in seconds. |
SM_BG_TASKS_DB_STATEMENT_TIMEOUT_MS |
unset | Override 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.
| Variable | Default | Notes |
|---|---|---|
SM_BG_TASKS_STUCK_AFTER_SECONDS |
300 |
Mark running tasks stuck after this long without a heartbeat. |
SM_BG_TASKS_STUCK_SWEEP_INTERVAL_SECONDS |
60 |
Interval between stuck-task sweeps. |
SM_BG_TASKS_PURGE_INTERVAL_SECONDS |
86400 |
Interval between retention sweeps. |
SM_BG_TASKS_RETENTION_DAYS |
14 |
Days to keep terminal task execution records. |
SM_BG_TASKS_LOG_SINK_ENABLED |
false |
Persist application and task log lines in the database. |
SM_BG_TASKS_LOG_SINK_LEVEL |
INFO |
Minimum level for retained logs. |
SM_BG_TASKS_LOG_RETENTION_DAYS |
7 |
Days to keep retained logs. |
SM_BG_TASKS_OUTBOX_MODE |
celery |
Durable delivery runner, either celery or inprocess. |
SM_BG_TASKS_OUTBOX_MAX_ATTEMPTS |
8 |
Delivery attempts before an outbox row is marked dead. |
SM_BG_TASKS_OUTBOX_SWEEP_INTERVAL_SECONDS |
5 |
Interval between outbox polls. |
SM_BG_TASKS_OUTBOX_LEASE_SECONDS |
300 |
How long a worker owns its claimed delivery before another can reclaim it. |
SM_BG_TASKS_OUTBOX_HANDLER_TIMEOUT_SECONDS |
unset | Handler deadline per attempt. Unset uses the lease duration minus a safety margin. |
Execution tracking mode and publish tracking are configured in the admin editor.
| Variable | Default | Notes |
|---|---|---|
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_QUEUES |
unset | Comma-separated queues for this worker. Also scopes the modules it loads. |
SM_BG_TASKS_INCLUDE_MODULES |
unset | Comma-separated Python package names to include even without a queue match. |
SM_BG_TASKS_EXCLUDE_MODULES |
unset | Comma-separated Python package names to exclude. Exclusion takes precedence over inclusion. |
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.
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. Use repeatable --only file_storage
or --prefix SM_FILE_STORAGE_ filters to limit the import; matches are additive.
--only uses case-insensitive settings package names and lists known packages
on an unknown name. In production, python -m settings import-from-env accepts
the same options without installing the developer CLI. The importer prints names
and the final count, never values; validation failures abort all writes and exit
non-zero. Only registered DB fields are eligible. Unregistered env-only secrets
and process wiring are skipped with an explanation; DB-readable background-task
and Keycloak fields remain eligible. See Settings CLI
for details and post-import precedence.
| Variable | Default | Notes |
|---|---|---|
SM_APP_PORT |
8000 |
Published host port for the repository Docker run targets. |
SM_TEST_DATABASE_URL |
in-memory SQLite; local PostgreSQL sm_test for make test-py-pg |
Database used by the pytest fixtures and the Postgres Make target. |
SM_MIGRATIONS_PG_URL |
local PostgreSQL sm_migrations_check |
Disposable database used by make migrations-roundtrip-pg. |
SM_TEST_REDIS_URL |
unset | External Redis URL for tests that need Redis. |
SM_TEST_REAL_PASSWORD_HASHING |
unset | Any nonempty value keeps real password hashing costs in tests. |
SM_TEST_SEPARATE_COMPILE_CACHES |
unset | Any nonempty value disables sharing of compiled SQL between in-memory SQLite test engines. |
SM_LOADTEST_COOKIE |
unset | Session cookie supplied to the Locust load test. |