diff --git a/.dockerignore b/.dockerignore index 85084ca..5e853f9 100644 --- a/.dockerignore +++ b/.dockerignore @@ -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 diff --git a/README.md b/README.md index 0541d3c..1c45b13 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/compose.yaml b/compose.yaml index 5fd60a2..b8a96c2 100644 --- a/compose.yaml +++ b/compose.yaml @@ -2,7 +2,7 @@ # this one (it is not committed): # # SONDA_JWT_SECRET= -# 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: diff --git a/internal/api/http/health_log_test.go b/internal/api/http/health_log_test.go new file mode 100644 index 0000000..69cf861 --- /dev/null +++ b/internal/api/http/health_log_test.go @@ -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) + } +} diff --git a/internal/api/http/middleware.go b/internal/api/http/middleware.go index 0e41a92..4b8e674 100644 --- a/internal/api/http/middleware.go +++ b/internal/api/http/middleware.go @@ -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)