From ddabcd3bb31d34727540b084f4a202d0cf0d4430 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Thu, 12 Nov 2026 12:23:41 +0100 Subject: [PATCH] feat(docker): an image of sondad and a compose example - A multi-stage Dockerfile: Sonda has no CGO, so the binary is static and the final image (alpine, 69 MB) holds only it, the CA certificates and the time zones. - It runs as an ordinary user (uid 10001), keeps the database and the files it makes under /data (a volume), listens on 0.0.0.0:8080 inside the container, and does not start without SONDA_JWT_SECRET. - A health check on /api/v1/health that follows SONDA_LISTEN. - compose.yaml as an example: the secret comes from .env (which is not committed), the music is mounted read-only, and the port is published on this machine only. - .dockerignore keeps the web client, the databases and the agent files out of the build. - The README says how to build, run and back up, and how to use a host folder. --- .dockerignore | 29 +++++++++++++++++++++++++++++ .gitignore | 1 + Dockerfile | 41 +++++++++++++++++++++++++++++++++++++++++ README.md | 21 +++++++++++++++++++++ compose.yaml | 26 ++++++++++++++++++++++++++ 5 files changed, 118 insertions(+) create mode 100644 .dockerignore create mode 100644 Dockerfile create mode 100644 compose.yaml diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..85084ca --- /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 +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..0541d3c 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,26 @@ 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 . +docker run -d --name sonda --restart unless-stopped \ + -p 127.0.0.1:8080:8080 \ + -e SONDA_JWT_SECRET="$(openssl rand -hex 32)" \ + -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. + +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`. + ## Configure Sonda reads `./sonda.toml`, or the file given with `--config`. Every key has a default except the secret. @@ -348,6 +368,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..5fd60a2 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,26 @@ +# 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 # optional, ./music by default +# SONDA_PORT=8080 # optional, the port on this machine +# +# then: docker compose up -d --build +services: + sonda: + build: . + image: sonda:local + restart: unless-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:-./music}:/music:ro # your music, read-only: a library is added with the path /music + +volumes: + sonda-data: