docs: add the README with a runnable local demo

- what Sonda is, what works today and what does not
- build, configure (keys and environment variables) and use PostgreSQL
- a demo from an empty database to streaming a track with curl: first user,
  library, scan, browse and search, Range streaming, listen events, token
  refresh and logout, a second user
- the API at a glance, security notes, backups, tests (including the
  PostgreSQL run) and the project layout

Closes #13
This commit is contained in:
tgiachi 2026-11-11 14:12:15 +01:00
commit dbbeb2aae0

239
README.md Normal file
View file

@ -0,0 +1,239 @@
# Sonda
Sonda is a privacy-first, self-hosted music server written in Go. It streams the music you already own, from your own disks, and keeps everything it knows about you on your own machine.
It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account.
> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Recommendations, a web client and OpenSubsonic compatibility are not built yet (see [What is not there yet](#what-is-not-there-yet)). The API may still change.
## What works today
- **Accounts.** The first user to register becomes the admin and registration then closes; admins create the other users. Short-lived access tokens (JWT) plus rotating refresh tokens, so a stolen refresh token is detected.
- **Libraries.** A library is a name and a folder, managed through the API. Sonda only ever reads your music folders: it never writes, renames or deletes a file.
- **Scanner.** Reads MP3 and FLAC tags and audio properties with several workers in parallel. Rescans are incremental, renamed files keep their identity, vanished files are flagged (never deleted), and a library whose folder looks empty or unreadable (an unmounted NAS) is left alone instead of being wiped.
- **Catalog.** Browse and search artists, albums and tracks, with paging, by library, artist or album. Only tracks you can actually play are listed.
- **Streaming.** `GET` and `HEAD` with `Range` support, so players can seek. Opening or prefetching a stream does not record a listen.
- **Listening history.** Clients report explicit `play`, `complete` and `skip` events. They stay in your database; nothing is sent anywhere. Sonda makes no outbound network requests at all.
## What is not there yet
Similar-artist discovery, recommendations and radio queues, a web client, OpenSubsonic compatibility, transcoding, and Last.fm/MusicBrainz/ListenBrainz integrations. The `[providers.lastfm]` section of the config is reserved for a later milestone and is not used yet.
## Requirements
- Go 1.27 or newer to build. The binary needs nothing else: SQLite and the tag reader are compiled in, with no CGO and no system libraries.
- `curl` and [`jq`](https://jqlang.github.io/jq/) for the demo below.
- Optional: `ffmpeg`, only to generate a few test tones for the demo.
## Build
```bash
go build -o bin/sondad ./cmd/sondad
```
## Configure
Sonda reads `./sonda.toml`, or the file given with `--config`. Every key has a default except the secret.
```bash
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. |
| `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). |
| `providers.lastfm.api_key` | `SONDA_LASTFM_API_KEY` | | Reserved, not used yet. |
Libraries are not in the config: you add them through the API (see the demo).
### Using PostgreSQL
```toml
[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.
## Demo
This takes you from an empty database to streaming a track. Run the server in one terminal and the commands in another.
**1. Get some music.** Point `MUSIC` at a folder of MP3 or FLAC files. The path must be absolute. If you have none, generate two test tones:
```bash
export MUSIC="$HOME/Music"
mkdir -p "$MUSIC/demo"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=440:duration=5" -metadata title="Tone A" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=1 "$MUSIC/demo/a.mp3"
ffmpeg -loglevel error -y -f lavfi -i "sine=frequency=660:duration=5" -metadata title="Tone B" -metadata artist="Demo Artist" -metadata album="Demo Album" -metadata track=2 "$MUSIC/demo/b.flac"
```
**2. Start the server** (after the Build and Configure steps above):
```bash
./bin/sondad
```
**3. Check it is up, create the first user, and log in:**
```bash
BASE=http://127.0.0.1:8080/api/v1
curl -s $BASE/health
# The first user becomes the admin; registration is then closed.
curl -s -X POST $BASE/auth/register -d '{"username":"alice","password":"correct horse battery"}'
LOGIN=$(curl -s -X POST $BASE/auth/login -d '{"username":"alice","password":"correct horse battery"}')
TOKEN=$(echo "$LOGIN" | jq -r .access_token)
REFRESH=$(echo "$LOGIN" | jq -r .refresh_token)
AUTH="Authorization: Bearer $TOKEN"
```
**4. Add a library and scan it:**
```bash
curl -s -X POST $BASE/libraries -H "$AUTH" -d "{\"name\":\"Music\",\"path\":\"$MUSIC\"}" | jq
curl -s -X POST $BASE/library/scan -H "$AUTH"
until [ "$(curl -s $BASE/library/scan -H "$AUTH" | jq .running)" = false ]; do sleep 1; done
curl -s $BASE/library/scan -H "$AUTH" | jq .last
```
`found`, `added`, `unchanged`, `renamed`, `missing` and `failed` tell you what the scan did. Run it again and everything is `unchanged`.
**5. Browse and search:**
```bash
curl -s "$BASE/artists?limit=5" -H "$AUTH" | jq
curl -s "$BASE/albums" -H "$AUTH" | jq '.items[] | {id, title, artist: .artist.name, tracks: .track_count}'
curl -s "$BASE/tracks?q=tone" -H "$AUTH" | jq '.items[] | {id, title, artists: [.artists[].name], format}'
```
**6. Stream a track:**
```bash
TRACK=$(curl -s "$BASE/tracks?limit=1" -H "$AUTH" | jq -r '.items[0].id')
# Ask for the first 100 bytes: the answer is 206 Partial Content with a Content-Range header.
curl -s -D - -o /dev/null -H "$AUTH" -H 'Range: bytes=0-99' $BASE/tracks/$TRACK/stream
# The whole file.
curl -s -o track.audio -H "$AUTH" $BASE/tracks/$TRACK/stream
```
A browser `<audio>` element cannot send headers, so the stream URL also accepts the access token in the query string: `$BASE/tracks/$TRACK/stream?access_token=$TOKEN`. That is the only route that does, and the query string is never logged.
**7. Report a listen.** Streaming never counts as a listen; clients say what happened. The idempotency key makes a retry harmless:
```bash
curl -s -X POST $BASE/listens -H "$AUTH" -d "{\"track_id\":$TRACK,\"event_type\":\"complete\",\"duration_played_ms\":5000,\"idempotency_key\":\"demo-1\"}"
```
**8. Refresh the session and log out:**
```bash
NEW=$(curl -s -X POST $BASE/auth/refresh -d "{\"refresh_token\":\"$REFRESH\"}")
TOKEN=$(echo "$NEW" | jq -r .access_token)
REFRESH=$(echo "$NEW" | jq -r .refresh_token)
AUTH="Authorization: Bearer $TOKEN"
curl -s -X POST $BASE/auth/logout -d "{\"refresh_token\":\"$REFRESH\"}"
```
Each refresh token works once. Presenting a spent one again, more than ten seconds after it was used, ends every session of that user.
**9. Add another user** (admins only):
```bash
TOKEN=$(curl -s -X POST $BASE/auth/login -d '{"username":"alice","password":"correct horse battery"}' | jq -r .access_token)
AUTH="Authorization: Bearer $TOKEN"
curl -s -X POST $BASE/users -H "$AUTH" -d '{"username":"bob","password":"another long password"}' | jq
```
## The API at a glance
Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"error":{"code":"...","message":"..."}}`.
| Who | Method and path | What it does |
|---|---|---|
| anyone | `GET /health` | Liveness check. |
| anyone | `POST /auth/register` | Create the first user (admin). Closed afterwards. |
| anyone | `POST /auth/login`, `/auth/refresh`, `/auth/logout` | Open, renew and end a session. |
| signed in | `GET /auth/me`, `POST /auth/password` | Your account; change your password (signs you out everywhere). |
| signed in | `GET /artists`, `/albums`, `/tracks` and `/…/{id}` | Browse and search. Query: `q`, `limit` (default 50, max 200), `offset`, `library_id`, `artist_id`, `album_id`. |
| signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. |
| signed in | `POST /listens` | Record a `play`, `complete` or `skip`. |
| signed in | `GET /library/scan` | Scan status and the last result. |
| admin | `GET`, `POST /libraries`; `PATCH`, `DELETE /libraries/{id}` | Manage libraries. Deleting one removes its index entries, never your files. |
| admin | `POST /library/scan`, `POST /libraries/{id}/scan` | Scan everything, or one library. |
| admin | `GET`, `POST /users`; `PATCH`, `DELETE /users/{id}`; `PUT /users/{id}/password` | Manage users and the admin role. The last admin cannot be demoted or deleted. |
A library path must be an absolute, existing folder, never the filesystem root, and never inside or around another library. Search is a case-insensitive substring match: `BJÖRK` finds `Björk`, but accents are kept, so `bjork` does not.
## Security notes
- Sonda listens on localhost only, unless you change `server.listen`. To use it from other machines, put it behind a reverse proxy that terminates HTTPS.
- Passwords are hashed with Argon2id. Refresh tokens are stored only as hashes.
- Music folders are read-only to Sonda. Streaming opens files through `os.Root`, so a path can never leave its library, even if a symlink is swapped in later.
- File paths are never returned by the catalog, and audio file paths are not logged.
## Back up
Back up the database and `sonda.toml`. Your music stays wherever you keep it.
- **SQLite:** `sqlite3 sonda.db ".backup sonda-backup.db"` works while Sonda runs. Or stop Sonda and copy `sonda.db` (and `sonda.db-wal` if it exists).
- **PostgreSQL:** `pg_dump` the database.
- `sonda.toml` holds the secret that signs tokens; treat the copy like a password.
## Development
```bash
go vet ./...
go test -race ./...
```
The default test run needs no network and uses SQLite only. To run the same storage tests against PostgreSQL as well, start a throwaway server and point the tests at it:
```bash
docker run -d --rm --name sonda-test-pg -e POSTGRES_PASSWORD=sonda -e POSTGRES_DB=sonda -p 127.0.0.1:55432:5432 postgres:17-alpine
SONDA_TEST_POSTGRES_DSN='postgres://postgres:sonda@127.0.0.1:55432/sonda?sslmode=disable' go test -race ./...
docker rm -f sonda-test-pg
```
Tests that read real audio need `ffmpeg` and are skipped when it is missing.
Layout:
```
cmd/sondad/ the server: wiring, config, logging, shutdown
internal/api/http/ the REST API (thin handlers)
internal/auth/ users, roles, passwords, access and refresh tokens
internal/catalog/ browsing and searching artists, albums, tracks
internal/library/ libraries, the scanner, the event hub, the tag reader
internal/listening/ listen events
internal/storage/ SQLite and PostgreSQL through bun, the repositories
internal/streaming/ opening a track's file safely
migrations/ SQL migrations, one folder per database
```
Migrations are plain SQL files in `migrations/sqlite` and `migrations/postgres`. They must describe the same schema, and a test checks that both folders hold the same files. Add a new numbered file to both whenever the schema changes.
## Third-party code
Audio tags are read with `go.senan.xyz/taglib`, which embeds [TagLib](https://github.com/taglib/taglib) compiled to WebAssembly and is licensed under the LGPL 2.1. The other dependencies are listed in `go.mod`.