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:
parent
b657d20452
commit
dbbeb2aae0
1 changed files with 239 additions and 0 deletions
239
README.md
Normal file
239
README.md
Normal 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`.
|
||||
Loading…
Reference in a new issue