Skip to content

Configuration ​

docker-compose.yml configures the container through environment variables read from .env (copy .env.example to .env to start). Apply changes with docker compose up -d.

TIP

Variables marked seed initialize database settings that the owner can change later in Cockpit (/cockpit) or via the operator CLI. Once saved in Cockpit or the CLI, the database value takes precedence over .env.

Address and TLS ​

VariableTypeDefaultDescription
STELLARR_DOMAINhostname or IPemptyPublic hostname or IP used for the origin, TURN realm, and self-signed certificate SAN. Falls back to localhost when unset.
STELLARR_PUBLIC_PORTportSTELLARR_HTTPS_PORTExternal HTTPS port browsers connect to (443 behind a reverse proxy). Omitted from URLs when 443.
PUBLIC_IPIPv4 or autoemptyPublic IPv4 advertised by coturn and stellarr-media. Required for voice from outside the Docker host; auto resolves STELLARR_DOMAIN's A record on startup.
STELLARR_HTTPS_PORTport (1–65535)8443Host port mapped to container 443/tcp.
STELLARR_HTTP_PORTport or ip:port8888Host port mapped to container 80/tcp (HTTP-to-HTTPS redirect only). Prefix with 127.0.0.1: when using a local reverse proxy.
STELLARR_PUBLIC_URLorigin URLemptyExplicit http or https origin (no credentials, query, or fragment), overriding STELLARR_DOMAIN + STELLARR_PUBLIC_PORT.
STELLARR_TRUSTED_PROXIESIP / CIDR listemptyComma- or space-separated IPv4/IPv6 addresses or CIDRs of trusted reverse proxies.
STELLARR_VERSIONimage taglatestImage tag for ghcr.io/arkazzae/stellarr (pin 1.2 or 1.2.3 for production).

Notes:

  • Self-signed vs. custom certificates: When /data/stellarr/tls/fullchain.pem or privkey.pem is missing, the container generates a self-signed certificate and renews it if STELLARR_DOMAIN changes or <30 days remain. Custom CA-signed certificates are never overwritten; see Reverse proxy and TLS.
  • Public origin behavior: STELLARR_PUBLIC_URL (or the URL built from STELLARR_DOMAIN + STELLARR_PUBLIC_PORT) is used for password-reset and email-change links, invite links, /.well-known/stellarr/client, and passkey Relying Party validation. When both STELLARR_DOMAIN and STELLARR_PUBLIC_URL are unset, password-reset emails remain disabled.
  • Trusted proxies: Listing a proxy tells the API to read real client IPs from X-Forwarded-For for rate limits, sessions, security events, and trusted devices. Invalid entries (hostnames, non-zero host bits such as 10.0.0.1/24, or 0.0.0.0/0) abort API startup.

Voice and RTC ​

VariableTypeDefaultDescription
STELLARR_MEDIA_PORTport (1–65535)49000Host UDP port for Stellarr Media; carries every call and must match the external router port.
STELLARR_TURN_PORTport (1–65535)3478Published host port and advertised port for STUN/TURN (udp and tcp).
STELLARR_TURNS_PORTport (1–65535)5349Published host port and advertised port for TURN over TLS/DTLS.
STELLARR_TURN_TCP_ENABLEDtrue | falsefalseEnables the TURN/TCP listener in coturn and advertises ?transport=tcp ICE URLs.
STELLARR_TURNS_ENABLEDtrue | falsefalseEnables TURN over TLS/DTLS (turns:). Requires a browser-trusted TLS certificate.
STELLARR_TURN_RELAY_RANGEport range49160-49200Host UDP ports mapped 1:1 to container 49160-49200/udp for TURN media relays.

See RTC and ports for relay sizing and firewall rules.

Uploads and quotas ​

Byte limits accept 0 (or negative values) to disable the quota check.

VariableTypeDefaultDescription
STELLARR_UPLOAD_USER_BYTESbytes2147483648 (2 GiB)Per-account storage quota.
STELLARR_UPLOAD_TOTAL_BYTESbytes21474836480 (20 GiB)Instance-wide storage quota.
STELLARR_MIN_FREE_BYTESbytes1073741824 (1 GiB)Minimum free disk space required on /data/stellarr to accept an upload (0 disables).
STELLARR_MAX_CONCURRENT_UPLOADSinteger (1–32)4Maximum concurrent uploads across the instance.

Per-file limits by media type: images 10 MiB, audio 25 MiB, documents/other 25 MiB, video 100 MiB. Nginx enforces a 128 MiB maximum request body size.

Mail ​

Password-reset, invitation, security alert, and activity notification emails use SMTP by default. Configure the SMTP host, port, encryption (STARTTLS, TLS, or none), and username in Cockpit under Settings, or enable Resend under Integrations.

NOTE

Secrets saved in Cockpit (SMTP password, Resend API key) are encrypted with the instance's data-protection keys, override .env, and are never returned to the browser. Clearing a secret in Cockpit falls back to the environment variable.

VariableTypeDefaultDescription
STELLARR_MAIL_ENABLEDtrue | falsetrueSeed for the mailing toggle in Cockpit settings.
STELLARR_SMTP_PASSWORDstringemptySMTP password fallback when none is stored in Cockpit.
STELLARR_RESEND_API_KEYstringemptyResend API key fallback when none is stored in Cockpit.
STELLARR_MAIL_FROMemailemptySeed for the sender address (onboarding@resend.dev works only via Resend testing).
STELLARR_MAIL_FROM_NAMEstringStellarrSender display name.

Web Push ​

Optional browser push notifications for mentions and direct messages. See Activity notifications for generating a persistent VAPID key pair.

VariableTypeDefaultDescription
STELLARR_PUSH_ENABLEDtrue | falsefalseEnables Web Push when a valid VAPID key pair and subject are configured.
STELLARR_PUSH_SUBJECTmailto: or https:// URIemptyOperator contact URI presented to push services (for example, mailto:admin@example.com).
STELLARR_PUSH_PUBLIC_KEYbase64url stringemptyUncompressed P-256 VAPID public key (65 bytes decoded).
STELLARR_PUSH_PRIVATE_KEYbase64url stringemptyP-256 VAPID private key (32 bytes decoded). Treat as a secret.

Single sign-on (OIDC) ​

OpenID Connect sign-in is optional; local username/password sign-in remains available. The callback URL is <public-url>/api/auth/oidc/callback.

VariableTypeDefaultDescription
STELLARR_OIDC_ENABLEDtrue | falsefalseEnables the primary OIDC provider (requires issuer, client ID, and client secret).
STELLARR_OIDC_ISSUERHTTPS URLemptyOIDC provider issuer URL.
STELLARR_OIDC_CLIENT_IDstringemptyOIDC client ID.
STELLARR_OIDC_CLIENT_SECRETstringemptyOIDC client secret (takes precedence over STELLARR_OIDC_CLIENT_SECRET_FILE).
STELLARR_OIDC_CLIENT_SECRET_FILEcontainer pathemptyPath to a mounted file containing the OIDC client secret.
STELLARR_OIDC_DISPLAY_NAMEstringMain accountSign-in button label on the login screen.
STELLARR_OIDC_TRUST_PROVIDER_MFAtrue | falsefalseCounts a provider login confirmed with a matching amr claim as Stellarr's second step.
STELLARR_OIDC_PROVIDER_MFA_AMRcomma-separated listmfaamr claim values treated as provider MFA when STELLARR_OIDC_TRUST_PROVIDER_MFA=true.

Additional OIDC providers ​

You can configure extra OIDC providers in docker-compose.override.yml under environment, keyed by a provider ID of 1–32 lowercase letters, digits, or hyphens (excluding default, login, and callback). Each provider gets its own login button and callback URL <public-url>/api/auth/oidc/<id>/callback:

yaml
services:
  stellarr:
    environment:
      Oidc__Providers__work__DisplayName: Work account
      Oidc__Providers__work__Authority: https://id.example.com/realms/work
      Oidc__Providers__work__ClientId: stellarr
      Oidc__Providers__work__ClientSecretFile: /run/secrets/oidc-work
      # Optional, off by default:
      Oidc__Providers__work__TrustProviderMfa: "true"
      Oidc__Providers__work__ProviderMfaAmr: mfa,hwk
  • A provider is enabled only when its issuer is HTTPS and both client ID and secret are configured; an invalid provider ID stops the API at startup.
  • Users link their accounts to a provider from Settings → Login and security → Sign-in providers (see Account security). Identities are matched strictly by (issuer, subject), never by email address.

Trusting provider MFA ​

By default, an OIDC sign-in still prompts for Stellarr's own second step if MFA is active on the account or instance policy. Enabling TrustProviderMfa allows the provider's own MFA check to satisfy Stellarr's second step (including Cockpit):

  • The provider's ID token must contain one of the configured amr values and an auth_time within the last 5 minutes (Stellarr sends max_age=300 when re-authenticating).
  • If auth_time is missing or stale, Stellarr falls back to its own second-step prompt. Enable this only for providers that enforce a real second factor and report it accurately in amr.

