blackcandy
Black Candy is a self-hosted music streaming server written in Ruby that lets you run your own personal music center. It provides a web interface and mobile apps (iOS, Android, F-Droid) for streaming music stored on your server, with support for both SQLite and PostgreSQL databases.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | blackcandy-org/blackcandy |
| Owner | blackcandy-org |
| Primary language | Ruby |
| License | MIT — OSI-approved |
| Stars | 4.3k |
| Forks | 216 |
| Open issues | 35 |
| Latest release | v3.2.0 (2026-05-07) |
| Last updated | 2026-07-06 |
| Source | https://github.com/blackcandy-org/blackcandy |
What blackcandy is
Rails-based music streaming application using Hotwire for real-time UI interactions, deployable via Docker with SQLite default or PostgreSQL for scaling. Supports media mounting, configurable ports, and session encryption via SECRET_KEY_BASE.
Get the blackcandy source
Clone the repository and explore it locally.
git clone https://github.com/blackcandy-org/blackcandy.gitcd blackcandy# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Mandatory SECRET_KEY_BASE environment variable setup to persist sessions across restarts; regenerated each startup if not set, invalidating existing user sessions.
- Default SQLite database suitable for small deployments; evaluate PostgreSQL migration if handling concurrent users or requiring independent cache/job/cable DB URLs.
- Media path mounting via Docker volumes required; ensure host directory permissions align with container UID/GID to avoid permission errors on media access.
- Breaking changes noted in upgrade guide; review docs before upgrading between versions to prevent data loss or incompatibility.
- Default admin credentials ([email protected] / foobar) must be changed immediately on first production deployment.
When to avoid it — and what to weigh
- Large-scale multi-tenant deployment — Project is designed for self-hosted single-instance use; production multi-tenant scaling (millions of users) would require significant architectural changes.
- Requirement for commercial SLA or support contract — This is a community-maintained open-source project; no official vendor support, SLA, or commercial agreements are indicated in the data.
- Need for advanced music metadata, recommendations, or AI features — Black Candy focuses on basic streaming; advanced ML features, social recommendations, or music discovery algorithms are not documented.
- Legacy on-premises infrastructure with no Docker/container capability — Primary deployment method is Docker; bare-metal or VM deployments without container support would require custom setup not covered in documentation.
License & commercial use
MIT License (Massachusetts Institute of Technology License). Permissive OSI-approved license allowing use, modification, and distribution with minimal restrictions.
MIT License permits commercial use, modification, and distribution without restriction, provided the license and copyright notice are included. No proprietary components or commercial restrictions are stated in the data. However, verify any mobile app store terms (App Store, Google Play) separately, as platform-specific requirements may apply beyond the MIT license.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
Project uses SECRET_KEY_BASE for session/data encryption; unset variable auto-generates on each startup, invalidating sessions. Default admin credentials must be changed. FORCE_SSL option available. No CVE history, security audit results, or hardening guidelines mentioned in provided data. Review deployment network isolation, Docker image provenance, and dependency vulnerabilities before production use.
Alternatives to consider
Subsonic / Airsonic
Mature Java-based music streaming servers with larger ecosystems, plugin support, and longer history; heavier resource footprint and steeper learning curve than Black Candy.
Funkwhale
Python-based federated audio platform with social features and federation support; more complex deployment but broader content-sharing capabilities beyond personal libraries.
Navidrome
Go-based lightweight music server with Subsonic API compatibility; lower resource use and faster startup, but smaller ecosystem and fewer UI/UX refinements than Black Candy.
Build on blackcandy with DEV.co software developers
Review the installation guide, test the demo instance, and assess SQLite vs. PostgreSQL for your concurrency needs. Plan SECRET_KEY_BASE setup and storage mounting strategy before production deployment.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
blackcandy FAQ
What database should I use, SQLite or PostgreSQL?
How do I upgrade Black Candy without losing data?
Can I access Black Candy from outside my local network?
What audio formats does Black Candy support?
Work with a software development agency
From first prototype to production, DEV.co delivers software development services around tools like blackcandy. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source devops and beyond.
Evaluate Black Candy for Your Music Infrastructure
Review the installation guide, test the demo instance, and assess SQLite vs. PostgreSQL for your concurrency needs. Plan SECRET_KEY_BASE setup and storage mounting strategy before production deployment.