Polaris

Polaris is a lightweight, high‑performance self‑hosted music streaming server written in Go. The core binary exposes a RESTful API documented with OpenAPI and serves a modern single‑page web UI built on React (via Vite) that communicates with the server over HTTPS. The architecture is intentionally minimalistic: a single binary, an optional PostgreSQL or SQLite database for metadata persistence, and a file‑system based storage layer that streams audio directly from disk. This design eliminates the need for external services, making Polaris ideal for developers who want full control over their media stack.

Architecture & Technical Stack

• Language & Runtime: Go 1.22+ – the server compiles to a statically linked binary, simplifying deployment across Linux, Windows, BSD, and Docker containers.
• Web Framework: net/http with a lightweight router (chi) that supports middleware for authentication, rate limiting, and CORS.
• Database: Supports PostgreSQL (recommended for large collections) or SQLite for single‑user setups. The schema is generated via Go structs and managed with a lightweight migration tool (sqlc).
• Audio Processing: Uses the ffmpeg CLI for transcoding on‑demand and generating waveform data. Audio metadata extraction is performed with mediainfo.
• Storage: Files are served via a range‑based HTTP handler that supports byte‑range requests, enabling efficient streaming and resume functionality.
• Authentication: JWT‑based tokens with support for multiple user accounts, each having isolated playlists and permissions.

Core Capabilities & APIs

Polaris exposes a comprehensive OpenAPI spec that includes endpoints for:

• Library Management: /albums, /artists, /tracks – CRUD operations, bulk import from a directory tree, and metadata enrichment.
• Playback: /stream/{track_id} – supports HTTP range requests and optional transcoding parameters (audio_format, bitrate).
• User & Playlist: /users, /playlists – create, update, delete, and share playlists.
• Search: /search?q=... – field‑specific queries (artist:, genre:) with full‑text indexing powered by PostgreSQL’s pg_trgm.
• Webhooks: Configurable POST endpoints that fire on events such as track_added, playlist_updated.

The API is stateless; clients can cache responses using standard HTTP caching headers. Developers can integrate Polaris into existing services (e.g., as a media backend for home automation or custom mobile apps) by consuming the OpenAPI spec with tools like openapi-generator or swagger-codegen.

Deployment & Infrastructure

Polaris is designed for container‑friendly deployment. The official Docker image (agersant/polaris) is a multi‑stage build that yields a 30 MB Alpine image. Kubernetes manifests are provided in the deploy/helm directory, enabling easy Helm chart installation with configurable resource limits and persistence volumes. For bare‑metal or VM deployments, the single binary can be run under systemd or as a Docker container with bind mounts for the music directory and database socket.

Scalability is achieved through:

• Horizontal scaling: Multiple Polaris instances can share a single PostgreSQL database and a distributed file system (e.g., NFS, Ceph) for the music library. Load balancers route requests to healthy instances.
• Caching: The server implements an in‑memory LRU cache for metadata queries and waveform blobs, reducing disk I/O under load.
• Statelessness: Since the API is stateless, autoscaling policies can spin up new pods on demand without session affinity concerns.

Integration & Extensibility

Polaris is intentionally extensible:

• Plugins: A Go plugin system allows developers to write shared object modules that hook into the request lifecycle (e.g., custom authentication, metadata enrichment).
• Webhooks & Callbacks: External services can subscribe to events via configurable webhooks, enabling integration with media libraries like Plex or Home Assistant.
• Custom UI Themes: The React front‑end exposes a theme API; developers can override CSS variables or supply their own component overrides.
• CLI Tools: A bundled CLI (polaris-cli) offers scripting capabilities for bulk import, metadata correction, and health checks.

Developer Experience

The project follows a clean codebase with comprehensive unit tests (coverage > 80%) and continuous integration via GitHub Actions. Documentation is split into concise modules: docs/SETUP.md for deployment, docs/CONFIGURATION.md for advanced settings, and the automatically generated OpenAPI docs. Community support is active on GitHub Discussions, with a dedicated channel for plugin development and feature requests.

Use Cases

• Home Media Server: Deploy Polaris on a NAS or Raspberry Pi to stream music to all household devices, leveraging the Android client for mobile listening.
• Custom Smart Home Integration: Expose Polaris endpoints to a home automation platform (e.g., Home Assistant) for voice‑controlled playback.
• Open‑Source Media Projects: Use Polaris as the backend for a campus or community radio station, taking advantage of its large‑collection support and waveform visualization.
• Developer Sandbox: Quickly spin up a Polaris instance in Docker Compose for testing audio streaming features in a CI pipeline.

Advantages Over Alternatives