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.
This commit is contained in:
tgiachi 2026-11-12 12:23:41 +01:00
commit ddabcd3bb3
5 changed files with 118 additions and 0 deletions

29
.dockerignore Normal file
View file

@ -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

1
.gitignore vendored
View file

@ -6,6 +6,7 @@ sonda.toml
*.db-wal
*.db-shm
/data/
.env
# AI agent instruction files: never published (Codeberg EULA)
agent.md

41
Dockerfile Normal file
View file

@ -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"]

View file

@ -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.

26
compose.yaml Normal file
View file

@ -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=<output of: openssl rand -hex 32>
# 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: