ProductPromotion
Logo

Open.Source

made by https://0x3d.site

GitHub - blackcandy-org/blackcandy: A self hosted music streaming server
A self hosted music streaming server. Contribute to blackcandy-org/blackcandy development by creating an account on GitHub.
Visit Site

GitHub - blackcandy-org/blackcandy: A self hosted music streaming server

GitHub - blackcandy-org/blackcandy: A self hosted music streaming server

Black Candy

CI Coverage Status Ruby Style Guide Docker Pulls

Screenshot

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

Try The Demo

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

[!NOTE] This demo user does not have administrator privileges. So you cannot experience all the features in Black Candy. And all music in the demo are from Free Music Archive. You can check their licenses.

Installation

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

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

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

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

Upgrade

[!IMPORTANT] If you upgrade to a major version, you need to read the upgrade guide carefully before upgrade. Because there are some breaking changes in a major version.

  • See V3 Upgrade for upgrade from V2 release.
  • See Edge Upgrade for upgrade from edge release to latest stable release.

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

Mobile Apps

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

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

Configuration

Port Mapping

Black Candy exports the 3000 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:3000 ghcr.io/blackcandy-org/blackcandy:latest

Media 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:latest   

Use 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:latest 

How to Persist Data

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 

Nginx To Send File

Black Candy supports use Nginx to delivery audio file to the client. It's a more effective way than handled by Black Candy backend. And Black Candy docker image is also ready for nginx-proxy, which means you can set up a Nginx proxy for Black Candy easily.

You can use docker-compose to set up 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 the same as blackcandy container.

  app:
    image: ghcr.io/blackcandy-org/blackcandy:latest 
    volumes:
      - ./storage_data:/app/storage
      - /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/blackcandy/v3.0.0/config/nginx/sendfile.conf > blackcandy.local

docker-compose up

Logging

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/.

Environment Variables

Name Default Description
DB_URL The URL of PostgreSQL database. You must set this environment variable if you use PostgreSQL as database.
MEDIA_PATH You can use this environment variable to set media path for Black Candy, otherwise you can set media path in settings page.
DB_ADAPTER "sqlite" There are two adapters are supported, "sqlite" and "postgresql".
NGINX_SENDFILE false Whether enable Nginx sendfile.
SECRET_KEY_BASE When the SECRET_KEY_BASE environment variable is not set, Black candy will generate SECRET_KEY_BASE environment variable every time when service start up. This will cause old sessions invalid, You can set your own SECRET_KEY_BASE environment variable on docker service to avoid it.
FORCE_SSL false Force all access to the app over SSL.
DEMO_MODE false Whether to enable demo mode, when demo mode is on, all users cannot access administrator privileges, even user is admin. And also users cannot change their profile.

Edge Version

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

Development

Requirements

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

Make sure you have installed all those dependencies.

Install gem dependencies

bundle install

Install JavaScript dependencies

npm install

Database Configuration

rails db:prepare
rails db:seed

Start all services

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: [email protected], password: foobar).

Running tests

# Running all test
$ rails test:all 

# Running lint
$ rails lint:all

Integrations

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.

Sponsorship

This project is supported by:

Articles
to learn more about the open-source concepts.

Resources
which are currently available to browse on.

mail [email protected] to add your project or resources here 🔥.

FAQ's
to know more about the topic.

mail [email protected] to add your project or resources here 🔥.

Queries
or most google FAQ's about Open-Source.

mail [email protected] to add more queries here 🔍.

More Sites
to check out once you're finished browsing here.

0x3d
https://www.0x3d.site/
0x3d is designed for aggregating information.
NodeJS
https://nodejs.0x3d.site/
NodeJS Online Directory
Cross Platform
https://cross-platform.0x3d.site/
Cross Platform Online Directory
Open Source
https://open-source.0x3d.site/
Open Source Online Directory
Analytics
https://analytics.0x3d.site/
Analytics Online Directory
JavaScript
https://javascript.0x3d.site/
JavaScript Online Directory
GoLang
https://golang.0x3d.site/
GoLang Online Directory
Python
https://python.0x3d.site/
Python Online Directory
Swift
https://swift.0x3d.site/
Swift Online Directory
Rust
https://rust.0x3d.site/
Rust Online Directory
Scala
https://scala.0x3d.site/
Scala Online Directory
Ruby
https://ruby.0x3d.site/
Ruby Online Directory
Clojure
https://clojure.0x3d.site/
Clojure Online Directory
Elixir
https://elixir.0x3d.site/
Elixir Online Directory
Elm
https://elm.0x3d.site/
Elm Online Directory
Lua
https://lua.0x3d.site/
Lua Online Directory
C Programming
https://c-programming.0x3d.site/
C Programming Online Directory
C++ Programming
https://cpp-programming.0x3d.site/
C++ Programming Online Directory
R Programming
https://r-programming.0x3d.site/
R Programming Online Directory
Perl
https://perl.0x3d.site/
Perl Online Directory
Java
https://java.0x3d.site/
Java Online Directory
Kotlin
https://kotlin.0x3d.site/
Kotlin Online Directory
PHP
https://php.0x3d.site/
PHP Online Directory
React JS
https://react.0x3d.site/
React JS Online Directory
Angular
https://angular.0x3d.site/
Angular JS Online Directory