fix(docker): keep the secret, quiet health checks, and tighter files

- The README keeps the JWT secret in a file that is passed every time, so an upgrade
  does not make a new one and sign everybody out.
- A health check that succeeds is logged at debug level, so a container does not write
  thousands of lines a day; any other answer, and every other request, still goes at info.
- .dockerignore patterns match in every folder, as .gitignore does.
- compose.yaml waits 15 seconds for Sonda to stop (it allows itself 10) and requires
  MUSIC_DIR instead of creating an empty folder.
- The README says that the library path is the one inside the container, that the health
  check follows SONDA_LISTEN, and that a sonda.toml in /data works as a secrets file.
This commit is contained in:
tgiachi 2026-11-12 12:29:38 +01:00
commit 95ba06311e
5 changed files with 75 additions and 23 deletions

View file

@ -4,26 +4,26 @@
bin
data
web
*.db
*.db-wal
*.db-shm
**/*.db
**/*.db-wal
**/*.db-shm
sonda.toml
*.test
*.out
**/*.test
**/*.out
Dockerfile
.dockerignore
compose.yaml
README.md
# AI agent instruction files: never part of the project's files
agent.md
Agent.md
AGENT.md
agents.md
Agents.md
AGENTS.md
claude.md
Claude.md
CLAUDE.md
GEMINI.md
.claude
# AI agent instruction files: never part of the project's files, wherever they are
**/agent.md
**/Agent.md
**/AGENT.md
**/agents.md
**/Agents.md
**/AGENTS.md
**/claude.md
**/Claude.md
**/CLAUDE.md
**/GEMINI.md
**/.claude

View file

@ -47,19 +47,22 @@ The image holds `sondad` and nothing else (the web client is not in it: `sondad`
```bash
docker build -t sonda .
docker run -d --name sonda --restart unless-stopped \
(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 \
-e SONDA_JWT_SECRET="$(openssl rand -hex 32)" \
--env-file sonda.env \
-v sonda-data:/data \
-v "$HOME/Music":/music:ro \
sonda
```
Mount your music read-only wherever you like, then add the library through the API with the path *inside* the container (`/music` above): the [Demo](#demo) works the same way with `BASE=http://127.0.0.1:8080/api/v1`. Keep the secret: a new one signs out everybody. 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](#configure) (`SONDA_DB_DRIVER` and `SONDA_DB_DSN` for PostgreSQL); the image sets `SONDA_LISTEN`, `SONDA_DB_PATH` and `SONDA_DATA_DIR` for the volume.
Mount your music read-only wherever you like, then add the library through the API with the path *inside* the container, `/music` above (not the folder of your host): the [Demo](#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](#configure) (`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`, `SONDA_PORT` if you want) in a `.env` file next to it and run `docker compose up -d --build`. The image has a health check on `/api/v1/health`.
`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`. 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.
## Configure

View file

@ -2,7 +2,7 @@
# this one (it is not committed):
#
# SONDA_JWT_SECRET=<output of: openssl rand -hex 32>
# MUSIC_DIR=/path/to/your/music # optional, ./music by default
# MUSIC_DIR=/path/to/your/music
# SONDA_PORT=8080 # optional, the port on this machine
#
# then: docker compose up -d --build
@ -11,6 +11,7 @@ services:
build: .
image: sonda:local
restart: unless-stopped
stop_grace_period: 15s # Sonda waits up to 10 seconds for the requests in progress when it is stopped
# Only this machine can reach it. To serve your network, publish "${SONDA_PORT:-8080}:8080" instead,
# and put a reverse proxy with https in front of it.
ports:
@ -20,7 +21,7 @@ services:
# TZ: Europe/Rome
volumes:
- sonda-data:/data # the database and the files Sonda makes: back up the database
- ${MUSIC_DIR:-./music}:/music:ro # your music, read-only: a library is added with the path /music
- ${MUSIC_DIR:?set MUSIC_DIR in .env to the folder of your music}:/music:ro # your music, read-only: a library is added with the path /music
volumes:
sonda-data:

View file

@ -0,0 +1,41 @@
package httpapi
import (
"net/http"
"testing"
"github.com/uptrace/bun"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"go.uber.org/zap/zaptest/observer"
)
// A container's health check asks every thirty seconds: that must not fill the log at the level
// people read, while every other request is still logged there.
func TestAHealthCheckThatSucceedsIsLoggedAtDebugAndOtherRequestsAtInfo(t *testing.T) {
core, logs := observer.New(zap.DebugLevel)
h, _ := newTestEnvDB(t, func(d *Deps, _ *bun.DB) { d.Logger = zap.New(core) })
for i := 0; i < 3; i++ {
if r := do(t, h, "GET", "/api/v1/health", "", nil); r.Code != http.StatusOK {
t.Fatalf("health: %d", r.Code)
}
}
do(t, h, "GET", "/api/v1/artists", "", nil) // refused, but a request like any other
var healthInfo, healthDebug, otherInfo int
for _, e := range logs.All() {
path, _ := e.ContextMap()["path"].(string)
switch {
case path == "/api/v1/health" && e.Level == zapcore.InfoLevel:
healthInfo++
case path == "/api/v1/health" && e.Level == zapcore.DebugLevel:
healthDebug++
case path == "/api/v1/artists" && e.Level == zapcore.InfoLevel:
otherInfo++
}
}
if healthInfo != 0 || healthDebug != 3 || otherInfo != 1 {
t.Errorf("health at info %d, at debug %d, other requests at info %d; want 0, 3 and 1", healthInfo, healthDebug, otherInfo)
}
}

View file

@ -43,10 +43,17 @@ func requestLog(logger *zap.Logger) gin.HandlerFunc {
// Internal errors are hidden from the client; keep them in the log.
fields = append(fields, zap.String("error", last.Error()))
}
if c.Request.URL.Path == healthPath && c.Writer.Status() == http.StatusOK {
logger.Debug("http request", fields...) // a health check asks all day: it is not news
return
}
logger.Info("http request", fields...)
}
}
// healthPath is what the health check of a container asks; see the Dockerfile.
const healthPath = "/api/v1/health"
// currentUserID returns the authenticated user's id (set by requireAuth).
func currentUserID(c *gin.Context) int64 {
v, _ := c.Get(ctxUserID)