A self hosted music streaming server
Black Candy is a self hosted music streaming server built with Rails and Hotwire. The goal of the project is to create a real personal music center.
Screenshot Try The DemoPlease visit https://demo.blackcandy.org and use demo user (email: admin@admin.com, password: foobar) to login. And feel free to try it.
InstallationNotice: This demo user does not have administrator privileges. So you cannot experience all the features in Black Candy. And all music in the demo is under non-commercial licences. You can check their licences.
⚠️ Notice: This installation instruction is for edge version, which means the docker image is build base on master branch. Because upcoming major version of Black Candy is going to have a lot of infrastructure changes. So the installation process will have a lot of difference. If you are looking for installation instruction for latest stable version, please visit here.
Black Candy use docker image to install easily. You can simply run Black Candy like this.
docker run ghcr.io/blackcandy-org/blackcandy:edge
That's all. Now, you can use initial admin user to login (email: admin@admin.com, password: foobar).
Mobile AppBlack Candy now has an iOS app in beta. You can visit here and join TestFlight to give it a try. Because this iOS app still in beta, you need use the edge version of Black Candy.
Configuration Port MappingBlack Candy exports the 3000 port. If you want to be able to access it from the host. You can add -p 3000:3000
to the arguments of docker run command and then access either http://localhost:3000 or http://host-ip:3000 in a browser.
docker run -p 3000:3000 ghcr.io/blackcandy-org/blackcandy:edgeMedia Files Mounts
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:edgeUse PostgreSQL As Database
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:edgeHow to Persist Data
There are two parts of data that need to persist in Black Candy. First it's the data from the database if you are using SQLite as database, which is stored in /app/storage
, second it's the data from the asset of media files, which is stored in /app/public/uploads
.
,s
mkdir storage_data mkdir uploads_data docker run -v ./storage_data:/app/storage -v ./uploads_data:/app/public/uploads ghcr.io/blackcandy-org/blackcandy:edgeEnhance With Redis
By default, Black Candy use async adapter for background job and WebSockets, and use file storage for cache. It maybe not have problem when your music library isn't large or doesn't have many users to use it. But you can use Redis to enhance the experience for Black Candy.
When you have set the REDIS_URL
environment variable, black candy will use Sidekiq for background job, Redis adapter for WebSockets and use Redis to store cache. In another way, you can also use REDIS_SIDEKIQ_URL
, REDIS_CABLE_URL
, and REDIS_CACHE_URL
to set those service separately.
docker run -e REDIS_URL=redis://yourredisurl ghcr.io/blackcandy-org/blackcandy:edgeNginx To Send File
Black Candy supports use Nginx to delivery audio file to client. It's a more effective way than handle by Black Candy backend. And Black Candy docker image are also ready for nginx-proxy, which means you can setup a Nginx proxy for Black Candy easily. I recommend you use nginx-proxy with Black Candy.
You can use docker-compose to setup those services. The docker-compose.yml file looks like this:
version: '3' services: nginx-proxy: image: nginxproxy/nginx-proxy ports: - "80:80" volumes: - ./blackcandy.local:/etc/nginx/vhost.d/blackcandy.local:ro - /var/run/docker.sock:/tmp/docker.sock:ro - /media_data:/media_data # Keep the path of media files in container same as blackcandy container. app: image: ghcr.io/blackcandy-org/blackcandy:edge volumes: - ./storage_data:/app/storage - ./uploads_data:/app/public/uploads - /media_data:/media_data environment: VIRTUAL_HOST: blackcandy.local MEDIA_PATH: /media_data NGINX_SENDFILE: "true" # Don't forget to set `NGINX_SENDFILE` environment variable to true to enable nginx sendfile.
# Get the default sendfile config for blackcandy. This file need to mount to nginx proxy container to add custom configuration for nginx. curl https://raw.githubusercontent.com/blackcandy-org/black_candy/master/config/nginx/sendfile.conf > blackcandy.local docker-compose upEmbedded Sidekiq
By default, you need another process to run Sidekiq for background job. Like this:
version: '3' services: app: &app_base image: ghcr.io/blackcandy-org/blackcandy:edge volumes: - ./storage_data:/app/storage - ./uploads_data:/app/public/uploads - /media_data:/media_data sidekiq: <<: *app_base command: bundle exec sidekiq
But you can also use embedded mode of Sidekiq if you don't want another separate Sidekiq process. This can help your deployment become easier.
All you need to do is to set EMBEDDED_SIDEKIQ
environment variable to true.
Listener for media library can automatically sync for media library changes. You need another process to run the listener.
version: '3' services: app: &app_base image: ghcr.io/blackcandy-org/blackcandy:edge volumes: - ./storage_data:/app/storage - ./uploads_data:/app/public/uploads - /media_data:/media_data listener: <<: *app_base command: bundle exec rails listen_media_changesLogging
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/.
Pull new image from remote
$ docker pull ghcr.io/blackcandy-org/blackcandy:edgeDevelopment Requirements
Make sure you have installed all those dependencies.
Install gem dependenciesbundle installInstall JavaScript dependencies
yarn installDatabase Configuration
rails db:prepare rails db:seedStart all services
After you’ve set up everything, now you can running ./bin/dev
to start all service you need to develop.
Then visit http://localhost:3000 use initial admin user to login (email: admin@admin.com, password: foobar).
# Running all test $ rails test:all # Running lint $ rails lint:allIntegrations
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.
Licences Of The Music In DemoKurt Vile - Live at WFMU on Talk's Cheap 8/11/2008 (licensed under Attribution-NonCommercial-ShareAlike 3.0)
Wooden Shjips - Live at ATP NY 2008 (licensed under Attribution-Noncommercial-No Derivative Works 3.0 United States)
Ty Segall - Live at WFMU on The Cherry Blossom Clinic with Terre T June 25, 2011 (licensed under Attribution-Noncommercial-No Derivative Works 3.0 United States)
Thee Oh Sees - Peanut Butter Oven EP (licensed under Attribution-Noncommercial-Share Alike 3.0 United States)
If you like their music, you can buy their albums to support them.
SponsorshipThis project is supported by:
Twice a month we will interview people behind open source businesses. We will talk about how they are building a business on top of open source projects.
We'll never share your email with anyone else.