sonda/docs/install.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

4.3 KiB

Install

Docs · Sonda

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 for the demo below.
  • Optional: ffmpeg, only to generate a few test tones for the demo.

Build

make build   # the web app (needs Node), then bin/sondad with the app inside

make build runs npm ci and npm run build in web/, which writes the app to internal/webui/dist, and then builds sondad with the tag webui, which embeds it: one program that serves the app on / and the API on /api. You can do the same by hand: (cd web && npm ci && npm run build) && go build -tags webui -o bin/sondad ./cmd/sondad.

A plain go build -o bin/sondad ./cmd/sondad needs no Node and gives the API only; / then shows a page that says how to build the app. make test runs the Go tests and the web tests.

Docker

The image holds sondad with the web app inside, and nothing else: it builds the app itself, so you need no Node on your machine. It runs as an ordinary user, keeps the database and the files Sonda makes under /data, listens on port 8080 inside the container, and does not start without SONDA_JWT_SECRET.

The image is published on the registry of git.kmalloc.org, so you do not have to build it: git.kmalloc.org/squid/sonda:latest is the last one, and git.kmalloc.org/squid/sonda:0.3.0 (a version from CHANGELOG.md) is one you can stay on. It runs on amd64 and on arm64 (a Raspberry Pi, an ARM NAS): one tag gives each machine its own. Anyone can pull it, with no login. To build it yourself instead, run docker build -t sonda . and use sonda where the commands below say git.kmalloc.org/squid/sonda:latest.

docker pull git.kmalloc.org/squid/sonda:latest
(umask 077; echo "SONDA_JWT_SECRET=$(openssl rand -hex 32)" > sonda.env)   # once: keep this file
docker run -d --name sonda --restart unless-stopped --stop-timeout 15 \
  -p 127.0.0.1:8080:8080 \
  --env-file sonda.env \
  -v sonda-data:/data \
  -v "$HOME/Music":/music:ro \
  git.kmalloc.org/squid/sonda:latest

Mount your music read-only wherever you like (only if you want Sonda to delete duplicate files, mount it writable and set SONDA_ALLOW_DELETE=true: see Duplicates), then add the library through the API with the path inside the container, /music above (not the folder of your host): the Demo works the same way with BASE=http://127.0.0.1:8080/api/v1, except that step 4 creates the library with "path":"/music". Keep sonda.env and pass it every time you run a new container, for example after an upgrade: a new secret signs out everybody. The container's health check asks the port in SONDA_LISTEN, so it works for 0.0.0.0, [::] and a port alone, but not if you bind the server to one interface address. Published like this the server answers only on this machine; to serve your network, publish the port without 127.0.0.1: and put a reverse proxy with https in front. The other settings are the environment variables of the table below (SONDA_DB_DRIVER and SONDA_DB_DSN for PostgreSQL); the image sets SONDA_LISTEN, SONDA_DB_PATH and SONDA_DATA_DIR for the volume.

To keep the data in a folder of the host instead of a volume, run the container as the owner of that folder, or it cannot write there: add --user "$(id -u):$(id -g)" and -v /path/to/sonda-data:/data. Back up sonda.db (and treat the backup like a secret: it holds the API keys of the providers); the rest of /data is built from your music.

compose.yaml is the same as an example: put SONDA_JWT_SECRET and MUSIC_DIR (and SONDA_PORT if 8080 is taken) in a .env file next to it and run docker compose up -d --build (to use the published image and not build one, swap the build: . and image: lines for the one in the comment of the file, and run docker compose pull && docker compose up -d). The image has a health check on /api/v1/health, which is logged at debug level when it succeeds.

If you prefer a config file to environment variables (it can hold the secret and the other settings, so a Docker or Compose secret can provide it), put a sonda.toml in /data or pass --config /run/secrets/sonda.toml; the variables the image sets still win over the file.