Configuration

Yuva reads its whole configuration from environment variables when it starts. Values are trimmed; an empty variable counts as unset and takes the default. Lists are comma-separated. Booleans accept true/false, 1/0, t/f. The server refuses to start on an invalid value and says which variable is wrong.

Settings that belong to one workspace, inbox or channel (SMTP accounts of e-mail channels, allowed origins of chat channels, webhooks, business hours, …) are not environment variables; they are made in the panel, through /v1, or with the operator commands.

In short

Everything is an environment variable, read once at start; a wrong value stops the server with its name.
Only three are required: YUVA_DATABASE_URL, YUVA_MASTER_KEY and YUVA_PUBLIC_URL.
Per-workspace, inbox and channel settings are not here; they live in the panel and the API.

Required

Variable	Meaning
`YUVA_DATABASE_URL`	Postgres connection URL, e.g. `postgres://yuva:secret@db:5432/yuva?sslmode=disable`. Postgres 16 or newer. Every command that touches the database needs it.
`YUVA_MASTER_KEY`	32 random bytes, base64-encoded (`openssl rand -base64 32`). Encrypts the secrets Yuva stores: SMTP passwords, inbox identity secrets and webhook signing secrets. `serve`, `ingest-email`, `inbox` and `channel` refuse to run without it. See Master key.
`YUVA_PUBLIC_URL`	The URL people and apps reach the server at, e.g. `https://support.example.com`. Default `http://localhost:8080`, which is only right for trying Yuva on your own machine. Must be an absolute `http` or `https` URL; serve Yuva at the root of its host name. It sets the defaults of the cookie, passkey and origin settings below and the links in e-mails.

Server

Variable	Default	Meaning
`YUVA_LISTEN_ADDR`	`:8080`	Address of the HTTP server: panel, API, WebSockets, widget scripts, ingress, `/healthz`, `/readyz`.
`YUVA_METRICS_ADDR`	`:9090`	Address of the Prometheus listener (`GET /metrics`). Keep it off the public internet. `off` or an empty value turns the listener off.
`YUVA_CLIENT_IP_HEADER`	unset	Header your reverse proxy puts the client’s IP address in, e.g. `X-Real-IP`. Rate limits are counted per client IP; unset, the TCP peer address is used, which behind a proxy is the proxy. With a comma-separated list such as `X-Forwarded-For`, Yuva takes the rightmost address that is not in `YUVA_TRUSTED_PROXIES` (the one your proxy appended); values further left are whatever the client sent.
`YUVA_TRUSTED_PROXIES`	unset	Comma-separated addresses or CIDR ranges of your reverse proxies, e.g. `10.0.0.0/8,fd00::/8`. When set, `YUVA_CLIENT_IP_HEADER` is used only for requests whose TCP peer is one of them, and their own entries are skipped when reading the header from the right. Set it when more than one proxy appends to the header.
`YUVA_COOKIE_SECURE`	`true` when `YUVA_PUBLIC_URL` is `https`	Marks the member session cookie `Secure`.

Variable	Default	Meaning
`YUVA_WEBAUTHN_RP_ID`	host name of `YUVA_PUBLIC_URL`	Passkey relying party id. Changing it later makes existing passkeys unusable.
`YUVA_WEBAUTHN_RP_NAME`	`Yuva`	Name browsers show when a passkey is created.
`YUVA_WEBAUTHN_ORIGINS`	origin of `YUVA_PUBLIC_URL`	Origins allowed for passkey ceremonies. The panel’s realtime socket also accepts these origins next to `YUVA_PUBLIC_URL`.

Server e-mail

The server’s own mail: sign-in codes, invitations and member notification e-mails. E-mail channels send replies to contacts through their own SMTP account (see E-mail).

Variable	Default	Meaning
`YUVA_SMTP_HOST`	unset	SMTP server. Unset, mails are written to the log instead of being sent (the server warns at start), which is enough to read a sign-in code while testing.
`YUVA_SMTP_PORT`	`465` with `YUVA_SMTP_TLS=tls`, else `587`	SMTP port.
`YUVA_SMTP_TLS`	`starttls`	`starttls`, `tls` (implicit TLS) or `none`.
`YUVA_SMTP_USERNAME`	unset	SMTP user name.
`YUVA_SMTP_PASSWORD`	unset	SMTP password.
`YUVA_SMTP_FROM`	unset	Sender, e.g. `Yuva <yuva@example.com>`. Required when `YUVA_SMTP_HOST` is set.
`YUVA_SMTP_ALLOW_PRIVATE`	`false`	Lets e-mail channels send through SMTP servers on loopback and private addresses, such as Mailpit in development (`deploy/compose.yaml` sets it). Without it, a channel cannot be saved with such a literal address or `localhost` as its SMTP host, and a channel whose host name resolves to such an address fails to send. Link-local and cloud metadata addresses stay refused. Does not affect `YUVA_SMTP_HOST`.

Attachments and storage

Attachments and the original of every inbound e-mail are stored as objects, never public; members download them through the API, which checks inbox access.

