Configuration

The server is configured entirely through environment variables with the VOUCH_ prefix, parsed by Settings in server/src/vouch/config.py. All have defaults suitable for local development.

Variable	Default	Purpose
VOUCH_DATABASE_URL	postgresql+asyncpg://vouch:vouch@localhost:5432/vouch	SQLAlchemy async DSN. Ignored when VOUCH_PG_HOST is set.
VOUCH_JWT_SECRET	dev-secret	HMAC secret for access tokens and the OAuth state cookie. Must be overridden in production — the app refuses to start on the default.
VOUCH_PHONE_PEPPER	dev-pepper	HMAC key for phone-number hashes and SMS codes. Must be overridden in production (startup refuses the default) and never rotated — every verification is keyed on it.
VOUCH_ADMIN_BOOTSTRAP_TOKEN	(unset)	Registering with this admin_token creates an admin.
VOUCH_PUBLIC_URL	http://localhost:5173	Public origin of the web app. Google’s redirect URI is <public_url>/auth/google/callback; cookies are Secure iff it is https.
VOUCH_GOOGLE_CLIENT_ID	(unset)	Google OAuth client id. Unset → /auth/google/* answer 404.
VOUCH_GOOGLE_CLIENT_SECRET	(unset)	Google OAuth client secret.
VOUCH_ACCESS_TOKEN_TTL_SECONDS	900	Access-token lifetime.
VOUCH_REFRESH_TOKEN_TTL_DAYS	30	Session (refresh cookie) lifetime.
VOUCH_SMS_BACKEND	log	log prints verification codes to the API log and keeps the last 50 in an in-memory outbox readable by admins at GET /admin/sms/outbox (and in the admin UI / vouch admin sms-outbox); sns sends real SMS via AWS SNS and the outbox answers 404.
VOUCH_AWS_REGION	(unset)	Required when VOUCH_SMS_BACKEND=sns. Credentials come from the ambient AWS chain (instance role).
VOUCH_SMS_MONTHLY_SPEND_LIMIT_USD	10	Set as the SNS account SMS spend cap at startup.
VOUCH_MATCHER_INTERVAL_SECONDS	60	Background matcher loop period. 0 disables the loop. With several API replicas only the one holding the Postgres advisory lock runs the pass; the others record a skip (visible in GET /admin/overview).
VOUCH_NOTICE_VERSION	1	Version of the privacy notice; recorded on the account when a user accepts it. Bump it when the notice changes materially and the client asks every user to accept again.
VOUCH_REPORT_RETENTION_DAYS	90	Resolved reports are deleted after this many days. 0 disables.
VOUCH_BAN_RETENTION_DAYS	365	Banned accounts are deleted after this many days (kept that long so a ban cannot be escaped by re-registering the same number). 0 disables.
VOUCH_INACTIVE_ACCOUNT_DAYS	365	Accounts whose sessions have not been used for this many days are deleted. 0 disables.
VOUCH_PUBLISH_PER_HOUR	6	Maximum PUT /me/contact-set versions per user per rolling hour; the next one answers 429 too_many_publishes with a Retry-After header. 0 disables the quota.
VOUCH_OTEL_ENABLED	false	Enable OpenTelemetry export.

CloudNativePG connection parts

CloudNativePG exposes connection details as separate secret keys rather than a single URL. When VOUCH_PG_HOST is set, these override VOUCH_DATABASE_URL so the deployment can wire the CNPG -app secret straight in.

Variable	Default	Purpose
VOUCH_PG_HOST	(unset)	When set, builds the DSN from the parts below.
VOUCH_PG_PORT	5432	Postgres port.
VOUCH_PG_USER	(unset)	Postgres user.
VOUCH_PG_PASSWORD	(unset)	Postgres password.
VOUCH_PG_DB	(unset)	Postgres database name.
VOUCH_PG_STATEMENT_CACHE	100	asyncpg prepared-statement cache size. Set to 0 when connecting through a transaction-mode pooler (the chart’s CNPG Pooler), where prepared statements do not survive across pooled connections.

Note

This table is maintained by hand from config.py. When you add or rename a setting, update it here — settings are not part of the OpenAPI spec, so they aren’t auto-generated.