Repolode
Submit
blackcandy-org

blackcandy-org/blackcandy

A self-hosted music streaming server that lets you play your own music library from a web browser or mobile app.

Open-source alternative to:SpotifyApple Music

View on GitHub
Stars
4,428
Forks
228
Open issues
31
Last commit
3 days ago

What is it?

Black Candy is a self-hosted music streaming server built on Ruby on Rails. You point it at a media folder on your machine or server, and it serves that library to a web interface and to official iOS and Android apps.

It is designed for small, personal deployments. SQLite is the default database, so a basic setup needs only a single Docker container, and PostgreSQL can be configured for larger installs. Media files are read from a mounted directory, and data such as settings and the database is kept in a persistent storage path.

The project provides Docker images, a demo instance with sample music, and a development setup that requires Ruby, Node.js, libvips and FFmpeg. Artist and album images can be fetched through the Discogs API once a token is entered in the settings page.

Key features

  • 01Streams music from a media folder you mount into the container.
  • 02Offers a web interface plus official iOS, Android and F-Droid apps.
  • 03Uses SQLite by default and supports PostgreSQL as an alternative.
  • 04Supports admin and regular user accounts, with a demo mode that restricts admin access.
  • 05Fetches artist and album images from the Discogs API.
  • 06Runs as a Docker container with persistent storage and configurable environment variables.

Use cases

  • Hosting a personal music library on a home server and listening from any browser.
  • Running a private music streaming service for a family or small group.
  • Accessing your own collection from phones without relying on a commercial subscription service.
  • Trying out a self-hosted Rails application as a reference for deployment with Docker.

Quick start

  1. 1

    Run Black Candy with Docker from GitHub Container Registry

    docker run -p 80:80 ghcr.io/blackcandy-org/blackcandy:latest
  2. 2

    Open http://localhost in a browser and log in with the initial admin user

Things to know

  • Default database is SQLite; PostgreSQL requires extra environment variables and setup.
  • Media files must be mounted into the container for the server to see your music library.

In collections

Self-hosted apps

Topics

#music#self-hosted#music-streaming#rails#ruby#docker#media-server#audio#hotwire#music-player

FAQ

What is blackcandy?
A self-hosted music streaming server that lets you play your own music library from a web browser or mobile app. Black Candy is a self-hosted music streaming server built on Ruby on Rails. You point it at a media folder on your machine or server, and it serves that library to a web interface and to official iOS and Android apps.
Is blackcandy free to use? What license does it have?
blackcandy is open source under the MIT license. Check the license terms before using it in commercial products.
Is blackcandy still maintained?
Actively maintained. The last commit to blackcandy was on Oct 21, 2026.
What can I use blackcandy for?
Hosting a personal music library on a home server and listening from any browser. Running a private music streaming service for a family or small group. Accessing your own collection from phones without relying on a commercial subscription service. Trying out a self-hosted Rails application as a reference for deployment with Docker.
How do I install blackcandy?
Run Black Candy with Docker from GitHub Container Registry: docker run -p 80:80 ghcr.io/blackcandy-org/blackcandy:latest Open http://localhost in a browser and log in with the initial admin user
Where can I get blackcandy?
The source code and installation instructions are on GitHub: https://github.com/blackcandy-org/blackcandy

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects