Add Docker/systemd deployment, documentation, extauth logout URL wiring

README.md

@@ -0,0 +1,95 @@
+# VibeSonic
+
+VibeSonic is a lightweight, self-hosted music/media server written in Go.
+It follows the same philosophy as other small `Vibe*` tools: a single Go
+binary, SQLite storage, server-rendered Bootstrap 5 templates, dark mode
+by default, minimal JavaScript, and no external services (no Redis, no
+message broker, no microservices, nothing Kubernetes-specific).
+
+**This is Phase 1 of 4.** It builds the foundation — configuration,
+database schema, authentication, the library scanner, metadata reading,
+direct streaming, cover art, and the web UI shell — that later phases
+build the full Subsonic/OpenSubsonic API on top of. Phase 1 does **not**
+implement the Subsonic protocol itself; see
+[`docs/subsonic-compatibility.md`](docs/subsonic-compatibility.md) for
+what's planned.
+
+## Features (Phase 1)
+
+- SQLite storage (WAL mode, foreign keys, versioned migrations) with a
+  schema already modeling artists, albums, songs, genres, contributors,
+  playlists, favorites, ratings, scrobbles, playback history, bookmarks,
+  play queues, shares, podcasts, internet radio, and settings
+- Native authentication: Argon2id password hashing, HTTP-only signed
+  session cookies, CSRF-protected forms, session revocation
+- Optional Navidrome-style external authentication via a trusted reverse
+  proxy header, gated on the real TCP peer address (never on
+  spoofable `X-Forwarded-For`/`X-Real-IP`/`Forwarded` headers)
+- A library scanner supporting multiple music folders, incremental
+  rescans, new/changed/deleted/renamed file detection, and a bounded
+  worker pool — never a blind full rebuild
+- Real metadata extraction via `ffprobe` (multi-artist, multi-genre,
+  MusicBrainz IDs, ReplayGain, embedded artwork/lyrics, sort fields, and
+  more)
+- Stable, opaque, URL-safe IDs that survive restarts and rescans
+- Direct media streaming with HTTP range request support, correct MIME
+  types, and no full-file buffering
+- Cover art discovery (embedded artwork or folder images) with a
+  resized-image disk cache
+- A server-rendered, dark-mode, keyboard-friendly web UI: browsing,
+  search, playlists, favorites, a persistent bottom player, and an admin
+  section (users, music folders, scanner status, system settings)
+- `/healthz` and `/readyz`
+
+## Quick start
+
+```
+go build -o vibesonic ./cmd/vibesonic
+VIBESONIC_SESSION_SECRET=$(openssl rand -hex 32) ./vibesonic
+```
+
+Then open `http://localhost:8080` — on a fresh database you'll land on
+the setup wizard, which creates the administrator account, your first
+music folder, and kicks off the first scan.
+
+`ffmpeg`/`ffprobe` should be on `PATH` (or pointed to via
+`VIBESONIC_FFMPEG_PATH`/`VIBESONIC_FFPROBE_PATH`) for metadata reading
+and cover art extraction to work.
+
+### Docker
+
+```
+docker compose up -d
+```
+
+See [`docker-compose.yml`](docker-compose.yml) — mount your music
+directory read-only at `/music` and set `VIBESONIC_SESSION_SECRET`.
+
+### systemd
+
+See [`systemd/vibesonic.service`](systemd/vibesonic.service).
+
+## Configuration
+
+VibeSonic is configured entirely through `VIBESONIC_*` environment
+variables — see [`docs/configuration.md`](docs/configuration.md) for the
+full list and defaults. There is no separate config file.
+
+## Documentation
+
+- [`docs/architecture.md`](docs/architecture.md) — how the pieces fit together
+- [`docs/configuration.md`](docs/configuration.md) — every environment variable
+- [`docs/external-auth.md`](docs/external-auth.md) — trusted reverse-proxy authentication
+- [`docs/subsonic-compatibility.md`](docs/subsonic-compatibility.md) — protocol endpoint status
+
+## Development
+
+```
+go fmt ./...
+go vet ./...
+go test ./...
+```
+
+Most tests exercise real SQLite databases and, where relevant, the real
+`ffmpeg`/`ffprobe` binaries (skipped automatically if not installed).
+No mocks are used for the database.