Configuration

Configuration is loaded from environment variables with the prefix YOTOSHELF_. Precedence: CLI flags > environment variables > built-in defaults. There is no config file; pass everything via the environment.

Core

Variable	Default	Description
YOTOSHELF_DB_PATH	yotoshelf.db	Path to the SQLite database file. Put this on a persistent volume.
YOTOSHELF_LISTEN_ADDR	:8080	HTTP listen address and port.
YOTOSHELF_LIBRARY_PATH	library	Directory for audio files, cover images, and generated assets. Put this on a persistent volume.
YOTOSHELF_PUBLIC_URL	—	Externally visible base URL (e.g. https://yotoshelf.example.com). Required for OAuth callbacks and share links to work correctly.

Security

Variable	Default	Description
YOTOSHELF_SESSION_SECRET	—	Signing key for session cookies. Minimum 32 bytes. Required. Rotate to invalidate all active sessions.
YOTOSHELF_ENCRYPTION_KEY	—	Key for encrypting Yoto OAuth tokens at rest. Minimum 32 bytes. Required. Changing this invalidates stored tokens, so users must re-link their Yoto accounts.
YOTOSHELF_SECURE_COOKIES	true	Set the Secure flag on session cookies. Set to false for local HTTP development only.
YOTOSHELF_TRUST_PROXY	false	Read real client IP from X-Forwarded-For. Enable when behind a reverse proxy.
YOTOSHELF_SESSION_MAX_AGE	604800	Session lifetime in seconds. Default is 7 days.

Authentication

Variable	Default	Description
YOTOSHELF_LOCAL_AUTH_ENABLED	true	Enable local username/password login. Set to false to require OIDC.
YOTOSHELF_REQUIRE_EMAIL_VERIFICATION	true	Require users to verify their email address after registration.
YOTOSHELF_PASSWORD_MIN_LENGTH	10	Minimum password length for local accounts.
YOTOSHELF_LOCKOUT_THRESHOLD	5	Failed login attempts before account lockout.
YOTOSHELF_LOCKOUT_DURATION	900	Lockout duration in seconds (default: 15 minutes).

OIDC (single sign-on)

YotoShelf supports OpenID Connect for SSO. When configured, users authenticate via an external identity provider. The OIDC flow uses PKCE S256, nonce verification, and email_verified enforcement.

Variable	Default	Description
YOTOSHELF_OIDC_ISSUER	—	OIDC issuer URL, e.g. https://auth.example.com/application/o/yotoshelf/
YOTOSHELF_OIDC_CLIENT_ID	—	OAuth 2.0 client ID from your identity provider.
YOTOSHELF_OIDC_CLIENT_SECRET	—	OAuth 2.0 client secret.
YOTOSHELF_OIDC_REDIRECT_URL	{PUBLIC_URL}/auth/oidc/callback	OAuth callback URL. Defaults to the PUBLIC_URL-relative path.

Configure your IdP's backchannel logout to send POST requests to /auth/oidc/backchannel-logout. When LOCAL_AUTH_ENABLED=false, the first OIDC user to log in is auto-promoted to admin.

Yoto API

Variable	Default	Description
YOTOSHELF_YOTO_CLIENT_ID	—	Yoto OAuth application client ID. Required for publishing cards to Yoto accounts.
YOTOSHELF_YOTO_CLIENT_SECRET	—	Yoto OAuth application client secret.
YOTOSHELF_YOTO_REDIRECT_URL	http://localhost:8080/api/v1/yoto-accounts/callback	Yoto OAuth callback URL. Set to your public URL's equivalent path in production.

Email (SMTP)

Variable	Default	Description
YOTOSHELF_SMTP_HOST	—	SMTP server hostname.
YOTOSHELF_SMTP_PORT	587	SMTP server port.
YOTOSHELF_SMTP_USER	—	SMTP username.
YOTOSHELF_SMTP_PASSWORD	—	SMTP password.
YOTOSHELF_SMTP_FROM	—	Sender address for outbound email (verification, password reset).

Observability

Variable	Default	Description
YOTOSHELF_LOG_LEVEL	info	Log verbosity: debug, info, warn, error.
YOTOSHELF_LOG_FORMAT	json	Log output format: json or text.
YOTOSHELF_SLOW_QUERY_MS	100	Queries slower than this threshold (milliseconds) are logged as warnings.
YOTOSHELF_METRICS_TOKEN	—	Bearer token for the GET /metrics Prometheus endpoint. Unset = endpoint is open.
YOTOSHELF_OTEL_ENDPOINT	—	OTLP gRPC endpoint for distributed tracing. Empty = tracing disabled.
YOTOSHELF_TRACE_SAMPLE_RATE	0.1	Fraction of traces to sample (0.0–1.0).

Housekeeping

Variable	Default	Description
YOTOSHELF_AUDIT_RETENTION_DAYS	90	Days to keep audit log entries. Set to 0 to disable pruning.