# Configuration

YotoShelf is configured entirely via environment variables. All variables are prefixed `YOTOSHELF_`. CLI flags take precedence over environment variables; environment variables take precedence over defaults.

## Core

| Variable | Default | Purpose |
|---|---|---|
| `YOTOSHELF_LISTEN_ADDR` | `:8080` | TCP address the server listens on |
| `YOTOSHELF_PUBLIC_URL` | (none) | Externally visible URL. Required for OAuth callbacks and share links. |
| `YOTOSHELF_DB_PATH` | `yotoshelf.db` | Path to the SQLite database file |
| `YOTOSHELF_LIBRARY_PATH` | `library` | Directory for audio files, covers, and generated assets |
| `YOTOSHELF_SESSION_SECRET` | (required) | HMAC secret for session cookies. At least 32 bytes. |
| `YOTOSHELF_ENCRYPTION_KEY` | (required) | AES key for Yoto tokens at rest. At least 32 bytes. |
| `YOTOSHELF_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `YOTOSHELF_LOG_FORMAT` | `json` | Log format: `json` or `text` |
| `YOTOSHELF_TRUST_PROXY` | `false` | Trust `X-Forwarded-For` headers (enable behind a reverse proxy) |

## Auth

| Variable | Default | Purpose |
|---|---|---|
| `YOTOSHELF_LOCAL_AUTH_ENABLED` | `true` | Enable local password authentication |
| `YOTOSHELF_OIDC_ENABLED` | `false` | Enable OIDC login |
| `YOTOSHELF_OIDC_ISSUER` | (none) | OIDC issuer URL |
| `YOTOSHELF_OIDC_CLIENT_ID` | (none) | OIDC client ID |
| `YOTOSHELF_OIDC_CLIENT_SECRET` | (none) | OIDC client secret |
| `YOTOSHELF_SESSION_MAX_AGE` | `604800` | Session cookie lifetime in seconds (default: 7 days) |

## SMTP (optional)

| Variable | Default | Purpose |
|---|---|---|
| `YOTOSHELF_SMTP_HOST` | (none) | SMTP hostname |
| `YOTOSHELF_SMTP_PORT` | `587` | SMTP port |
| `YOTOSHELF_SMTP_USER` | (none) | SMTP username |
| `YOTOSHELF_SMTP_PASS` | (none) | SMTP password |
| `YOTOSHELF_SMTP_FROM` | (none) | From address for outbound email |

SMTP is optional. Without it, password reset and email verification are disabled.

## Observability

| Variable | Default | Purpose |
|---|---|---|
| `YOTOSHELF_METRICS_TOKEN` | (none) | Bearer token required for `GET /metrics`. If unset, metrics are disabled. |

## Yoto client

| Variable | Default | Purpose |
|---|---|---|
| `YOTOSHELF_YOTO_CLIENT_ID` | (built-in) | OAuth2 client ID for Yoto API. Override only for testing. |