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

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

Please visit https://demo.blackcandy.org and use the demo user (email: admin@admin.compassword: foobar) to log in.

Black Candy uses docker images for easy installation. 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 visit http://localhost:3000 or http://hostip:3000 In a browser and log in with the original admin user (email: admin@admin.compassword: foobar).

Upgrading Brown Sugar is pulling new images from the remote end. Then delete the 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 

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

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

The Black Candy mobile app can be found in the following app stores:

For Android apps, you can also download the APK from GitHub releases

Black Candy outputs port 3000. If you want to be able to access it from the host, you can use -p Options for mapping ports.

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

You can mount media archives from the host to the container and use MEDIA_PATH Set the environment variables for the Black Candy media path.

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

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

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

All data that needs to be persisted in Black Candy is stored in /app/storageso you can mount this directory to the host to persist data.

mkdir storage_data

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

Black Candy supports using Nginx to send audio files to the client. This is a more efficient method than Black Candy’s backend processing. Black Candy docker image is also ready nginx proxywhich means you can easily configure the Nginx proxy for Black Candy.

You can use docker-compose to configure these 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

Brown Sugar Login STDOUT By default. So if you want to control logging, Docker already supports many options for handling logging in containers. look: https://docs.docker.com/config/containers/logging/configure/.

The marginal version of Black Candy is based on the master branch, which means it is unstable and you may encounter data loss or other issues. However, I wouldn’t recommend the edge version for general users. But if you are a developer who wants to test Black Candy or contribute to Black Candy, you can use the edge version.

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

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

Make sure you have all these dependencies installed.

rails db:prepare
rails db:seed

With everything set up, it’s now time to run ./bin/dev Start all services you need to develop. Then visit http://localhost:3000 Log in with the original admin user (email: admin@admin.compassword: foobar).

# Running all test
$ rails test:all 

# Running lint
$ rails lint:all

Black Candy supports retrieving artist and album images from the Discogs API. You can create an API token from Discogs and enable it by setting the Discogs token on the settings page.

This project is supported by: