feat: DB-backed module settings with admin UI

.env.example

@@ -1,58 +1,14 @@
-# Database
+# Only SM_DATABASE_URL is required. Everything else has sensible defaults.
+# All module-level settings (SMTP, Celery, users, etc.) are now managed in
+# the admin UI at /settings/modules — no env vars needed.
+
+# Database (required)
 SM_DATABASE_URL=sqlite+aiosqlite:///./app.db
 # SM_DATABASE_URL=postgresql+asyncpg://sm:sm@localhost:5432/simple_module
 
-# App
+# Process identity (production must override SM_SECRET_KEY)
 SM_ENVIRONMENT=development
 SM_SECRET_KEY=change-me-in-production
-SM_VITE_DEV_URL=http://localhost:5050
-
-# Users module — local email+password auth (replaces Keycloak)
-#
-# Signup mode: false = admin-invite only (default), true = public signup
-SM_USERS_ALLOW_SIGNUP=false
-
-# Token secrets — MUST change in production. Dev placeholders are visible in
-# log lines so they're obvious to rotate.
-SM_USERS_RESET_PASSWORD_TOKEN_SECRET=dev-reset-token-secret-change-me
-SM_USERS_VERIFICATION_TOKEN_SECRET=dev-verify-token-secret-change-me
-
-# Mailer: console (logs tokenized links at INFO) or smtp
-SM_USERS_MAILER=console
-SM_USERS_BASE_URL=http://localhost:8000
-# SM_USERS_SMTP_HOST=
-# SM_USERS_SMTP_PORT=587
-# SM_USERS_SMTP_USERNAME=
-# SM_USERS_SMTP_PASSWORD=
-# SM_USERS_SMTP_FROM=no-reply@localhost
-# SM_USERS_SMTP_TLS=true
 
-# First-admin bootstrap (auto-create an admin on first boot iff users table
-# is empty AND both are set). Leave blank to disable — use `sm-users
-# create-admin` instead.
-# SM_USERS_BOOTSTRAP_EMAIL=admin@example.com
-# SM_USERS_BOOTSTRAP_PASSWORD=changeme
-
-# Optional second seeded user with the "user" role. Seeded alongside the
-# admin on first boot (same empty-table guard). When both env vars are set
-# AND SM_ENVIRONMENT=development, the login page renders quick-login buttons
-# for both accounts to speed up manual testing. Leave blank in production.
-# SM_USERS_BOOTSTRAP_USER_EMAIL=user@example.com
-# SM_USERS_BOOTSTRAP_USER_PASSWORD=changeme
-
-# Cookie: set cookie_secure=false in dev (HTTPS-only otherwise)
-SM_USERS_COOKIE_SECURE=false
-
-# Multi-tenancy (default off).
-# SM_MULTI_TENANT=false
-# SM_TENANT_HEADER=
-
-# BackgroundTasks module — Celery + Redis task queue.
-# In docker-compose these point at the `redis` service host (redis://redis:6379/*).
-SM_BG_TASKS_BROKER_URL=redis://localhost:6379/0
-SM_BG_TASKS_RESULT_BACKEND=redis://localhost:6379/1
-# How long a task can stay in `running` without a heartbeat before it's
-# flipped to `stuck` by the beat sweep.
-SM_BG_TASKS_STUCK_AFTER_SECONDS=300
-# Purge terminal rows older than this (days) — keeps history bounded.
-SM_BG_TASKS_RETENTION_DAYS=14
+# Dev-only: Vite asset URL (ignored in production builds)
+SM_VITE_DEV_URL=http://localhost:5050

.gitignore