Variable	Default	Meaning
`YUVA_STORAGE`	`local`	`local` (a directory) or `s3` (any S3-compatible service: S3, R2, MinIO, …).
`YUVA_STORAGE_DIR`	`data/attachments`	Directory for `local`. The Docker image has `/data/attachments`; mount a volume at `/data`.
`YUVA_S3_ENDPOINT`	unset	S3 endpoint URL, e.g. `https://s3.eu-central-1.amazonaws.com` or your R2 or MinIO endpoint.
`YUVA_S3_REGION`	`auto`	Region.
`YUVA_S3_BUCKET`	unset	Bucket.
`YUVA_S3_ACCESS_KEY_ID`	unset	Access key id.
`YUVA_S3_SECRET_ACCESS_KEY`	unset	Secret access key.
`YUVA_S3_PATH_STYLE`	`false`	Path-style URLs (`endpoint/bucket/key`), which MinIO usually needs.
`YUVA_ATTACHMENT_MAX_BYTES`	`26214400` (25 MiB)	Largest attachment accepted, in bytes.
`YUVA_ATTACHMENT_TYPES`	see below	Allowed content types, comma-separated; `image/*` style wildcards are allowed.

The default YUVA_ATTACHMENT_TYPES is image/png,image/jpeg,image/gif,image/webp,image/heic,application/pdf,text/plain,text/csv,application/zip,application/json,video/mp4,video/quicktime,audio/mpeg,audio/mp4. Inbound e-mail parts outside these rules are skipped; they stay in the stored original.

Inbound e-mail

Variable	Default	Meaning
`YUVA_INGRESS_SECRET`	unset	Shared secret that signs requests to `/ingress/email` (the Cloudflare Email Worker uses the same value). Unset, `/ingress/email` refuses all mail. `yuva ingest-email` does not need it. Generate it with `openssl rand -hex 32`.
`YUVA_INGRESS_ACCEPT_V1`	`false`	Also accept the deprecated `v1` request signature, which does not cover `X-Yuva-Envelope-From` (see `edge/README.md`). Under `v1` the envelope sender is not trusted: an empty one never makes a message a delivery report or automatic. Set it only while an older Email Worker or relay still signs with `v1`; the server warns at start while it is on.
`YUVA_INGRESS_AUTHSERV_ID`	unset	The authserv-id of the server that receives your mail and stamps `Authentication-Results`, e.g. `mx.cloudflare.net` for Cloudflare Email Routing. Only the topmost `Authentication-Results` is read, and its DMARC verdict is used (spam flag, threading) only when it starts with this id; any other header could have come with the message. Unset, the header is stored and shown but DMARC is treated as unknown.
`YUVA_INGRESS_MAX_CONCURRENT`	`8`	Most messages `/ingress/email` processes at once per server process. Further requests are answered `503 unavailable` before their body is read; the Email Worker then forwards to its fallback address or fails the delivery so the sending server retries.
`YUVA_SES_TOPIC_ARNS`	unset	Amazon SNS topic ARNs whose SES bounce and complaint notifications `/ingress/ses` accepts, comma-separated. Unset, none are accepted.
`YUVA_EMAIL_SENDER_HOURLY_CAP`	`500`	Most inbound e-mails one sender may send to a workspace per hour. Mail beyond it is refused (`429 rate_limited`, a permanent rejection through the Email Worker). Below it no mail is refused for volume.

Chat

Variable	Default	Meaning
`YUVA_CHAT_EMAIL_DELAY`	`5m`	How long a member’s reply stays unread, and the contact gone, before it is e-mailed to a contact who left the chat. A Go duration of at least `1s`, such as `90s` or `10m`.
`YUVA_ANONYMOUS_CONTACTS_PER_HOUR`	`20`	Most new anonymous visitors one IP address (an IPv6 /64) may start per chat or app channel and hour; more answer `429 anonymous_limit`. Resuming a visitor with its `visitor_id` does not count. Counted per server process.

Webhooks

Variable	Default	Meaning
`YUVA_WEBHOOK_ALLOW_PRIVATE`	`false`	Lets webhooks reach loopback and private addresses, for development. Never set it on a server others use. Link-local and cloud metadata addresses stay refused.

Web Push

Member notifications on phones and desktops through the installable panel. Without keys, Web Push is off and members get e-mail notifications only.

Variable	Default	Meaning
`YUVA_VAPID_PUBLIC_KEY`	unset	VAPID public key. Set both keys or neither; `yuva vapid-keys` prints a pair.
`YUVA_VAPID_PRIVATE_KEY`	unset	VAPID private key.
`YUVA_VAPID_SUBJECT`	`mailto:` + the address in `YUVA_SMTP_FROM`, else `YUVA_PUBLIC_URL` when it is `https`	Contact for push services, `mailto:you@example.com` or an `https://` URL. Required when neither default applies.

Keep the key pair once members have subscribed: browser subscriptions are bound to the public key, so after a change members have to turn notifications on again.

Build

The version the server reports (GET /v1/version, the start log) is set at build time with the Docker build argument VERSION (-X main.version); it is not an environment variable.