Stellar Grooves — Self-Hosted Music Library

The Challenge

If you own your music — actual files, ripped or bought — your options are bleak. Streaming services don’t want your library; media servers like Plex and Jellyfin treat music as an afterthought; and nothing lets you treat a playlist as something you can share and re-run, not just a frozen list of tracks.

We wanted a music app built around a different idea: playlists are queries. Write a rule like “four-star thrash I haven’t played in a year,” save it, and share the query — so other curators can run it against their own libraries. That meant building, and open-sourcing, a real multi-user web application:

• Let people stream their own collection in the browser, on any device, with no upload to anyone’s cloud
• Make smart playlists first-class — a real query language, not a few canned filters
• Let curators share playlists as portable queries, not as copied audio
• Keep it genuinely self-hostable — one command to run, hardened by default
• Build it in the open, under a license that keeps it open

Our Approach

Stellar Grooves is a Stellar Ideas LLC open-source product, released under the AGPL-3.0 license on GitHub. It’s a self-hosted, multi-user library you point at your own music directory; it scans your files, auto-organizes them, and streams them back to you in a retro, jukebox-themed interface.

Key decisions:

• Playlists as queries — a focused DSL (genre:hard_rock rating:>=4 lastPlayed:>1y sort:random limit:25) with boolean composition, negation, time windows, and reusable @phrase fragments. Any query can be previewed with a live match count before you save it
• Share the query, not the audio — a curator publishes a link; subscribers run that curator’s query against their own library and only ever see tracks they themselves own. Playlists can be forked, and keep working even if the original is deleted
• Own your files — scan local directories (or an S3-compatible object store), with metadata, cover art, and SHA-256 duplicate detection handled automatically; nothing is uploaded to a third party
• Self-host in one command — docker compose up brings up the app and database together with hardened container defaults; a live demo runs the exact same image
• Built in the open — full open-source governance: contributor license agreement, code of conduct, contributing guide, security policy, CI, and dependency scanning

Technical Details

The stack is deliberately boring where it should be and interesting where it matters:

• Backend: Java 17 and Spring Boot 3 — Spring Web, Spring Security, Spring Data MongoDB, WebSocket (STOMP over SockJS), validation, and mail
• Database: MongoDB, with a weighted full-text index for search and aggregation pipelines powering library stats and listening history
• Auth & security: session and JWT auth (short-lived access tokens with refresh-token rotation and blacklisting), account lockout, email verification and password reset with hashed one-time tokens, CSRF protection, a strict Content-Security-Policy, path-traversal and symlink guards, and pluggable rate limiting (in-memory or Redis-backed for multi-instance deployments)
• Playback: in-browser player with HTTP Range seeking, crossfade and gapless playback, an “Up Next” queue synced across devices over WebSocket, OS-level Media Session controls, and optional on-the-fly FLAC/M4A→MP3 transcoding via ffmpeg
• Smart-playlist engine: a custom parser for the query DSL with cycle detection and depth guards on @phrase expansion, dry-run previews, and “materialize” to snapshot a query into a static playlist
• Frontend: server-rendered Thymeleaf plus vanilla JavaScript and Bootstrap 5.3 — no SPA framework — with DOM virtualization for libraries of 10,000+ tracks, dual jukebox/light themes, and a full Progressive Web App (installable, service-worker cached, offline fallback)
• Observability: Prometheus metrics via Micrometer, structured logging with correlation IDs, a dedicated audit log for security-sensitive actions, RFC 7807 problem-detail error responses, and versioned (/api/v1/) endpoints documented with OpenAPI/Swagger
• Delivery: Docker and Docker Compose with hardened containers, GitHub Actions CI, dependency scanning, and an Astro + Tailwind marketing site deployed to GitHub Pages

Results

Stellar Grooves is live, open source, and self-hostable today — a Stellar Ideas LLC product that doubles as a public showcase of how we build server software:

• Open source under AGPL-3.0 — anyone can read the code, run it, and contribute, with the governance in place to accept those contributions
• Run it yourself in minutes — a single docker compose up stands up the whole stack, hardened by default; a public demo runs the same build
• A genuinely new idea, shipped — shareable smart-playlist queries are the product’s signature, not a checkbox feature
• Production-grade where it counts — real auth, rate limiting, audit logging, metrics, and accessibility, not a weekend prototype
• Managed hosting on the way — for people who want the app without running a server, a managed option is in the works (waitlist open)

It’s the clearest proof in our portfolio of how we approach Java web applications — and that we hold our own open-source work to the same bar as client work.

Explore the code on GitHub, try the live demo, or learn more at stellargrooves.com.