Self-Host

Configuration

Environment variable reference for YotoShelf. All knobs, their defaults, and when to set them.

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 — 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.

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).

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.

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).