sonda/docs/configuration.md
tgiachi 11077f40e1
All checks were successful
release / release (push) Successful in 36s
release / base (push) Has been skipped
release / image (amd64) (push) Has been skipped
release / image (arm64) (push) Has been skipped
release / manifest (push) Has been skipped
docs: split the README into pages under docs/
The README had grown to about 500 lines. It now holds the intro, a quick
start and an index, and the rest lives in docs/.

- docs: add docs/README.md as the index of all pages
- docs: move install, configuration, demo, providers, OpenSubsonic, API,
  security and backups, web app, Android app and development/releases
  to their own pages, text unchanged
- docs: split the feature list into five pages under docs/features/
- docs: rewrite internal anchors as links between the new pages
- chore: add docs to .dockerignore, next to README.md
2026-11-17 14:50:52 +01:00

3.5 KiB

Configuration

Docs · Sonda

Sonda reads ./sonda.toml, or the file given with --config. Every key has a default except the secret.

cp sonda.example.toml sonda.toml
# Put a random secret in it (32 characters or more). Edit the file by hand if your sed differs.
sed -i "s|^jwt_secret = .*|jwt_secret = \"$(openssl rand -hex 32)\"|" sonda.toml

sonda.toml is git-ignored because it holds the secret. Keep it readable only by the user that runs Sonda (chmod 600 sonda.toml).

Precedence is: built-in defaults, then the file, then environment variables. An unknown key in the file is an error, so a typo cannot be ignored silently.

Key Environment variable Default Meaning
server.listen SONDA_LISTEN 127.0.0.1:8080 Address to listen on. Localhost by default.
library.scan_workers 4 Files whose tags are read in parallel during a scan.
library.auto_scan_minutes SONDA_AUTO_SCAN_MINUTES 15 How often, in minutes, Sonda looks at the folders of the libraries and scans the ones whose music changed (a song or a folder came, went or was renamed); 0 turns it off. Looking reads the names of the files and nothing else, so it is cheap for a NAS. A library is scanned at least once a day anyway, which finds a song that was tagged again where it stands. A folder that cannot be read (a NAS that is not mounted) is left alone.
library.allow_delete SONDA_ALLOW_DELETE false Lets an admin delete the extra copy of a song from the music folders (see Duplicates). It is the one thing that makes Sonda write there, so it needs the folders mounted writable. A value that is not true or false is an error.
database.driver SONDA_DB_DRIVER sqlite sqlite or postgres.
database.path SONDA_DB_PATH sonda.db SQLite file (driver sqlite).
database.dsn SONDA_DB_DSN Connection string (driver postgres).
log.env SONDA_ENV production production logs JSON; dev logs readable text.
auth.jwt_secret SONDA_JWT_SECRET (required) Signs access tokens. At least 32 characters.
auth.access_ttl_minutes 15 Lifetime of an access token.
auth.refresh_ttl_hours 720 Lifetime of a refresh token (30 days).
listening.min_listen_seconds 20 A play counts as a listen after this long (1 to 3600), or when it is complete.
taste.half_life_days 90 After this many days a listen weighs half as much when learning your taste (1 to 3650).
wikipedia.languages ["en"] Languages for artist descriptions, best first: one to five codes of two or three lower case letters.
storage.data_dir SONDA_DATA_DIR data next to the SQLite database (data in the working directory with PostgreSQL) Where Sonda keeps the files it makes (covers). They are built from your music, so they need no backup.
scoring.weight_affinity, weight_genre, weight_preference, weight_discovery 0.40, 0.25, 0.25, 0.10 The weights of the parts of a Discover score (0 to 10 each, not all zero). Only their proportions matter.

Libraries and the external providers are not in the config: you set them up through the API (see the demo and External providers).

Using PostgreSQL

[database]
driver = "postgres"
dsn = "postgres://user:password@localhost:5432/sonda?sslmode=disable"

Sonda creates and migrates its tables on start. The storage tests run against both databases.