https://github.com/blackcandy-org/blackcandy Skip to content Navigation Menu Toggle navigation Sign in * Product + GitHub Copilot Write better code with AI + Security Find and fix vulnerabilities + Actions Automate any workflow + Codespaces Instant dev environments + Issues Plan and track work + Code Review Manage code changes + Discussions Collaborate outside of code + Code Search Find more, search less Explore + All features + Documentation + GitHub Skills + Blog * Solutions By company size + Enterprises + Small and medium teams + Startups By use case + DevSecOps + DevOps + CI/CD + View all use cases By industry + Healthcare + Financial services + Manufacturing + Government + View all industries View all solutions * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners + Executive Insights * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} blackcandy-org / blackcandy Public * Notifications You must be signed in to change notification settings * Fork 128 * Star 2.3k A self hosted music streaming server License MIT license 2.3k stars 128 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 18 * Pull requests 3 * Discussions * Actions * Projects 0 * Security * Insights Additional navigation options * Code * Issues * Pull requests * Discussions * Actions * Projects * Security * Insights blackcandy-org/blackcandy master BranchesTags [ ] Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 920 Commits .github/workflows .github/workflows app app bin bin config config db db docker docker docs docs lib lib log log public public screenshots screenshots storage storage test test tmp tmp vendor vendor .dockerignore .dockerignore .erb-lint.yml .erb-lint.yml .gitignore .gitignore .node-version .node-version .ruby-version .ruby-version .standard.yml .standard.yml .stylelintrc .stylelintrc Dockerfile Dockerfile Gemfile Gemfile Gemfile.lock Gemfile.lock LICENSE LICENSE Procfile.dev Procfile.dev README.md README.md Rakefile Rakefile config.ru config.ru package-lock.json package-lock.json package.json package.json View all files Repository files navigation * README * MIT license Black Candy logo 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: admin@admin.com, 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: admin@admin.com, 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 docker rm docker run 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: Get it on App Store Get it on F-Droid 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 The URL of PostgreSQL database. You must set DB_URL this environment variable if you use PostgreSQL as database. You can use this environment variable to set MEDIA_PATH 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. When the SECRET_KEY_BASE environment variable is not set, Black candy will generate SECRET_KEY_BASE environment SECRET_KEY_BASE 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. Whether to enable demo mode, when demo mode DEMO_MODE false 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: admin@admin.com, 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: [68747470733a2f2f6f70656e736] [6874747073] About A self hosted music streaming server Topics audio ruby music rails music-player self-hosted music-streaming musicplayer hotwire Resources Readme License MIT license Activity Custom properties Stars 2.3k stars Watchers 17 watching Forks 128 forks Report repository Releases 9 v3.0.0 Latest May 31, 2024 + 8 releases Packages 0 Contributors 6 * * * * * * Languages * Ruby 61.4% * HTML 18.2% * SCSS 10.4% * JavaScript 9.4% * Other 0.6% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.