sardaukar / black_candy

A self hosted music streaming server

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Black candy logo

Black candy

Build status

Black candy is a self hosted music streaming server built with Rails and Stimulus. The goal of the project is to create a real personal music center.


screenshot theme dark

screenshot theme light

Getting started

Black candy use docker for simplify deployment, development and test process. So you should install docker and docker-compose first.

Black candy support mp3, m4a, ogg, opus, flac and wav formats now.


Black candy has built docker images.

First, you need clone this project to your server.

$ git clone

And checkout to latest version.

$ git checkout v1.0.5

Notice, the git tag you checkout must match with the version that blackcandy docker image you use, otherwise will cause some unexpected issue.

Second, set BLACK_CANDY_MEDIA_PATH and BLACK_CANDY_SECRET_KEY_BASE environment variable on your sever and point BLACK_CANDY_MEDIA_PATH to the readable directory on your server to store your music files.

# Like this
$ export BLACK_CANDY_MEDIA_PATH="/example_media_path"
$ export BLACK_CANDY_SECRET_KEY_BASE="your_secret_key"

Then, you should setup database

$ make production_setup 

Finally run:

$ make production_run

That's all.

You can use initial admin user to login (email:, password: foobar).

You can also change docker-compose.yml for your own needs.

Setup SSL

Black candy can use Let’s Encrypt to get certificate. If you want to enable ssl, you sould make sure your server IP associate with your domain on DNS first.

Then you need set BLACK_CANDY_DOMAIN_NAME and BLACK_CANDY_DOMAIN_EMAIL environment variable on your sever.


Then set ssl certificate

$ make production_set_ssl

After set ssl certificate successfully, you should set BLACK_CANDY_USE_SSL environment variable to true.

$ export BLACK_CANDY_USE_SSL="true"

Finally, restart Black candy

$ make production_restart


Pull new code from remote

$ git pull origin master

And checkout to new version

$ git checkout v1.0.5

Finally run:

$ make production_update 


# Clone the repo
$ git clone

# Setup development environment
$ make dev_setup

# Runing development server
$ make dev_run

# Stop development server
$ make dev_stop

# Into development shell
$ make dev_shell


# Setup test environment
$ make test_setup

# Runing test
$ make test_run

# Runing lint
$ make test_run_lint

# Into test shell
$ make test_shell


Black candy support get artist and album image from Discogs API. You can create a API token from Discogs and set Discogs token on Setting page to enable it.


A self hosted music streaming server

License:MIT License


Language:Ruby 54.0%Language:JavaScript 15.8%Language:HTML 15.6%Language:CSS 13.1%Language:Makefile 0.7%Language:Shell 0.4%Language:Dockerfile 0.4%