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:
parent
ddabcd3bb3
commit
95ba06311e
5 changed files with 75 additions and 23 deletions
|
|
@ -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
|
||||
|
|
|
|||
11
README.md
11
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
41
internal/api/http/health_log_test.go
Normal file
41
internal/api/http/health_log_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
Loading…
Reference in a new issue