Environment Variables Documentation

This document describes the environment variables used by the Synara API and Proxy, based on the application.yaml configuration.

Getting Started

You can define these variables in a .env file in the root of the project. An example file is provided in example.env.

Most variables have sensible defaults and are optional. Only variables without a default value in application.yaml (no : suffix) are strictly required to be provided by the environment.

Default Precedence

Environment Variables: Any variable set in your environment (or .env file) takes highest precedence.
Docker Defaults: If running via Docker, variables set in the Dockerfile override standalone defaults.
Standalone Defaults: The default values defined in application.yaml are used if no other value is provided.

Covers

Variable	Description	Required	Default (Standalone)	Default (Docker)
`COVER_AUTO_DEBOUNCE_SECONDS`	Seconds to wait after the last content change before regenerating a cover.	No	`30`	-
`COVER_AUTO_GENERATE`	Whether covers are generated automatically for playlists and collections without one.	No	`true`	-
`COVER_NSFW_PACKS_ENABLED`	Whether NSFW cover asset packs may be used when a request opts in.	No	`false`	-

Credential Server

Variable	Description	Required	Default (Standalone)	Default (Docker)
`CREDENTIAL_SERVER_ADMIN_KEY`	Admin key of the credential server. The credential server requires it as X-Admin-Key for its admin routes and answers 503 while it is unset. A Synara server uses the same variable to manage a connected credential server.	No	-	-
`CREDENTIAL_SERVER_CLIENT_ID`	Client id this Synara server uses to authenticate at the credential server.	No	-	-
`CREDENTIAL_SERVER_CLIENT_SECRET`	Client secret belonging to CREDENTIAL_SERVER_CLIENT_ID.	No	-	-
`CREDENTIAL_SERVER_DB_DRIVER`	JDBC driver of the credential server database. Use org.postgresql.Driver for PostgreSQL.	No	`org.sqlite.JDBC`	-
`CREDENTIAL_SERVER_DB_PASSWORD`	Database password of the credential server (PostgreSQL only).	No	-	-
`CREDENTIAL_SERVER_DB_URL`	JDBC URL of the credential server database.	No	`jdbc:sqlite:credentials.db`	-
`CREDENTIAL_SERVER_DB_USER`	Database user of the credential server (PostgreSQL only).	No	-	-
`CREDENTIAL_SERVER_ISSUER`	Issuer claim of the tokens signed by the credential server.	No	`synara-credentials`	-
`CREDENTIAL_SERVER_KEY_FILE`	Path of the generated master key file, used when no master key is set.	No	`master.key`	-
`CREDENTIAL_SERVER_MASTER_KEY`	Master key that encrypts the stored credentials and signing keys of the credential server. When empty, a key file is generated instead.	No	-	-
`CREDENTIAL_SERVER_PORT`	HTTP port of the credential server.	No	`8083`	-
`CREDENTIAL_SERVER_TOKEN_TTL_SECONDS`	Lifetime of the access tokens issued by the credential server in seconds.	No	`900`	-
`CREDENTIAL_SERVER_URL`	Base URL of a credential server this Synara server fetches third-party credentials from. Can also be set on the credential server settings page.	No	-	-

Database Configuration

Variable	Description	Required	Default (Standalone)	Default (Docker)
`BACKUP_DIR`	Directory for database backups.	No	-	`/backups`
`DB_DRIVER`	JDBC driver class name.	No	`org.sqlite.JDBC`	-
`DB_PASSWORD`	Database password.	No	-	-
`DB_URL`	JDBC connection URL.	No	`jdbc:sqlite:data.db`	-
`DB_USER`	Database username.	No	-	-
`SETUP_FROM_BACKUP`	Path to a backup file to initialize the server from (only if the database is empty).	No	-	-
`SETUP_FROM_MIRROR_PASSWORD`	Password for the remote server mirroring setup.	No	-	-
`SETUP_FROM_MIRROR_URL`	URL of another Synara server to initialize from (only if the database is empty).	No	-	-
`SETUP_FROM_MIRROR_USERNAME`	Username for the remote server mirroring setup.	No	-	-

External Services

