Configuration

Runtime configuration, secrets, and provider-specific SMTP settings.

Use this page to decide which files belong to local development, which values must come from secrets, and what must change when moving the service to production.

Configuration Model

The service has two configuration layers: static userver component configuration and runtime variables. Static configuration defines which components and handlers exist. Runtime variables provide environment-specific values such as ports, database URLs, JWT keys, and SMTP credentials.

File	Use	Production rule
`configs/static_config.yaml`	Local development and testsuite-enabled workflows.	Do not use for internet-facing production if it enables test handlers.
`configs/static_config.prod.yaml`	Production component graph and HTTP handlers.	Use this file for production containers.
`configs/config_vars.yaml`	Runtime values loaded by the static config.	Generate or mount it from a secret store; do not bake real secrets into the image.
`configs/config_vars.docker.yaml`	Local Docker/devcontainer values.	Treat as local/demo config when it contains credentials.
`.env`	Docker Compose variables for local Postgres and migration jobs.	Keep it untracked and environment-specific.

Runtime Variables

Setting	Required	Notes
`worker-threads`	Yes	Main userver task processor size for request handling.
`worker-fs-threads`	Yes	Filesystem/blocking utility processor size.
`worker-email-outbox-threads`	Yes	Dedicated SMTP delivery processor. Keep email delivery off the main request path.
`logger-level`	Yes	Use `info` in production unless debugging a controlled incident.
`is-testing`	Yes	Must be `false` outside testsuite or local test runs.
`server-port`	Yes	HTTP listen port inside the container.
`postgres-dbconnection`	Yes	Postgres DSN used by the service. Keep aligned with migration DSN for the same environment.
`AUTH_JWT_AUDIENCE`	Yes	Audience claim expected by downstream services.
`AUTH_JWT_KEY_ID`	Yes	Stable key id exposed as token `kid` and in JWKS.
`AUTH_JWT_PRIVATE_KEY_PATH`	Yes	Path to the RSA private key mounted inside the runtime container.
`AUTH_JWT_PUBLIC_KEY_PATH`	Yes	Path to the RSA public key served through JWKS.

SMTP Variables

Email verification depends on the outbox worker and the SMTP variables below. Values are provider-specific, so production should use the provider documentation and a secret store, not copied local credentials.

Setting	Example	Production guidance
`AUTH_SMTP_HOST`	`smtp.gmail.com`	Use a controlled relay or transactional provider for production.
`AUTH_SMTP_PORT`	`465`	Use `465` for implicit TLS or `587` for STARTTLS.
`AUTH_SMTP_TLS_MODE`	`tls`	Use `tls` with port `465`, `starttls` with port `587`, and `none` only for fake local SMTP.
`AUTH_SMTP_USERNAME`	`your-account@gmail.com`	Use provider-issued credentials with the narrowest available scope.
`AUTH_SMTP_APP_PASSWORD`	`<secret>`	Never commit it. Rotate immediately after exposure in chat, logs, screenshots, or git.
`AUTH_SMTP_FROM_EMAIL`	`no-reply@example.com`	Must be authorized by provider policy and aligned with SPF, DKIM, and DMARC.
`AUTH_SMTP_FROM_NAME`	`Smirkly`	Human sender name displayed by email clients.

AUTH_SMTP_HOST: smtp.gmail.com
AUTH_SMTP_PORT: 465
AUTH_SMTP_TLS_MODE: tls
AUTH_SMTP_USERNAME: your-account@gmail.com
AUTH_SMTP_APP_PASSWORD: "<gmail-app-password>"
AUTH_SMTP_FROM_EMAIL: your-account@gmail.com
AUTH_SMTP_FROM_NAME: "Smirkly"

Client IP and Proxy Headers

The service can use forwarded client IP headers only when the immediate peer is a trusted proxy. Configure trusted proxy CIDRs to match the ingress or load balancer ranges exactly. Do not trust arbitrary X-Forwarded-For or X-Real-IP values from the public internet.

Change Rules

Changing source code requires a rebuild and service restart.
Changing config_vars.yaml requires a service restart, not a rebuild.
Changing migrations requires running the migration job before the new service version starts.
Changing JWT keys requires a planned rotation window and downstream JWKS cache awareness.