Configuration

Required Variables

These three environment variables must be set for Sofa to start:

BETTER_AUTH_URL is critical when using a reverse proxy or OIDC — it must match the URL users access in their browser.

Data & Storage

DATABASE_URL and CACHE_DIR are derived from DATA_DIR by default but can be overridden independently.

The database uses SQLite with WAL (Write-Ahead Logging) mode for concurrent read access. Migrations run automatically on every startup.

Image Caching

When enabled, Sofa downloads poster, backdrop, and other images from TMDB and serves them from disk. This improves load times and reduces external requests but uses disk space.

Cached images are stored in subdirectories under CACHE_DIR:

images/
├── posters/       # 500px wide
├── backdrops/     # 1280px wide
├── stills/        # 1280px wide (episode stills)
├── logos/         # 92px wide (provider logos)
└── profiles/      # 185px wide (cast photos)

Set IMAGE_CACHE_ENABLED=false to serve images directly from TMDB's CDN instead.

Logging

Sofa uses structured JSON logging via Pino. Set to debug for troubleshooting.

OIDC / SSO

Sofa supports any OpenID Connect provider (Authentik, Keycloak, Authelia, Google Workspace, etc.). OIDC is enabled when all three of OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_ISSUER_URL are set.

Callback URL

Configure this redirect URI in your identity provider:

https://your-sofa-url.com/api/auth/oauth2/callback/oidc

Replace https://your-sofa-url.com with your BETTER_AUTH_URL value.

Example: Authentik

1. In Authentik, create a new OAuth2/OpenID Provider
2. Set the redirect URI to https://sofa.example.com/api/auth/oauth2/callback/oidc
3. Note the Client ID and Client Secret
4. Add to your .env:

OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret
OIDC_ISSUER_URL=https://authentik.example.com/application/o/sofa
OIDC_PROVIDER_NAME=Authentik

Example: Keycloak

1. In Keycloak, create a new OpenID Connect client in your realm
2. Set the Valid Redirect URI to https://sofa.example.com/api/auth/oauth2/callback/oidc
3. Add to your .env:

OIDC_CLIENT_ID=sofa
OIDC_CLIENT_SECRET=your_client_secret
OIDC_ISSUER_URL=https://keycloak.example.com/realms/your-realm
OIDC_PROVIDER_NAME=Keycloak

Disabling Password Login

To enforce SSO-only login, set DISABLE_PASSWORD_LOGIN=true. This only takes effect when OIDC is configured. The admin account created during setup will still work via OIDC.

Account Linking

When OIDC is enabled, account linking is active by default. If a user logs in via OIDC with an email address that matches an existing Sofa account, the accounts are automatically linked — no manual confirmation is required. This means existing users can start using SSO without losing their library or watch history.

Auto-Registration and Password Login

OIDC_AUTO_REGISTER and DISABLE_PASSWORD_LOGIN interact to control how users can access your instance:

TMDB Overrides

These are only needed if you're proxying TMDB requests or using an alternative endpoint.

Network

Set CORS_ORIGIN to your public URL when using a reverse proxy.

Update Checks

Sofa checks for new versions every 6 hours by contacting the public API.

Update checks can be disabled in Settings → Admin → Update Checks. When a new version is available, a notification appears in the admin settings.

Telemetry

Sofa includes opt-in anonymous telemetry. It is disabled by default. See the Telemetry page for full details on what is and isn't collected.

Scheduled Backups

Automatic backups can be enabled in Settings → Admin → Backups. Configuration options:

Backups are SQLite database dumps stored in the backups/ directory inside DATA_DIR. Old backups beyond the retention count are automatically deleted.

Background Jobs

Sofa runs several background jobs automatically:

All schedules are in UTC. TMDB API calls are rate-limited with a 300ms delay between requests per title to stay within API limits.