blackcandy

Black Candy is a self-hosted music streaming server described as a personal music center. It is distributed primarily as a Docker image, so installation consists of running a container and mapping a port; the initial admin account uses the email admin@admin.com with password foobar. A public demo instance is available for evaluation, though the demo user lacks administrator privileges and its music comes from the Free Music Archive. Deployment and configuration are handled through environment variables and volume mounts. Media files are mounted from the host and pointed to with MEDIA_PATH. Persistent data lives under /rails/storage, which can be mounted to the host; when permission conflicts arise between host and container, the container can be run as an arbitrary user via --user UID:GID. SQLite is the default database, with PostgreSQL supported through DB_ADAPTER and related connection variables for the main database, Pub/Sub, background jobs and cache. Other documented options include FORCE_SSL, DEMO_MODE, HTTP_PORT, and SECRET_KEY_BASE, the latter used to protect sessions and security-sensitive data; if unset, a new value is generated at each startup, invalidating existing sessions. Logging goes to STDOUT by default. A docker-compose example is provided, and an edge image based on the master branch is offered for testing and contribution, with a warning that it is unstable. Upgrades require pulling a new image and recreating the container; the project explicitly warns users to read the upgrade guide because new versions may contain breaking changes. Mobile clients are listed for iOS via the App Store and for Android via Google Play and F-Droid, with APK downloads from GitHub releases. The project also integrates with the Discogs API so artist and album artwork can be fetched when a Discogs token is configured in the settings page. For development, the documented requirements are Ruby 4.0, Node.js 20, libvips and FFmpeg, with bundle and npm for dependencies, Rails database preparation and seeding, and a ./bin/dev script to start services locally on port 3000. Tests and linting are run through rails test:all and rails lint:all. The repository includes CI and coverage badges and notes sponsorship from JetBrains.