Environment variables

Use the web UI for most settings. Use these variables for Docker deployment settings.

Mounts and permissions

Variable	Purpose
PUID / PGID	Run the container as the user that owns mounted folders.
AURRAL_DATA_DIR	Override app data directory. Default /config.
DOWNLOAD_FOLDER	Initial Downloads Folder path. Prefer Settings > Download clients > Downloads Folder > Path. Use an absolute path under your media mount.

Path mappings

Variable	Purpose
PATH_MAPPINGS	Translate paths for mixed Windows and Docker setups. Use the format remote|local. Separate multiple mappings with ;. To limit a mapping to one source, use source|remote|local. Aurral applies these mappings at runtime. Edit them under Settings > Download clients > Remote Path Mappings.

Authentication

Better Auth configuration is optional. When BETTER_AUTH_SECRET is omitted, Aurral generates a random secret and stores it in the /config database. When BETTER_AUTH_URL is omitted, Better Auth derives the origin from the incoming request.

Set BETTER_AUTH_SECRET explicitly only when you manage secrets outside /config. Keep a configured value stable across restarts. Changing it invalidates active authentication state and requires users to sign in again.

For installations behind a proxy, keep the public Host and protocol forwarded to Aurral. Set BETTER_AUTH_URL when the public origin cannot be inferred reliably, especially for OIDC callbacks.

Generate an explicit secret with:

openssl rand -hex 32

If you set a value explicitly, keep it in your environment file or secret store. Do not commit it to a Compose file. Keep the same value across restarts. Changing it invalidates active authentication state and requires users to sign in again.

Variable	Purpose
BETTER_AUTH_SECRET	Optional Better Auth secret override. If omitted, Aurral generates and stores one in /config.
BETTER_AUTH_URL	Optional public Aurral origin for Better Auth callbacks, for example https://aurral.example.com. If omitted, Better Auth uses the request origin.
SESSION_EXPIRY_HOURS	Better Auth session lifetime in hours. Default 720 (30 days).
AURRAL_PUBLIC_URL	Public Aurral origin used by non-authentication integration callbacks. Aurral also accepts it as a compatibility fallback when BETTER_AUTH_URL is omitted.
TRUST_PROXY	Set when Aurral is behind a reverse proxy.
AUTH_PROXY_ENABLED	Enable reverse-proxy authentication. Default header x-forwarded-user.
AUTH_PROXY_HEADER	Custom header that contains the authenticated identity.
AUTH_PROXY_DOMAIN	Origin of your forwardAuth login page. Aurral adds it to the connect-src content security policy.
AUTH_PROXY_TRUSTED_IPS	Comma-separated proxy IP allowlist for authentication headers. Set it when you enable proxy authentication.
AUTH_PROXY_LOGOUT_URL	Proxy or identity-provider logout endpoint. Aurral redirects there after local logout.
AUTH_PROXY_DEFAULT_ROLE	Role for proxy identities that do not otherwise receive administrator access: user or admin.
AUTH_PROXY_ADMIN_USERS	Comma-separated identities that receive the admin role.
AUTH_PROXY_ROLE_HEADER	Header that contains group membership, such as Authelia’s Remote-Groups.
AUTH_PROXY_ADMIN_GROUPS	Comma-separated groups that grant the admin role.
OIDC_ENABLED	Enable the Better Auth OIDC provider.
OIDC_PROVIDER_ID	Provider identifier used by Better Auth. Default oidc.
OIDC_ISSUER	Identity-provider issuer URL.
OIDC_DISCOVERY_URL	Optional discovery document URL when the provider does not use its standard location.
OIDC_CLIENT_ID	OIDC client ID.
OIDC_CLIENT_SECRET	OIDC client secret.
OIDC_REDIRECT_URI	Exact callback URL registered with the provider. Use https://<your-aurral-host>/api/auth/callback/oidc.
OIDC_USERNAME_CLAIM	Provider claim used for Aurral’s compatibility username field. Default preferred_username.
OIDC_ADMIN_USERS	Comma-separated provider identities that receive the admin role.

Register only /api/auth/callback/oidc with the identity provider. Better Auth completes the provider transaction and creates the session.

Cross-origin clients

Variable	Purpose
CORS_ORIGIN	Comma-separated browser origins allowed to call Aurral’s JSON API with authenticated credentials. Browser Subsonic clients do not need this setting.

Logging

Variable	Purpose
AURRAL_VERBOSE_LOGS	Set to true to include routine and debug server logs. Regular logs show startup messages, warnings, and errors.

Image proxy

Variable	Purpose
AURRAL_IMAGE_PROXY_MAX_BYTES	Maximum image-proxy disk-cache size in bytes. The default is 268435456 (256MB). Aurral removes the oldest entries first. When Aurral serves an image, it updates the age of that image.

Last.fm tuning

Variable	Purpose
AURRAL_LASTFM_TIMEOUT_MS	Last.fm API timeout in milliseconds. Default 15000. Increase this value if focus playlists have no tracks and logs show ECONNABORTED.

Spotify playlist import

These variables change the shared Lidarr Spotify OAuth proxy. The default values are correct for most installations.

Variable	Purpose
SPOTIFY_CLIENT_ID	OAuth client ID.
SPOTIFY_OAUTH_REDIRECT_URI	Authorization redirect. Default https://spotify.lidarr.audio/auth.
SPOTIFY_OAUTH_RENEW_URI	Token refresh endpoint. Default https://spotify.lidarr.audio/renew.

Example

environment:
  - PUID=1000
  - PGID=1000
  - TRUST_PROXY=true

For mounts and path mappings, see Filesystem and mounts.