From 95c1fa3e27735e99da2571f11948a519c58f0593 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Thu, 12 Nov 2026 15:56:36 +0100 Subject: [PATCH] build: make build and an image with the web app inside; README describes it make build builds the app and then sondad with -tags webui. The Dockerfile builds the app in a Node stage and embeds it in the Go build, so the image serves it with no Node on the host. README: how to build, what the image holds, the policy of the page, and how to work on the interface with the dev server. --- .dockerignore | 5 ++++- Dockerfile | 15 +++++++++++++-- Makefile | 20 ++++++++++++++++++++ README.md | 18 ++++++++++++------ 4 files changed, 49 insertions(+), 9 deletions(-) create mode 100644 Makefile diff --git a/.dockerignore b/.dockerignore index 5e853f9..15c247d 100644 --- a/.dockerignore +++ b/.dockerignore @@ -3,7 +3,10 @@ .gitignore bin data -web +# The web app is built in the image; its dependencies and a build of it on this machine are not sent. +web/node_modules +web/dist +internal/webui/dist **/*.db **/*.db-wal **/*.db-shm diff --git a/Dockerfile b/Dockerfile index b684c87..802b1f8 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,17 @@ # syntax=docker/dockerfile:1 +# The web app: built once here, written (by its Vite config) to /src/internal/webui/dist, where the Go +# build below embeds it. Nothing of Node reaches the final image. +FROM node:24-alpine AS web +WORKDIR /src/web +COPY web/package.json web/package-lock.json ./ +RUN npm ci +COPY web ./ +RUN npm run build + # 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. +# is static and the final image needs nothing but it and the CA certificates. The web app is inside it +# (-tags webui), so sondad serves it on / and the API on /api. FROM golang:1.27-alpine AS build WORKDIR /src COPY go.mod go.sum ./ @@ -9,7 +19,8 @@ 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 +COPY --from=web /src/internal/webui/dist ./internal/webui/dist +RUN CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o /out/sondad ./cmd/sondad FROM alpine:3.22 LABEL org.opencontainers.image.title="Sonda" \ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c2f008f --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Sonda with its web app inside the binary. +# +# make build build the web app, then sondad with the app embedded (bin/sondad) +# make web only the web app (it is written to internal/webui/dist) +# make test the Go tests and the web tests +# +# A plain `go build ./cmd/sondad` still works: it gives the API only, and / says how to build the app. + +.PHONY: build web test + +build: web + CGO_ENABLED=0 go build -tags webui -trimpath -ldflags="-s -w" -o bin/sondad ./cmd/sondad + +web: + cd web && npm ci && npm run build + +test: + go vet ./... + go test ./... + cd web && npm test diff --git a/README.md b/README.md index 7079808..e0e36f5 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Sonda is a privacy-first, self-hosted music server written in Go. It streams the It is a single executable, one database (SQLite by default, PostgreSQL if you prefer) and the folders that hold your music. There is no Redis, no message broker and no cloud account. -> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). Radio queues and OpenSubsonic compatibility are not built yet, and the web client in `web/` is a work in progress (see [What is not there yet](#what-is-not-there-yet) and [Web app](#web-app)). The API may still change. +> **Status: early.** The local-playback part works end to end: accounts, libraries, scanning, search, and streaming with HTTP Range. Suggestions of new artists work too (Discover). Radio queues and OpenSubsonic compatibility are not built yet, and the web client in `web/`, which `sondad` serves, is young (see [What is not there yet](#what-is-not-there-yet) and [Web app](#web-app)). The API may still change. ## What works today @@ -27,7 +27,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr ## What is not there yet -Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client exists (see [Web app](#web-app)) but `sondad` does not serve it yet, and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs. +Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz integration. The web client is built into the binary (see [Web app](#web-app)), and its admin area covers everything the API can do for an admin: libraries and scanning, users, the external providers and the bulk jobs. ## Requirements @@ -38,12 +38,16 @@ Radio queues, OpenSubsonic compatibility, transcoding, and the ListenBrainz inte ## Build ```bash -go build -o bin/sondad ./cmd/sondad +make build # the web app (needs Node), then bin/sondad with the app inside ``` +`make build` runs `npm ci` and `npm run build` in `web/`, which writes the app to `internal/webui/dist`, and then builds `sondad` with the tag `webui`, which embeds it: one program that serves the app on `/` and the API on `/api`. You can do the same by hand: `(cd web && npm ci && npm run build) && go build -tags webui -o bin/sondad ./cmd/sondad`. + +A plain `go build -o bin/sondad ./cmd/sondad` needs no Node and gives the API only; `/` then shows a page that says how to build the app. `make test` runs the Go tests and the web tests. + ### 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`. +The image holds `sondad` with the web app inside, and nothing else: it builds the app itself, so you need no Node on your machine. 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 . @@ -320,7 +324,9 @@ Back up the database and `sonda.toml`. Your music stays wherever you keep it. ## Web app -A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. `sondad` does not serve it yet, so for now it runs next to the server: +A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. With the app built into the binary (`make build`, or the Docker image) `sondad` serves it: open the address of the server, for example `http://127.0.0.1:8080`, and sign in. The page carries a strict Content-Security-Policy (only resources of the server itself, no inline scripts), cannot be framed and sends no referrer, and a link inside the app (`/admin/users`) works when you reload it. + +To work on the interface itself, run the Vite dev server next to a running `sondad` (set `SONDA_URL` to where it listens: the default is `http://127.0.0.1:8080`): ```bash cd web @@ -330,7 +336,7 @@ SONDA_URL=http://127.0.0.1:8080 npm run dev # open http://localhost:5173, /api What it does today: sign in (and create the first account of a new server), browse artists, albums and songs, search, and play with a queue, shuffle, repeat, media keys, a volume slider with mute (remembered in the browser) and a full-screen player. Artist pages show the Wikipedia text, similar artists and tags when those providers are on, each with its credit, and the photo credit next to the photo. It reports one listen per play. Discover suggests artists from the ones you pick, or from your listening only after you allow it (a dialog says that their names go to Last.fm), explains each score, and keeps your wishlist and the artists you are not interested in. An admin who set up the `lidarr` provider gets a "Request on Lidarr" button on an artist's page and on the Discover cards: it asks first, then sends that one artist to their own Lidarr, which does the downloading (the web app downloads nothing; the page of an artist reads what Lidarr has, the cards ask nothing until you send). An admin also gets an Admin area to add, rename, move and remove libraries and to start a scan (of one library or all, optionally reading every file again) and follow it, and to manage accounts: add one by email, give or take away the admin role, reset a password (which ends that person's sessions) and delete an account. The last admin cannot be changed, and your own account has no buttons there. Providers have a card each that says what the provider is sent: turning one on asks first, the API key is write-only (never shown, and gone from the page once saved), and there are a test of the key, the contact or address, removing what a provider gave, and, for Lidarr, the profiles and root folder to use when an artist is added. The bulk jobs (album covers, artist pictures, artist descriptions) each have a card that says what the job sends and to whom: starting one asks first and says it goes through the whole library, reading everything again is a separate choice, a job whose providers are off cannot be started, and the page follows its progress and can stop it. There are six themes (Sonda, Tokyo Night, Gruvbox dark, Gruvbox light, Dracula and Neon) and two languages (English and Italian), both chosen in Settings. -More commands, all run in `web/`: `npm test`, `npm run build`, and `npm run gen:api`, which rebuilds `src/api/schema.d.ts` from the OpenAPI spec (it fetches the generator with `npx`, so it needs the network once). Serving the app from the binary comes later. +More commands, all run in `web/`: `npm test`, `npm run build`, and `npm run gen:api`, which rebuilds `src/api/schema.d.ts` from the OpenAPI spec (it fetches the generator with `npx`, so it needs the network once). `npm run build` writes to `internal/webui/dist` (git-ignored), not to `web/dist`. ## Development