Configuration

Each qbrix service reads its settings from environment variables with its own prefix: PROXY_ for the API, MOTOR_ for selection, CORTEX_ for learning and TRACE_ for the analytics writer. A few logging variables are shared.

You rarely set these directly:

Docker Compose reads .env, whose shorter names (SIGNUP_MODE, SMTP_HOST, …) are mapped onto the variables below. .env.example documents each one.
Helm sets them from the chart's values, such as proxy.config.signupMode. The chart's README lists the values.

This page is the reference underneath both, for when you run the images some other way or need a setting neither exposes.

API (`PROXY_`)

The proxy serves the REST API and the console's backend, and routes selection to the selection service.

Secrets

Set all three to long random values. bin/selfhost-init and the Helm chart generate them for you.

Variable	Default	Description
`PROXY_POSTGRES_PASSWORD`	`qbrix`	Postgres password
`PROXY_JWT_SECRET_KEY`	`change-me-in-production`	Signs console sessions. Changing it signs everyone out
`PROXY_TOKEN_SECRET`	`change-me-in-production`	Signs the `request_id` that `select` returns and `feedback` sends back. Changing it invalidates selections still waiting for feedback

Databases and services

Variable	Default	Description
`PROXY_POSTGRES_HOST` / `_PORT`	`localhost` / `5432`	Postgres
`PROXY_POSTGRES_USER` / `_DATABASE`	`qbrix` / `qbrix`	Postgres user and database
`PROXY_REDIS_HOST` / `_PORT`	`localhost` / `6379`	Redis
`PROXY_REDIS_PASSWORD` / `_DB`	unset / `0`	Redis auth and database number
`PROXY_MOTOR_HOST` / `_PORT`	`localhost` / `50051`	The selection service
`PROXY_CORTEX_HOST` / `_PORT`	`localhost` / `50052`	The learning service

Variable	Default	Description
`PROXY_SIGNUP_MODE`	`first-user`	`first-user`, `invite-only` or `open`. See who can sign up
`PROXY_JWT_ACCESS_TOKEN_EXPIRE_MINUTES`	`30`	Console session lifetime before a silent refresh
`PROXY_JWT_REFRESH_TOKEN_EXPIRE_DAYS`	`7`	How long a console sign-in lasts
`PROXY_TOKEN_MAX_AGE_MS`	unset	How old a selection may be and still accept feedback, in milliseconds. Unset means no limit

Email

Variable	Default	Description
`PROXY_EMAIL_PROVIDER`	`auto`	`auto`, `smtp`, `resend` or `none`. See Email
`PROXY_EMAIL_FROM`	`qbrix <noreply@localhost>`	Sender address
`PROXY_SMTP_HOST` / `_PORT`	unset / `587`	SMTP relay
`PROXY_SMTP_USERNAME` / `_PASSWORD`	unset	SMTP credentials
`PROXY_SMTP_STARTTLS`	`true`	Upgrade the SMTP connection with STARTTLS
`PROXY_RESEND_API_KEY`	unset	Resend API key
`PROXY_EMAIL_VERIFICATION_TTL_SECONDS`	`86400`	How long a verification link stays valid

Network

Variable	Default	Description
`PROXY_HTTP_PORT`	`8080`	REST API port
`PROXY_GRPC_PORT`	`50050`	gRPC API port
`PROXY_CONSOLE_URL`	unset	Public console URL used in email links. Unset falls back to `http://localhost:3001`; Compose and Helm set it for you
`PROXY_CORS_ORIGINS`	unset	Extra browser origins allowed to call the API with credentials, comma separated. Only needed when the console is served from a different origin than the API
`PROXY_TRUSTED_PROXY_HOPS`	`1`	Reverse proxies in front of the API that append to `X-Forwarded-For`. The login rate limit keys on the client address this many hops from the right
`PROXY_TRUST_CLOUDFRONT_HEADER`	`false`	Key the login rate limit on `CloudFront-Viewer-Address`. Only safe when CloudFront is the sole way in and its origin request policy adds that header

Analytics

Variable	Default	Description
`PROXY_ANALYTICS_ENABLED`	`false`	Serve insights and the event log, and publish the events they are built from. Needs ClickHouse and the analytics writer
`PROXY_CLICKHOUSE_HOST` / `_PORT`	`localhost` / `8123`	ClickHouse HTTP interface
`PROXY_CLICKHOUSE_USER` / `_PASSWORD` / `_DATABASE`	`default` / unset / `qbrix`	ClickHouse credentials and database

Environment

Variable	Default	Description
`PROXY_RUNENV`	`prod`	Leave it at `prod`. `dev` turns off authentication and signs every request in as a built-in development user, for working on qbrix itself

Careful

Never set PROXY_RUNENV=dev on an install anyone else can reach. Every request is then accepted without a key or a session.

PROXY_EE_ENABLED and the PROXY_STRIPE_* variables belong to the managed cloud edition. Leave them unset on a self-hosted install.

Selection (`MOTOR_`)

Variable	Default	Description
`MOTOR_REDIS_HOST` / `_PORT`	`localhost` / `6379`	Redis
`MOTOR_REDIS_PASSWORD` / `_DB`	unset / `0`	Redis auth and database number
`MOTOR_GRPC_PORT`	`50051`	gRPC port the API calls
`MOTOR_PARAM_CACHE_TTL`	`60`	Seconds learned parameters are cached before re-reading Redis. Traffic allocation moves when this refreshes, not on every feedback

Learning (`CORTEX_`)

Run exactly one learning service. It applies feedback in order, and two instances would race to update the same parameters.

Variable	Default	Description
`CORTEX_REDIS_HOST` / `_PORT`	`localhost` / `6379`	Redis
`CORTEX_REDIS_PASSWORD` / `_DB`	unset / `0`	Redis auth and database number
`CORTEX_GRPC_PORT`	`50052`	gRPC port
`CORTEX_BATCH_SIZE`	`256`	Feedback events trained on per batch
`CORTEX_NUM_WORKERS`	`4`	Training workers

Analytics writer (`TRACE_`)

Only runs with analytics on. It scales horizontally; give each replica its own TRACE_CONSUMER_NAME.

Variable	Default	Description
`TRACE_REDIS_HOST` / `_PORT`	`localhost` / `6379`	Redis
`TRACE_REDIS_PASSWORD` / `_DB`	unset / `0`	Redis auth and database number
`TRACE_CLICKHOUSE_HOST` / `_PORT`	`localhost` / `8123`	ClickHouse HTTP interface
`TRACE_CLICKHOUSE_USER` / `_PASSWORD` / `_DATABASE`	`default` / unset / `qbrix`	ClickHouse credentials and database
`TRACE_CONSUMER_NAME`	`worker-0`	This replica's identity in the event stream. Must differ per replica
`TRACE_BATCH_SIZE`	`500`	Events written to ClickHouse per batch
`TRACE_FLUSH_INTERVAL_SEC`	`5.0`	Longest an event waits before it is written

Every service

Variable	Default	Description
`{SERVICE}_SHUTDOWN_GRACE_SEC`	`20`	Seconds a service spends draining in-flight work on shutdown. On Kubernetes, `terminationGracePeriodSeconds` must be longer
`LOG_LEVEL`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. `{SERVICE}_LOG_LEVEL` overrides it for one service, e.g. `MOTOR_LOG_LEVEL`
`LOG_FORMAT`	`text`	`json` for structured logs, `text` for people
`SENTRY_DSN`	unset	Send errors to Sentry. `{SERVICE}_SENTRY_DSN` overrides it for one service. Unset sends nothing

Next steps

Self-hosting — install, upgrade and back up
Roles & limits — what each role can do, and the rate limits