Black Candy is a self-hosted music streaming server, your personal music center.

Please visit https://demo.blackcandy.org and use demo user (email: admin@admin.com, password: foobar) to log in. And feel free to try it.

Black Candy uses docker image to install easily. You can run Black Candy like this.

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

# Or pull from Docker Hub.
docker run -p 80:80 blackcandy/blackcandy:latest 

That's all. Now, you can access either http://localhost or http://host-ip in a browser, and use initial admin user to log in (email: admin@admin.com, password: foobar).

Upgrade Black Candy is pull new image from remote. Then remove an old container and create a new one.

docker pull ghcr.io/blackcandy-org/blackcandy:latest
docker stop <your_blackcandy_container>
docker rm <your_blackcandy_container>
docker run <OPTIONS> ghcr.io/blackcandy-org/blackcandy:latest 

With docker compose, you can upgrade Black Candy like this:

docker pull ghcr.io/blackcandy-org/blackcandy:latest
docker-compose down
docker-compose up

Black Candy mobile apps are available in the following app stores:

For Android app, you can also download APK from GitHub Release

Black Candy exports the 80 port. If you want to be able to access it from the host, you can use the -p option to map the port.

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

You can mount media files from host to container and use MEDIA_PATH environment variable to set the media path for black candy.

docker run -v /media_data:/media_data -e MEDIA_PATH=/media_data ghcr.io/blackcandy-org/blackcandy:latest   

Black Candy use SQLite as database by default. Because SQLite can simplify the process of installation, and it's an ideal choice for self-hosted small server. If you think SQLite is not enough, or you are using some cloud service like heroku to host Black Candy, you can also use PostgreSQL as database.

docker run -e DB_ADAPTER=postgresql -e DB_URL=postgresql://yourdatabaseurl ghcr.io/blackcandy-org/blackcandy:latest 

All the data that need to persist in Black Candy are stored in /app/storage, So you can mount this directory to host to persist data.

mkdir storage_data

docker run -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:latest 

When mounting volumes, you may encounter permission issues between the host and the Docker container. To resolve this issue, pass the UID and GID with the --user to set the same UID and GID as your host user.

docker run --user 2000:2000 -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:latest 

Black Candy logs to STDOUT by default. So if you want to control the log, Docker already supports a lot of options to handle the log in the container. See: https://docs.docker.com/config/containers/logging/configure/.

The edge version of Black Candy base on master branch, which means it's not stable, you may encounter data loss or other issues. However, I don't recommend normal user using an edge version. But if you are a developer who wants to test or contribute to Black Candy, you can use the edge version.

docker pull ghcr.io/blackcandy-org/blackcandy:edge

• Ruby 3.4
• Node.js 20
• libvips
• FFmpeg

Make sure you have installed all those dependencies.

bundle install

npm install

rails db:prepare
rails db:seed

After you’ve set up everything, now you can run ./bin/dev to start all services you need to develop. Then visit http://localhost:3000 use initial admin user to log in (email: admin@admin.com, password: foobar).

# Running all test
$ rails test:all 

# Running lint
$ rails lint:all

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

This project is supported by: