Configuration¶

Environment variables configure service connections, paths, secrets and optional integrations. Symfony's configuration reads those values when the application starts. The source installation uses private web settings and a separate worker credentials file; changing one does not update the other.

Behavior that an administrator may want to change while the server runs, such as whether audio is transcoded or which language emails default to, is kept in the database instead, as server settings.

Where a change takes effect¶

For the source-installation web environment, Symfony reads .env, .env.local, .env.dev and .env.dev.local in that order; existing process environment values win. The tracked .env.dev has development defaults, including an application secret, so put private overrides in .env.dev.local as shown in Getting started. A prod process selects its corresponding environment files instead. Do not put secrets in files copied into an image.

Compose's --env-file options configure Compose interpolation separately from Symfony's environment loading. The installation's dc function names both the private settings and generated image-selection file. Use that function for its commands; Make targets the development preview. See Command context.

The worker pair runs with APP_ENV=prod. It does not read the web's .env.dev.local. Its admitted credentials allow a restricted set of runtime keys; other values, including encoder selection, must be configured in the image as described by the worker and transcoding guides. Web, workers and host controller must reach the same main database through addresses appropriate to their networks. Web and workers must also agree on shared media paths and Redis transport settings. See Shared media paths.

Application¶

The application name is fixed as Bånder. Environment variables cannot change the name shown in emails, passkey prompts or TOTP enrollment.

Database¶

The test database uses baander_test as the database name — configured in .env.test.

Redis¶

Redis is used for:

• Cache — tag-aware caching for API responses, OAuth tokens, and user sessions
• Messenger — async job transport (scan jobs, notification delivery)
• Rate limiting — limiter state for API requests, for login, passkey, registration, password reset and token refresh attempts, and for the OAuth authorization server endpoints
• DPoP stores — the single-use nonces of the token endpoints and the proof identifiers seen on API requests (replay protection)

Redis connections from the application pool and Doctrine cache pools have one-second connect and read timeouts. A request can make several Redis calls, so these are per-connection bounds rather than a one-second total request deadline. Rate limiters use the pooled client directly, with atomic state in separate namespaces; they do not use cache pools. Unavailable rate-limit state answers 503 with Retry-After: 1; unavailable DPoP state answers 503 with Retry-After: 5. Both carry Cache-Control: no-store, and the first rejecting check determines the response. Clients keep their sessions. See Sessions and a Redis outage for the narrow logout/revocation exceptions.

Messenger¶

Worker deployments accept a single redis:// or rediss:// endpoint in each URL, including percent-encoded credentials and bracketed IPv6 hosts. A host is required; percent escapes in hosts and port zero are rejected. URLs cannot contain fragments, ASCII whitespace or control characters, commas, backslashes, malformed percent escapes or multiple unescaped @ separators. REDIS_URL must have no path or query. MESSENGER_TRANSPORT_DSN may carry unique scalar query options: stream=messages, group=baander, non-negative integer dbindex and retry_interval, or finite non-negative decimal timeout and read_timeout. Integer values use 0 or digits without leading zeroes; decimal values may add a fraction to that form. Unknown options, duplicates and nested option names are rejected. Consumer overrides are rejected, including a consumer path segment.

Credential admission rejects invalid URLs before Docker creation. The supervisor checks again before launching children; diagnostics identify the setting without printing its credential-bearing value. These checks preserve the configured streams, group and generated identity. They do not test endpoint connectivity.

The validated workload catalog in config/packages/messenger.php supplies fifteen default production routes and two explicit-only workloads: lyrics fetch and webhook delivery. Container compilation checks routes, handlers, codecs, JSON serialization and bounded retry policies; producer dispatch checks the selected senders. Execution runs ordinary consumers for async and a separate consumer for scheduler. See Background work for how queues, the outbox and scheduled work reach those consumers. Resource classes io, cpu and coordination describe work and do not change worker reservations. The test environment configures both receivers as in-memory:// in that file; changing a production worker DSN to in-memory:// is rejected.

Both async and scheduler configure max_retries: 3, delay: 1000 milliseconds, multiplier: 2 and max_delay: 60000 milliseconds. Symfony recoverable exceptions can bypass the retry count and supply their own retry delay. These values bound the configured retry policy; they do not impose an unconditional execution cap.

OAuth 2.0¶

Provision the RSA key files outside the image and set the two key-path variables to readable paths inside the web container. The default paths resolve relative to the project directory. Keep the private key readable only by the application user; production images contain no OAuth keys.

Token lifetimes¶

These are configured as parameters in config/packages/auth.yaml and can be overridden per-environment:

Authorization server¶

Clients other than Baander's own apps obtain tokens through the authorization code grant, the device authorization grant, and the refresh token grant. These parameters are also in config/packages/auth.yaml:

The issuer is APP_URL. app:auth:setup-clients creates only the first-party client; administrators register device, public and confidential clients with the app:oauth:client:* commands or the admin API (see OAuth Clients).

Web Push (VAPID)¶

Mail¶

config/packages/mailer.yaml builds the From header with the fixed name Bånder and the address from MAIL_FROM_ADDRESS. Mail servers often reject a sender address whose domain they cannot verify, so use an address at a domain your SMTP provider is allowed to send for. The test environment replaces MAILER_DSN with null://null, so tests never send real mail.

External APIs¶

API keys are optional. MusicBrainz and LRCLIB lookups work without them; other providers need credentials in the process that makes the request.

The MusicBrainz adapter sends a fixed application user agent. Changing the two MusicBrainz environment values above does not change it. See External APIs for provider behavior and limits.

Security¶

Rate limiting¶

Limits are set in config/packages/auth.yaml. They feed the Symfony policies in config/packages/framework.yaml; all 19 configured limiters consume state through atomic Redis compare-and-set. Each limiter has its own namespace, so the admin Rate Limits tab and app:rate-limiter:clear reset its generation without changing other limiters. The catalog reports storageNamespace, not a cache pool. Changing a limiter's effective configuration starts fresh subject budgets; it does not carry a shared budget across different configurations during a rolling change. See Rate Limiter Monitor.

Each limiter counts requests per key:

The last three have fixed limits in config/packages/framework.yaml and no auth.yaml parameter.

A request over a limit gets 429 Too Many Requests with a Retry-After header in seconds. The password reset account limit and the verification resend user limit are the exceptions. Over the reset account limit, the endpoint returns the same 200 response as for any other address but issues no reset token, so the response never shows whether an account exists. Over the resend user limit, the endpoint returns its usual 200 response but sends no email. The per-IP reset and verification limits still answer 429.

Media delivery routes are exempt from anonymous_api and authenticated_api, so playback is never throttled by the general API budget: the audio stream (/api/stream/track), the HLS and DASH manifests and segments under /api/transcode/{id}/ (master.m3u8, media.m3u8, manifest.mpd, init, segment), subtitle playlists and segments, image files (/api/images/{id}/file) and album covers (GET /api/albums/{id}/cover). Health, readiness and metrics endpoints (/health, /ready, /live, /metrics) are outside /api and are never limited.

With APP_ENV=dev, only the config_check, auth_password_reset_email and auth_email_verification_user limits apply; the others are skipped.

Both HTTP layers read TRUSTED_PROXIES, a comma-separated list of trusted proxy addresses or CIDRs that defaults to empty. With that default, a direct client cannot select a rate-limit identity by supplying X-Forwarded-For. Behind nginx or another proxy, configure only its actual source addresses or deliberately restricted CIDRs and make that proxy replace incoming forwarding headers. Otherwise clients share the proxy's address and its anonymous budget. Do not enable broad subnet trust merely because the service runs in Docker. See Request identity and proxy deployment.

Passkeys (WebAuthn)¶

Configured in config/packages/auth.yaml:

Passwords (Argon2id)¶

Password reset¶

A user has at most one outstanding reset token; a new request replaces it. The token is removed when it is redeemed, when the account is deleted, and when the account's email address or password changes. Baander stores only a SHA-256 hash of the token.

Self-service reset needs working email. When a user asks for a reset on the web login page, POST /api/auth/password/reset-request issues a token for an existing account and emails a link through MAILER_DSN (see Mail). The link opens APP_URL/reset-password, so APP_URL must be the address users reach the web app at. The token sits in the link's fragment (#token=…); browsers do not send fragments to the server, so the token stays out of access logs and Referer headers. The email states the link's lifetime from PASSWORD_RESET_EXPIRE.

Baander sends the email after the HTTP response has gone out, so the request takes as long for an unknown address as for a real account. A failed send does not change the response either. Baander logs the failure with the user ID but without the token or the address, and does not retry; the user can ask for a new link. The email is written in the user's email language, which Baander looks up when it sends the email, after the response.

Without working email, reset a forgotten password with app:user:reset-password or from the admin panel.

A password change revokes the sessions that the old password started. Redeeming a reset token, an administrator reset and app:user:reset-password revoke all of the user's access and refresh tokens. When users change their own password, the session that made the change stays signed in and their other sessions are revoked.

Email verification¶