Variable	Description	Required	Default (Standalone)	Default (Docker)
`ACOUSTID_API_KEY`	An AcoustID client API key used to identify songs without a MusicBrainz id by audio fingerprint. The Docker images set a default Synara key. Without a key, fingerprint matching is skipped. Overridable in the admin settings.	No	-	`Y2A24vXli6`
`APPLE_MUSIC_KEY_ID`	Apple Music Key ID.	No	-	-
`APPLE_MUSIC_P8_PATH`	Path to the Apple Music .p8 private key file.	No	-	-
`APPLE_MUSIC_STOREFRONT`	Apple Music storefront (country code) used for catalog requests.	No	`us`	-
`APPLE_MUSIC_TEAM_ID`	Apple Music Team ID.	No	-	-
`GAMDL_CODEC_SONG`	Optional gamdl song codec override (empty = gamdl default, e.g. aac-web). Advanced/version-sensitive.	No	-	-
`GAMDL_COOKIES_PATH`	Path to the Netscape cookies.txt for Apple Music (gamdl importer).	No	`cookies.txt`	-
`GAMDL_WVD_PATH`	Optional path to a Widevine .wvd device for higher-quality gamdl codecs.	No	-	-
`IMAGE_CACHE_TOKEN`	Image Cache auth token.	No	-	-
`IMAGE_CACHE_URL`	Image Cache service URL.	No	-	-
`LINKRESOLVER_API_KEY`	API key for the self-hosted LinkResolver service (linkresolver.synara.audio).	No	-	-
`LYRICS_PROVIDERS`	Comma separated online lyrics providers to ask, in order of preference. Known ids are betterlyrics, unison, lyricsplus, kugou, lrclib and youtubemusic. Empty asks no online provider and only reads lyrics files next to the songs.	No	`betterlyrics,unison,lyricsplus,kugou,lrclib,youtubemusic`	-
`PODCAST_INDEX_API_KEY`	Podcast Index (podcastindex.org) API key used to search podcast directories. Can also be stored through the admin settings card, which takes precedence.	No	-	-
`PODCAST_INDEX_API_SECRET`	Podcast Index API secret belonging to PODCAST_INDEX_API_KEY.	No	-	-
`SPOTIFY_CLIENT_ID`	Spotify API Client ID.	No	-	-
`SPOTIFY_CLIENT_SECRET`	Spotify API Client Secret.	No	-	-
`TIDAL_CLIENT_ID`	Tidal API Client ID.	No	-	-
`TIDAL_CLIENT_SECRET`	Tidal API Client Secret.	No	-	-
`TIDDL_AUTH`	Optional Tidal client for tiddl in the form client_id;client_secret, the same value tiddl reads. When set, the credential server page sends it for tiddl sessions whenever the client id and secret fields are blank.	No	-	-
`TRANSCRIBER_URL`	Transcriber service URL.	No	`http://localhost:8000`	-

General & Authentication

Variable	Description	Required	Default (Standalone)	Default (Docker)
`CLIENT_ID`	Initial admin username (only on first run).	No	-	-
`CLIENT_SECRET`	Initial admin password (only on first run).	No	-	-
`CREDENTIALS_ENCRYPTION_KEY`	Key that encrypts credentials stored through the admin settings, for example the Podcast Index and AcoustID keys. Generate one with `openssl rand -base64 32`. When unset, a random key is generated once into CREDENTIALS_KEY_FILE. Keep this value, or the key file, to read stored credentials after restoring a backup on another host.	No	-	-
`CREDENTIALS_KEY_FILE`	Key file used when CREDENTIALS_ENCRYPTION_KEY is unset. Defaults to `~/.config/synara/credentials.key` and is created on first start.	No	-	-
`JWT_AUDIENCE`	The audience claim for JWT tokens.	No	`synara-api`	-
`JWT_ISSUER`	The issuer claim for JWT tokens.	No	`synara`	-
`JWT_REALM`	The realm for JWT authentication.	No	`Access to 'Synara-API'`	-
`JWT_SECRET`	Secret key for signing tokens.	No	`changeme`	-
`PORT`	The port the server listens on.	No	`8080`	-

Metrics

Variable	Description	Required	Default (Standalone)	Default (Docker)
`METRICS_ENABLED`	Whether to collect RPC call usage metrics (invocation counts per call, per user, over time).	No	`true`	-
`METRICS_EVENT_LOG_RETENTION_HOURS`	How long (in hours) individual call events are retained in the capped event log before pruning. Lifetime totals are never pruned.	No	`24`	-
`METRICS_FLUSH_INTERVAL_SECONDS`	How often (in seconds) buffered in-memory call counts are flushed to the database.	No	`60`	-

Other

Variable	Description	Required	Default (Standalone)	Default (Docker)
`ENTITY_CHANGE_RETENTION_DAYS`	How long (in days) recorded library changes are kept for clients that ask what changed since their last pull. A client that was away longer reads everything again.	No	`30`	-
`SERVER_SSL_SUPPORTED`		No	`false`	-
`VERSION_GROUP_REBUILD_MAX_WAIT_SECONDS`	Longest time in seconds that album changes wait until the versions of an album are grouped again, even while further changes keep arriving. A value below VERSION_GROUP_REBUILD_QUIET_SECONDS counts as that value.	No	`5`	-
`VERSION_GROUP_REBUILD_QUIET_SECONDS`	Seconds without a further album change before the versions of an album are grouped again. A value below 1 counts as 1.	No	`1`	-
`WORKER_THREAD_MULTIPLIER`	Multiplier for background worker threads. Scales the number of parallel tasks relative to CPU cores.	No	`1.0`	-
`YOUTUBE_API_KEY`	Youtube API key for YouTube Data API v3 (Downloader).	No	-	-

Proxy Configuration

Variable	Description	Required	Default (Standalone)	Default (Docker)
`PROXY_CONTROL_PORT`	Port for the proxy control interface.	No	`8081`	-
`PROXY_HOSTNAME`	Public hostname of the proxy.	No	-	-
`PROXY_ID`	Unique identifier for this proxy.	No	-	-
`PROXY_KEY`	Authentication key for the proxy.	No	-	-
`PROXY_NAME`	Display name for this proxy instance.	No	-	-
`PROXY_SSL`	Whether to use SSL (true/false).	No	`false`	-

Recommendations

Variable	Description	Required	Default (Standalone)	Default (Docker)
`AUDIO_EMBED_URL`	URL of the audio embedding service (MusiCNN). Empty disables per-song audio embeddings.	No	-	-
`RECSYS_DATA_DIR`	Shared directory used to exchange training data with the recommendation (recsys) service. Empty disables recommendation training.	No	-	-

Redis Configuration

Variable	Description	Required	Default (Standalone)	Default (Docker)
`REDIS_CACHE_ANIMATED_IMAGES`	Whether to cache animated cover bytes in Redis.	No	`false`	-
`REDIS_HOST`	Redis server hostname.	No	-	-
`REDIS_INDEX_PREFIX`	Prefix for Redis Search indices.	No	`synara`	-
`REDIS_PORT`	Redis server port.	No	-	-
`REDIS_USE_SEARCH`	Whether to use RediSearch for ranked searching.	No	`false`	-

Storage & Paths

Variable	Description	Required	Default (Standalone)	Default (Docker)
`AUDIO_ALBUMS_PATH`	Base path for albums.	No	`music/albums`	`/data/Synara/Albums`
`AUDIO_AUTO_TRANSCODE_QUALITIES`	Bitrates for auto-transcoding (Opus).	No	-	-
`AUDIO_AUTO_TRANSCODE_QUALITIES_AAC`	Bitrates for auto-transcoding (AAC).	No	-	-
`AUDIO_CUSTOM_PATH`	Path for custom uploaded audio.	No	`music/custom`	`/data/Synara/custom`
`AUDIO_LOSSLESS_FORMAT`	Lossless container for audio the server produces (custom uploads, downloader imports): FLAC, WAV or AIFF.	No	`FLAC`	`FLAC`
`AUDIO_PLAYLISTS_PATH`	Base path for playlists.	No	`music/playlists`	`/data/Synara/Playlists`
`AUDIO_TRACKS_PATH`	Base path for audio tracks.	No	`music/tracks`	`/data/Synara/Tracks`
`AUDIO_TRACKS_SECONDARY_PATH`	Optional secondary audio path.	No	-	`/data/Synara/other`
`AUDIO_TRANSCODE_PATH`	Path for transcoded files.	No	`music/transcode`	`/data/Synara/Transcode`
`DATA_ANIMATED_IMAGES_PATH`	Path for cached animated covers.	No	`data/animated-images`	`/data/Synara/AnimatedImages`
`DATA_COVER_ASSETS_PATH`	Path containing cover asset packs (one directory with pack.json per pack).	No	`data/cover-assets`	`/app/cover-assets`
`DATA_IMAGES_PATH`	Path for cached images/covers.	No	`data/images`	`/data/Synara/Images`
`PODCASTS_IMPORTS_PATH`	Folder where episodes of IMPORT-mode feed subscriptions are stored (<showId>/<episodeId>.<ext>).	No	`podcasts/imports`	`/data/Synara/podcasts/imports`
`PODCASTS_LIBRARY_PATH`	Root folder of local podcast shows: one sub-folder per show, audio files inside become episodes.	No	`podcasts/library`	`/data/Synara/podcasts/library`
`YTDLP_CONFIG_PATH`	Path to yt-dlp.conf for yt-dlp.	No	-	`/data/config/yt-dlp.conf`