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.
`LIDARR_ALLOW_HTTP`	Allow Aurral to send the Lidarr API key over HTTP. Default `false`. Use `true` only for a trusted local network. HTTPS is recommended.

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.
`M3U_PATH_MODE`	`local` (default, Aurral paths in `.m3u` files) or `remote` (paths Navidrome can open).
`M3U_PATH_MAPPINGS`	Translate Navidrome playlist paths. Use the format `Aurral path\|Navidrome path`. Separate multiple mappings with `;`. Aurral applies these mappings at runtime. The UI does not show them.

Authentication

Variable	Purpose
`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 username.
`AUTH_PROXY_DOMAIN`	Origin of your forwardAuth login page (for example, `https://auth.example.com`). Aurral adds it to the `connect-src` content security policy so pages can reach your authentication origin.
`AUTH_PROXY_TRUSTED_IPS`	Comma-separated proxy IP allowlist for authentication headers. You must set it when you enable proxy authentication. Without it, a direct client can use the identity header to impersonate users.
`AUTH_PROXY_LOGOUT_URL`	Your proxy or IdP logout endpoint. For Authentik single-application forward auth, use `https://aurral.example.com/outpost.goauthentik.io/sign_out`. This value ends the proxy session when you log out of Aurral. Aurral hides its Log out control while proxy authentication is on and this value is unset.
`AUTH_PROXY_DEFAULT_ROLE`	Role for proxy-auth users who do not otherwise have the admin role: `user` or `admin`. Aurral evaluates the role on every request.
`AUTH_PROXY_ADMIN_USERS`	Comma-separated usernames that get the admin role. Aurral checks the list on each request. If you remove a username, Aurral changes that user on the next request.
`AUTH_PROXY_ROLE_HEADER`	Optional header that contains the user’s group membership (for example, Authelia’s `Remote-Groups`). Usually, this is a comma-separated list. Aurral compares it with `AUTH_PROXY_ADMIN_GROUPS` on every request.
`AUTH_PROXY_ADMIN_GROUPS`	Comma-separated group names that give the admin role. Aurral compares these names with `AUTH_PROXY_ROLE_HEADER`. A group named `admin` has no special function unless you list it here.
`OIDC_ENABLED`	Enable native OpenID Connect login.
`OIDC_ISSUER`	Identity provider issuer URL used for OIDC discovery.
`OIDC_CLIENT_ID`	OIDC client ID.
`OIDC_CLIENT_SECRET`	OIDC client secret.
`OIDC_REDIRECT_URI`	Exact callback URL registered with your IdP. Must be `https://<your-aurral-host>/sso/callback`.
`OIDC_SCOPES`	Space-separated scopes. Default `openid profile email`.
`OIDC_USERNAME_CLAIM`	Claim used as the Aurral username. Default `preferred_username`. Falls back to `email` when that claim is missing.
`OIDC_DEFAULT_ROLE`	Role for OIDC users who are not otherwise granted admin: `user` or `admin`.
`OIDC_ADMIN_USERS`	Comma-separated usernames that get the admin role at OIDC login.
`OIDC_GROUPS_CLAIM`	Optional ID-token claim that contains group membership.
`OIDC_ADMIN_GROUPS`	Comma-separated group names that grant the admin role when present in `OIDC_GROUPS_CLAIM`.
`OIDC_LOGOUT_URL`	Optional IdP logout URL. When set, Aurral redirects there after clearing the local session.
`OIDC_DOMAIN`	Optional IdP origin added to the `connect-src` content security policy.
`SESSION_EXPIRY_HOURS`	Session lifetime in hours for password login, proxy auth, and native OIDC. Default `720` (30 days).

Logging

Variable	Purpose
`AURRAL_VERBOSE_LOGS`	Detailed server logs for problem analysis.

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.