diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..5e853f9 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,29 @@ +.git +.idea +.gitignore +bin +data +web +**/*.db +**/*.db-wal +**/*.db-shm +sonda.toml +**/*.test +**/*.out +Dockerfile +.dockerignore +compose.yaml +README.md + +# 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/.gitignore b/.gitignore index 04bae5e..4869cfd 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,7 @@ sonda.toml *.db-wal *.db-shm /data/ +.env # AI agent instruction files: never published (Codeberg EULA) agent.md diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..b684c87 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,41 @@ +# syntax=docker/dockerfile:1 + +# Build: Sonda has no CGO (SQLite, PostgreSQL and the tag reader are pure Go), so the binary +# is static and the final image needs nothing but it and the CA certificates. +FROM golang:1.27-alpine AS build +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY cmd ./cmd +COPY internal ./internal +COPY migrations ./migrations +RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/sondad ./cmd/sondad + +FROM alpine:3.22 +LABEL org.opencontainers.image.title="Sonda" \ + org.opencontainers.image.description="A privacy-first, self-hosted music server" \ + org.opencontainers.image.source="https://codeberg.org/squidd/sonda" +# ca-certificates: the providers an admin may switch on are reached over https. +# tzdata: log times in the zone the operator sets with TZ. +RUN apk add --no-cache ca-certificates tzdata \ + && addgroup -S -g 10001 sonda \ + && adduser -S -u 10001 -G sonda -h /data -H sonda \ + && mkdir -p /data /music \ + && chown sonda:sonda /data +COPY --from=build /out/sondad /usr/local/bin/sondad + +# Everything Sonda writes is under /data: the database and the files it makes (covers, pictures). +# The music is mounted, read-only, wherever you like (/music is a convention); a library is added +# through the API with its path inside the container. SONDA_JWT_SECRET has no default and is +# required: the server does not start without it. +ENV SONDA_LISTEN=0.0.0.0:8080 \ + SONDA_DB_PATH=/data/sonda.db \ + SONDA_DATA_DIR=/data/files \ + SONDA_ENV=production +WORKDIR /data +USER sonda +VOLUME /data +EXPOSE 8080 +HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \ + CMD wget -qO /dev/null "http://127.0.0.1:${SONDA_LISTEN##*:}/api/v1/health" || exit 1 +ENTRYPOINT ["sondad"] diff --git a/README.md b/README.md index f2bb21e..1c45b13 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,29 @@ Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz inte go build -o bin/sondad ./cmd/sondad ``` +### Docker + +The image holds `sondad` and nothing else (the web client is not in it: `sondad` does not serve it yet). 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`. + +```bash +docker build -t sonda . +(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 \ + sonda +``` + +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` (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 Sonda reads `./sonda.toml`, or the file given with `--config`. Every key has a default except the secret. @@ -348,6 +371,7 @@ internal/storage/ SQLite and PostgreSQL through bun, the repositories internal/streaming/ opening a track's file safely migrations/ SQL migrations, one folder per database web/ the web client (React, Vite, shadcn/ui) +Dockerfile, compose.yaml the image of sondad, and an example for Docker Compose ``` The API description is `internal/api/openapi/openapi.yaml`, written by hand and embedded in the binary. Two tests keep it in step with the code: one fails when a route and the spec disagree in either direction, and a contract test sends real requests through every operation and validates each response (status, headers, JSON body) against the spec. Adding or changing an endpoint therefore means updating the spec in the same change. Response objects are closed (`additionalProperties: false`), so a field added in the code and forgotten in the spec fails the build. diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..b8a96c2 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,27 @@ +# An example for running Sonda with Docker Compose. Put the secret in a file named .env next to +# this one (it is not committed): +# +# SONDA_JWT_SECRET= +# MUSIC_DIR=/path/to/your/music +# SONDA_PORT=8080 # optional, the port on this machine +# +# then: docker compose up -d --build +services: + sonda: + 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: + - "127.0.0.1:${SONDA_PORT:-8080}:8080" + environment: + SONDA_JWT_SECRET: ${SONDA_JWT_SECRET:?set SONDA_JWT_SECRET in .env (openssl rand -hex 32)} + # TZ: Europe/Rome + volumes: + - sonda-data:/data # the database and the files Sonda makes: back up the database + - ${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)