@@ -56,3 +56,4 @@ Thumbs.db
 .playwright-cli/*
 .playwright-mcp/*
 host/client_app/.playwright-cli/*
+.superpowers/

README.md

@@ -89,21 +89,26 @@ docs/
 
 ## Configuration
 
-All settings are `SM_`-prefixed env vars. Defaults in `.env.example` cover local dev. Key knobs:
+Local deployments only need one env var — everything else has sensible defaults and is managed in the admin UI at `/settings/modules`.
 
-| Variable | Default | Notes |
+| Variable | Default | Required |
 |---|---|---|
-| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | Async URL. Postgres: `postgresql+asyncpg://...` |
-| `SM_ENVIRONMENT` | `development` | Anything else triggers strict module discovery |
-| `SM_SECRET_KEY` | _(placeholder)_ | **Must** change in production — signs session cookies |
-| `SM_USERS_ALLOW_SIGNUP` | `false` | Enable public signup (else admin-invite only) |
-| `SM_USERS_MAILER` | `console` | `console` logs links; `smtp` uses SMTP config (see `.env.example`) |
-| `SM_USERS_RESET_PASSWORD_TOKEN_SECRET` | _(dev placeholder)_ | **Must** change in production |
-| `SM_USERS_VERIFICATION_TOKEN_SECRET` | _(dev placeholder)_ | **Must** change in production |
-| `SM_USERS_BOOTSTRAP_EMAIL` | `` | First-admin email; combined with `SM_USERS_BOOTSTRAP_PASSWORD`, creates admin on first boot iff users table is empty |
-| `SM_USERS_BOOTSTRAP_PASSWORD` | `` | Paired with above |
-| `SM_MULTI_TENANT` | `false` | Set `true` to enable `TenantMiddleware` |
-| `SM_TENANT_HEADER` | `` | Empty = token-only; set e.g. `X-Tenant-ID` to enable header fallback |
+| `SM_DATABASE_URL` | `sqlite+aiosqlite:///./app.db` | Yes — async URL. Postgres: `postgresql+asyncpg://...` |
+| `SM_ENVIRONMENT` | `development` | No — any value other than `development`, `test`, `testing` triggers strict discovery and placeholder-secret checks |
+| `SM_SECRET_KEY` | `change-me-in-production` | No in dev; **must** be overridden in production |
+| `SM_VITE_DEV_URL` | `http://localhost:5050` | Dev only |
+
+Power users can still override the following bootstrap knobs via env if needed: `SM_DB_POOL_SIZE`, `SM_DB_MAX_OVERFLOW`, `SM_DB_POOL_PRE_PING`, `SM_DB_POOL_RECYCLE`, `SM_DEBUG`, `SM_LOG_LEVEL`, `SM_LOG_FORMAT`, `SM_MODULES_ENABLED`. These are needed before the DB connection is open.
+
+All module-level settings — users, SMTP, Celery broker, file storage backend, etc. — live in the admin UI. After upgrading an existing deployment, run once:
+
+```bash
+uv run sm-settings import-from-env
+```
+
+to seed DB overrides from the current `SM_*` environment.
+
+> **docker-compose note:** `docker-compose.yml` sets a few `SM_BG_TASKS_*` vars so Celery can reach the `redis` service by container hostname before the DB-backed settings are loaded. That's deployment plumbing — not a module config knob.
 
 See `framework-conventions.md` for the settings-per-module convention.
 

docs/release-notes/2026-04-21-db-backed-settings.md

@@ -0,0 +1,15 @@
+# DB-backed module settings
+
+Every `SM_<MODULE>_*` env var has moved to the admin UI at `/settings/modules`.
+`.env` now only needs `SM_DATABASE_URL` in typical deployments.
+
+## Upgrading
+
+After deploying this release:
+
+1. Run `uv run sm-settings import-from-env` once to seed the DB with your current environment values.
+2. Remove the `SM_<MODULE>_*` entries from your `.env` / deployment config (they're no longer read).
+
+## Breaking changes
+
+Setting `SM_USERS_ALLOW_SIGNUP=true` (or any other `SM_<MODULE>_*`) in the environment no longer has any effect. Use the admin UI or the `sm-settings` CLI.