Verification confirms that the user owns the account's email address. Until it does, Baander sends the account no notification email. Operator-created accounts start verified; every other account needs working email to verify (see Mail).

Baander emails a verification link when a user registers and whenever an email address changes, whether the user changes it, an administrator changes it in the admin panel, or an operator runs app:user:change-email. A changed address starts unverified. The link opens APP_URL/verify-email, so APP_URL must be the address users reach the web app at. As with password reset, the token sits in the link's fragment (#token=…) and stays out of access logs and Referer headers. A signed-in user whose address is unverified can ask for a new link in Settings, which calls POST /api/auth/me/email/verification. That endpoint answers the same way whether or not it sent an email.

A user has at most one outstanding verification token; a new link replaces it. A token verifies only the address it was sent to. It is removed when it is redeemed, when the account is deleted, and when the account's email address changes, so a link sent to an old address stops working. Baander stores only a SHA-256 hash of the token, with the address.

Baander sends the email after the HTTP response has gone out, or at once when the change comes from the command line. A failed send never fails the registration or email change that caused it. Baander logs the failure with the user ID but without the token or the address, and does not retry; the user can ask for a new link. Like the reset email, the verification email is written in the user's email language.

Token binding¶

Constrains how many distinct IPs a single token can bind to, to detect token theft and sharing.

Server¶

Swoole¶

Configured in config/packages/swoole.yaml:

Swoole's max_wait_time is not set in this file. When the server starts, it derives the whole drain budget from the deadline D, WEB_DRAIN_SECONDS:

• the drain window, during which requests finish and clients are told to reconnect, is floor((D - 4) / 2): 13 seconds at the default of 30;
• max_wait_time is floor((D - 4 - window) / 2): 6 seconds at the default. After the window, Swoole stops the HTTP workers. The formula retains room for two Swoole stop phases;
• 4 seconds remain reserved as shutdown margin. Web starts no CPU process pool; encoders belong to the independent worker deployment.

The window, twice max_wait_time and those 4 seconds never add up to more than D.

The startup table of app:serve shows the derived max_wait_time, and the line the server logs when a drain starts names the deadline, the window and max_wait_time.

Coroutine file I/O¶

The image builds Swoole 6.2 with its asynchronous thread backend for coroutine file I/O. An io_uring-enabled build cannot read coroutine files under Docker's default seccomp profile, and this Swoole version has no supported runtime INI switch to select another backend. Rebuild the image with the shipped flags; changing PHP INI or relaxing the worker's security profile is not the deployment recipe.

Web configures aio_core_worker_num: 1 and aio_worker_num: 4. Each private media job sets both limits to 1 before its helper forks or a reactor starts. These finite thread limits apply independently of the host CPU count. Include the AIO and encoder threads in container PID accounting.

PHP memory limit¶

The production image sets memory_limit to 512M in /usr/local/etc/php/conf.d/zz-baander-production-memory.ini. Every PHP process in the image reads it: the web server, the app:health:check HEALTHCHECK and console commands. The web server's memory check measures each HTTP worker against this limit. The worker supervisor (app:worker) sets its children's limits itself with -d. To change the limit, override the file or add a later one in conf.d.

Library Scanner Security¶

Limits applied when scanning media libraries, to prevent path traversal, oversized files, and metadata-based attacks. All variables use the SCANNER_ prefix.

Local Network Discovery¶

Media Storage & Tools¶

Stream Authentication¶

HTTP¶

API routes accept cross-origin requests only from the origin in APP_URL. Four paths allow any origin: /.well-known/, which serves the public JWKS keys and the OAuth authorization server metadata; POST /api/oauth/token and POST /api/oauth/device/authorize, which third-party and device clients call with a DPoP proof rather than cookies; and /api/discovery/, whose endpoints still require authentication. The authorization endpoint /api/oauth/authorize, token revocation, and device verification and approval follow the APP_URL rule, because only the web app's consent and device pages call them for the signed-in user. Third-party clients never call /api/oauth/authorize themselves: they send the user's browser to the consent page. The policy is set in config/packages/nelmio_cors.yaml; no environment variable changes it.

Job Monitoring¶

Server Settings¶

A server setting is a named value in the system_settings table that an administrator can change while Baander runs. The part of Baander that uses a setting also defines it: its key, its value type, the values it allows and its default. A setting nobody has changed has no row and takes its default. Baander reads a setting each time it acts on it, so a change applies to the next request, message or scheduled run without a restart, including in workers that are already running.

Changing a setting¶

The admin panel, the CLI and the API change settings through the same validation:

• Admin panel. Admin → Settings (/admin/settings) lists every server setting by group, with a switch, select or number input and a Reset button for each. A setting the server does not act on yet carries a Not yet enforced badge. Super administrators can change settings; other administrators see the page read-only, and the admin sidebar links to it only for super administrators.
• CLI. app:settings:list, get, set and reset.
• API. The endpoints below.

PATCH checks every key before it writes any. An unknown key or a value its setting does not allow rejects the whole request with 422 and a message for each failing key, and nothing is saved. A malformed body gets 400. DELETE on an unknown key gets 404.

A stored value can stop being allowed, for example when a setting's allowed values change in a new release. Baander then uses the default; the API reports the stored value with storedValueValid: false, and the CLI marks it (invalid). Setting or resetting the setting replaces it.

Settings reference¶

Every setting in the table is enforced. Four features arrived with server settings and start switched off: audio transcoding, metadata sync for new albums, lyrics fetch for new tracks, and scheduled recommendations. Turn on the ones you want.

Scheduled recommendations¶

A fresh install has an active scheduled job, Generate recommendations, that runs every day at 04:00 UTC in incremental mode, which recomputes recommendations for songs updated in the last seven days. Each run reads recommendations.auto_generate when it fires. While the setting is off, the run generates nothing, logs that it was skipped, and records skipped: recommendations.auto_generate is off as the job's last result.

The setting governs only that job. app:recommendation:generate, the admin action and schedules an administrator creates always generate.

You can change the job's schedule, pause it, or switch it to full mode in the scheduler admin. A full run loads every song and the listening history of every user, and it runs inside the scheduler worker, whose memory is limited (the worker deployment manifest requires a reservation of at least 320 MiB for it). On a large library it may run out of memory or time, which is why the seeded job is incremental.

Email language¶

Baander writes emails in English, Danish or Thai. It picks the language of each email when it sends it:

1. the user's own choice, while Baander still offers that language;
2. otherwise the server default, i18n.default_language, while Baander still offers it;
3. otherwise English.

Users choose under Language in the Account section of Settings. The first option, for example Server default (Dansk), names the current server default; choosing it removes the user's choice, so the user follows the default when an administrator changes it later. Administrators set a user's language in the admin user dialog, and operators with app:user:setting; see User settings.

At registration Baander reads the browser's Accept-Language header and takes the supported language the browser ranks highest. It ignores * and entries with q=0, and maps a regional tag such as da-DK to da. It stores that language as the user's choice only when it differs from the server default: most browsers ask for English, and storing it would tie those users to English after an administrator changes the default. Accounts created by an operator or administrator store no language and follow the server default until one is set for them.

The same choice sets the language of the messages the API returns, such as errors. A signed-in user with a saved choice gets messages in that language. Without a choice, and for requests that are not signed in, the API follows the request's Accept-Language header, then falls back to English; the server default applies to emails only.

The language applies to these emails:

• Password reset and email verification. Baander looks up the language when it sends the email: after the HTTP response, or at once when the email comes from a console command. If the lookup fails, the email goes out in English and the failure is logged without the address or the link.
• Notification emails. The worker looks up the language when it sends each email, so a change made after the notification was queued, such as a new server default, applies to it.

In-app notifications, push notifications and webhook payloads are always in English.

Each language must have a translation of every authentication and notification message before Baander can offer it. The Shared kernel guide describes how a language is added.

User settings¶

A user setting is a per-user value with the same kind of definition as a server setting. The user_settings table holds a row only for an explicit choice; a user without one gets the setting's default, or, for a setting that follows a server setting, that server setting's current value. language is currently the only user setting, and it follows i18n.default_language.

Signed-in users read and change their own settings through these endpoints:

An unknown key gets 404, a setting the user may not change gets 403, and an invalid value gets 422 and stores nothing. Users never read server settings directly; the value after a reset is how the Language control learns the current server default. A stored choice that is no longer allowed is presented to the user as no choice.

Administrators read and change a user's settings through the admin API and the CLI; see User settings.

Protect configuration¶

• Keep deployment credentials out of Git and image build contexts. The source installation uses .env.dev.local; the worker credentials file has its own ownership and mode requirements in the worker deployment reference.
• All env vars in .env can be overridden by setting real environment variables in your container runtime (Docker Compose, Kubernetes, etc.).
• For each deployment, generate a unique APP_SECRET with php -r 'echo bin2hex(random_bytes(32));'.
• OAuth keys should be at least 2048-bit RSA. Generate with openssl genrsa -out private.key 2048 and openssl rsa -in private.key -pubout > public.key.
• Rate limiting requires Redis. Unavailable state stops protected work with 503; logout and revocation retain the narrow availability exceptions described above.