Automatic backups and Cloudflare R2 ​

Production Docker Compose enables daily automatic full backups by default. Schedule settings can be overridden at runtime in Cockpit → Backups → Backup settings; see Automatic backups and Cloudflare R2 offsite backups.

Backup schedule ​

VariableTypeDefaultDescription
STELLARR_BACKUP_ENABLEDtrue | falsetrueSeed enabling automatic full backups.
STELLARR_BACKUP_INTERVAL_HOURSinteger24Hours between completed backup cycles.
STELLARR_BACKUP_RETRY_MINUTESinteger15Delay before retrying a failed offsite upload.
STELLARR_BACKUP_INITIAL_DELAY_MINUTESinteger5Delay after container startup before the first scheduled backup runs.

Cloudflare R2 integration ​

VariableTypeDefaultDescription
STELLARR_CLOUDFLARE_R2_ENABLEDtrue | falsefalseEnables uploading completed backups to Cloudflare R2.
STELLARR_CLOUDFLARE_R2_MODEs3 | workers3Upload mode: direct S3 API (s3) or Backup Relay Worker (worker).
STELLARR_CLOUDFLARE_R2_ENDPOINTHTTPS URLemptyR2 S3 endpoint (https://<ACCOUNT_ID>.r2.cloudflarestorage.com) or Worker URL.
STELLARR_CLOUDFLARE_R2_REGIONstringautoR2 region (s3 mode).
STELLARR_CLOUDFLARE_R2_BUCKETstringemptyPrivate R2 bucket name (s3 mode).
STELLARR_CLOUDFLARE_R2_ACCESS_KEYstringemptyR2 S3 access key ID (s3 mode).
STELLARR_CLOUDFLARE_R2_SECRET_KEYstringemptyR2 S3 secret access key (s3 mode).
STELLARR_CLOUDFLARE_R2_WORKER_TOKENstringemptyBearer token for the Backup Relay Worker (worker mode).
STELLARR_CLOUDFLARE_R2_PREFIXstringstellarrObject key prefix inside the bucket.

Language ​

VariableTypeDefaultDescription
STELLARR_LANGUAGEen | plenDefault web client locale (for users without a saved browser preference) and API language for error messages, system messages, default server/role/channel names, audit entries, and emails.

Unknown values abort API startup. Existing database records keep the language in which they were created. Browsers cache /stellarr-instance.js for up to one hour, so a changed default may take up to an hour to reach existing tabs. See Localization.

Instance identity and desktop handshake ​

VariableTypeDefaultDescription
STELLARR_INSTANCE_IDUUIDgeneratedPersistent instance UUID reported at /.well-known/stellarr/client (auto-generated in /data/stellarr/instance-id when unset).
STELLARR_INSTANCE_NAMEstringStellarrInstance name reported before the primary server exists (afterward, uses the primary server's name; editable in Cockpit).
STELLARR_TIME_ZONEIANA time zoneUTCSeed for the instance time zone in Cockpit settings (for example, Europe/Warsaw).
STELLARR_DESKTOP_MINIMUM_VERSIONsemver0.1.0Minimum allowed desktop client version; older clients are rejected by the client gate.
STELLARR_DESKTOP_RECOMMENDED_VERSIONsemver0.1.3Recommended desktop client version advertised in /.well-known/stellarr/client.

Other settings ​

VariableTypeDefaultDescription
GIPHY_API_KEYstringemptyGIPHY key for GIF search. Sent to signed-in browsers (unless disabled in user privacy settings); can also be set and tested in Cockpit → Integrations, which takes precedence without a restart.
STELLARR_EF_COMMAND_LOG_LEVEL.NET log levelWarningLog level for Microsoft.EntityFrameworkCore.Database.Command (Information logs SQL queries).

Logs ​

The API writes logs to container stdout/stderr (docker compose logs) and to Cockpit's Logs view (which retains the latest 10,000 lines in memory). By default it logs:

  • Warnings and errors from all components
  • One summary line per API request (POST /api/channels/…/messages 201 in 12 ms under Stellarr.Api.Requests), excluding routine container health checks
  • Operational lifecycle events (startup, media server resets, backups, maintenance)
  • The setup code for the owner account, at each start while the instance has no account, as a warning so that it shows even with the log set to Warning

Framework HTTP diagnostics (Microsoft.AspNetCore), Entity Framework SQL (Microsoft.EntityFrameworkCore.Database.Command), and outgoing HTTP client calls default to Warning and above. Override any category in docker-compose.override.yml:

yaml
services:
  stellarr:
    environment:
      Logging__LogLevel__Microsoft.AspNetCore: Information
      Logging__LogLevel__Stellarr.Api.Requests: Warning

Container resource limits ​

VariableTypeDefaultDescription
STELLARR_CONTAINER_MEMORY_LIMITsize4gContainer memory limit (mem_limit).
STELLARR_CONTAINER_CPUSnumber4Container CPU quota (cpus).
STELLARR_CONTAINER_PIDS_LIMITinteger512Container process limit (pids_limit).

Advanced container environment variables ​

The container entrypoint and TLS maintenance scripts also read the variables below. Set them in docker-compose.override.yml when needed.

VariableDefaultDescription
STELLARR_DATA_ROOT/data/stellarrRoot directory for persistent state inside the container.
TLS_RENEW_BEFORE_SECONDS2592000 (30 days)Renew managed self-signed certificates when remaining validity falls below this threshold or when STELLARR_DOMAIN changes.
TLS_RENEW_CHECK_SECONDS43200 (12 hours)Interval between self-signed certificate renewal checks.
STELLARR_MEDIA_ADVERTISEemptyComma-separated ip:port list overriding the derived stellarr-media ICE host candidates.
STELLARR_MEDIA_LOGinfotracing filter for stellarr-media (for example, info,stellarr_media=debug).
STELLARR_MEDIA_CONTROL_SECRET/data/stellarr/secrets/media-control-secretOverrides the shared bearer secret between the API and stellarr-media.
TURN_SHARED_SECRET/data/stellarr/secrets/turn-shared-secretOverrides the shared HMAC secret between the API and coturn.

IMPORTANT

On first start, generated secrets are written to /data/stellarr/secrets/. Always include them when backing up /data/stellarr.

Development stack (docker-compose.dev.yml) ​

docker-compose.dev.yml runs each service from bind mounts with live reload (STELLARR_TIME_ZONE defaults to Europe/Warsaw and STELLARR_INSTANCE_NAME to Stellarr Dev).

VariableDefaultDescription
STELLARR_DEV_WEB_PORT3000Host port for Vite's dev server serving both the web client and Cockpit (/cockpit).
STELLARR_DEV_API_PORT5000Host port for the ASP.NET Core API (dotnet watch).
STELLARR_DEV_MEDIA_PORT49100Host UDP port for stellarr-media (advertised on 127.0.0.1).
STELLARR_DEV_MEDIA_CONTROL_PORT5200Host loopback TCP port (127.0.0.1:5200) for the stellarr-media control API.
STELLARR_DEV_ALLOWED_HOSTSemptyComma-separated extra hostnames allowed by Vite's dev server (localhost and IPs are always allowed).
STELLARR_API_ORIGINhttp://127.0.0.1:5000Upstream API origin proxied by Vite for /api, /assets, /health, /hubs, and /.well-known/stellarr/client (http://api:5000 in Compose).
STELLARR_DEV_POLLINGtrueEnables filesystem polling in Vite when file-watch events do not cross bind mounts.

Running without Docker Compose ​

docker-compose.yml maps friendly STELLARR_* variables from .env to the container's internal environment names. When running plain docker run or a custom platform template (such as Unraid):

  • Persistent volume: Mount a volume or host directory at /data/stellarr.
  • Stop timeout: Pass --stop-timeout=75 so stellarr-init has time to shut down services gracefully (Docker's 10-second default cuts shutdown short).
  • Language: Set both STELLARR_LANGUAGE (web client) and Stellarr__Language (API) to en or pl.
  • Port mappings and advertised variables: A container cannot inspect host port mappings, so set these container variables to match your published host ports:
PurposeContainer portDefault host portContainer variableCompose .env variable
HTTPS443/tcp8443PUBLIC_HTTPS_PORTSTELLARR_HTTPS_PORT
Voice media49000/udp49000Rtc__MediaPortSTELLARR_MEDIA_PORT
TURN3478/udp, 3478/tcp3478Rtc__TurnPortSTELLARR_TURN_PORT
TURNS5349/tcp, 5349/udp5349Rtc__TurnsPortSTELLARR_TURNS_PORT

The HTTP redirect (80/tcp, default host 8888) needs no container variable, and the TURN relay range (49160-49200/udp) must map 1:1 with the same port numbers on host and container. For all other optional variables, inspect docker-compose.yml to see the underlying container key name.