{"id":9456313,"url":"https://github.com/blackcandy-org/blackcandy","last_synced_at":"2026-05-04T09:02:56.471Z","repository":{"id":38373647,"uuid":"120575426","full_name":"blackcandy-org/blackcandy","owner":"blackcandy-org","description":"A self hosted music streaming server","archived":false,"fork":false,"pushed_at":"2025-05-08T13:58:59.000Z","size":11798,"stargazers_count":3580,"open_issues_count":34,"forks_count":178,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-08T14:39:18.940Z","etag":null,"topics":["audio","hotwire","music","music-player","music-streaming","musicplayer","rails","ruby","self-hosted"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackcandy-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-02-07T06:51:06.000Z","updated_at":"2025-05-08T13:59:03.000Z","dependencies_parsed_at":"2023-09-22T19:37:21.771Z","dependency_job_id":"8fc15e33-8861-45ee-b6e1-638462646d11","html_url":"https://github.com/blackcandy-org/blackcandy","commit_stats":{"total_commits":683,"total_committers":6,"mean_commits":"113.83333333333333","dds":"0.040995607613469986","last_synced_commit":"dd86df5281f47c052b55649b1554c5c477bc39cb"},"previous_names":["aidewoode/black_candy","blackcandy-org/blackcandy","blackcandy-org/black_candy"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackcandy-org%2Fblackcandy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackcandy-org%2Fblackcandy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackcandy-org%2Fblackcandy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackcandy-org%2Fblackcandy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackcandy-org","download_url":"https://codeload.github.com/blackcandy-org/blackcandy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","hotwire","music","music-player","music-streaming","musicplayer","rails","ruby","self-hosted"],"created_at":"2024-05-11T14:18:24.086Z","updated_at":"2026-05-04T09:02:56.465Z","avatar_url":"https://github.com/blackcandy-org.png","language":"Ruby","funding_links":[],"categories":["Software","Ruby","Apps","Uncategorized","Media Streaming"],"sub_categories":["Media Streaming - Audio Streaming","MediaManagement","Uncategorized","Audio Streaming"],"readme":"\u003cp align='center'\u003e\n  \u003cimg alt='Black Candy logo' width='200' src='https://raw.githubusercontent.com/blackcandy-org/black_candy/master/app/assets/images/logo.svg'\u003e\n\u003c/p\u003e\n\n# Black Candy\n[![CI](https://github.com/blackcandy-org/black_candy/actions/workflows/ci.yml/badge.svg)](https://github.com/blackcandy-org/black_candy/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/blackcandy-org/blackcandy/badge.svg?branch=master)](https://coveralls.io/github/blackcandy-org/black_candy?branch=master)\n![Docker Pulls](https://img.shields.io/docker/pulls/blackcandy/blackcandy)\n\n![Screenshot](https://raw.githubusercontent.com/blackcandy-org/blackcandy/master/docs/images/screenshot_main.png)\n\nBlack Candy is a self-hosted music streaming server, your personal music center.\n\n## Try The Demo\n\nPlease visit \u003chttps://demo.blackcandy.org\u003e and use demo user (email: admin@admin.com, password: foobar) to log in. And feel free to try it.\n\n\u003e [!NOTE]\n\u003e 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](https://freemusicarchive.org/). You can check their [licenses](https://github.com/blackcandy-org/blackcandy/blob/master/docs/demo_music_licenses.md).\n\n## Installation\n\nBlack Candy uses docker image to install easily. You can run Black Candy like this.\n\n```shell\ndocker run -p 80:80 ghcr.io/blackcandy-org/blackcandy:latest \n\n# Or pull from Docker Hub.\ndocker run -p 80:80 blackcandy/blackcandy:latest \n```\n\nThat'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).\n\n## Upgrade\n\n\u003e [!IMPORTANT]\n\u003e If you upgrade to a new version, you need to read the upgrade guide carefully before upgrade. Because there are may some breaking changes in a new version.\n\u003e\n\u003e Please Check the [Upgrade Guide](https://github.com/blackcandy-org/blackcandy/blob/master/docs/upgrade.md) for upgrading to a new version \n\nUpgrade Black Candy is pull new image from remote. Then remove an old container and create a new one.\n\n```shell\ndocker pull ghcr.io/blackcandy-org/blackcandy:latest\ndocker stop \u003cyour_blackcandy_container\u003e\ndocker rm \u003cyour_blackcandy_container\u003e\ndocker run \u003cOPTIONS\u003e ghcr.io/blackcandy-org/blackcandy:latest \n```\n\nWith docker compose, you can upgrade Black Candy like this:\n\n```shell\ndocker pull ghcr.io/blackcandy-org/blackcandy:latest\ndocker-compose down\ndocker-compose up\n```\n\n## Mobile Apps\n\nBlack Candy mobile apps are available in the following app stores:\n\n[\u003cimg src=\"https://raw.githubusercontent.com/blackcandy-org/ios/master/images/appstore_badge.png\" alt=\"Get it on App Store\" height=\"50\"\u003e](https://apps.apple.com/app/blackcandy/id6444304071)\n[\u003cimg src=\"https://raw.githubusercontent.com/blackcandy-org/android/master/images/fdroid_badge.png\" alt=\"Get it on F-Droid\" height=\"50\"\u003e](https://f-droid.org/packages/org.blackcandy.android/)\n\n\nFor Android app, you can also download APK from [GitHub Release](https://github.com/blackcandy-org/android/releases/latest)\n\n## Configuration\n\n### Port Mapping\n\nBlack 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.\n\n```shell\ndocker run -p 3000:80 ghcr.io/blackcandy-org/blackcandy:latest\n```\n\n### Media Files Mounts\n\nYou can mount media files from host to container and use `MEDIA_PATH` environment variable to set the media path for black candy.\n\n```shell\ndocker run -v /media_data:/media_data -e MEDIA_PATH=/media_data ghcr.io/blackcandy-org/blackcandy:latest   \n```\n\n### Use PostgreSQL As Database\n\nBlack 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.\n\n```shell\ndocker run -e DB_ADAPTER=postgresql -e DB_URL=postgresql://yourdatabaseurl ghcr.io/blackcandy-org/blackcandy:latest \n```\n\n### How to Persist Data\n\nAll 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.\n\n```shell\nmkdir storage_data\n\ndocker run -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:latest \n```\n\n### Running as an Arbitrary User\n\nWhen 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.\n\n```shell\ndocker run --user 2000:2000 -v ./storage_data:/app/storage ghcr.io/blackcandy-org/blackcandy:latest \n```\n\n### Logging\n\nBlack 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/.\n\n## Environment Variables\n\n| Name                         | Default   | Description                                                                                                                                                                                                                                                                               |\n| ---                          | ---       |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| DB_URL                 |           | The URL of PostgreSQL database. You must set this environment variable if you use PostgreSQL as database.                                                                                                                                                                                 |\n| CABLE_DB_URL          |           | The URL of Pub/Sub database. You must set this environment variable if you use PostgreSQL as database.                                                                                                                                                                                    |\n| QUEUE_DB_URL                 |           | The URL of background job database. You must set this environment variable if you use PostgreSQL as database.                                                                                                                                                                             |\n| CACHE_DB_URL                 |           | The URL of cache database. You must set this environment variable if you use PostgreSQL as database.                                                                                                                                                                                      |\n| MEDIA_PATH                   |           | You can use this environment variable to set media path for Black Candy, otherwise you can set media path in settings page.                                                                                                                                                               |\n| DB_ADAPTER             | \"sqlite\"  | There are two adapters are supported, \"sqlite\" and \"postgresql\".                                                                                                                                                                                                                          |\n| 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. |\n| FORCE_SSL                    | false     | Force all access to the app over SSL.                                                                                                                                                                                                                                                     |\n| 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.                                                                                                                      |\n\n## Edge Version\n\nThe 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.\n\n```shell\ndocker pull ghcr.io/blackcandy-org/blackcandy:edge\n```\n\n## Development\n\n### Requirements\n\n- Ruby 4.0 \n- Node.js 20\n- libvips\n- FFmpeg\n\nMake sure you have installed all those dependencies.\n\n### Install gem dependencies\n\n```shell\nbundle install\n```\n\n### Install JavaScript dependencies\n\n```shell\nnpm install\n```\n\n### Database Configuration\n\n```shell\nrails db:prepare\nrails db:seed\n```\n\n### Start all services\n\nAfter you’ve set up everything, now you can run `./bin/dev` to start all services you need to develop.\nThen visit \u003chttp://localhost:3000\u003e use initial admin user to log in (email: admin@admin.com, password: foobar).\n\n### Running tests\n\n```shell\n# Running all test\n$ rails test:all \n\n# Running lint\n$ rails lint:all\n```\n\n## Integrations\n\nBlack 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.\n\n## Sponsorship\n\nThis project is supported by:\n\n\u003ca href=\"https://www.jetbrains.com/community/opensource\"\u003e\u003cimg src=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jb_square.svg\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackcandy-org%2Fblackcandy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackcandy-org%2Fblackcandy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackcandy-org%2Fblackcandy/lists"}