Black Candy

Black Candy is an open-source, self-hosted music streaming server designed for managing and playing personal music collections. It functions as a central hub for audio files, allowing users to organize their library and stream content through a web browser or dedicated mobile applications. The software is deployed as a server application, primarily via Docker containers, which simplifies the installation and update process for users of various technical levels.

The application allows for the mounting of local media directories from a host machine to the container, ensuring that the music library remains independent of the application installation. This setup enables users to maintain their file structure on the host system while the server handles the streaming and metadata management. Users can access the interface via standard web ports or map them to custom ports to fit their network configuration.

Key features

• Support for SQLite and PostgreSQL databases
• Dedicated mobile applications for Android
• Custom media path configuration via environment variables
• Persistent data storage for user settings and library metadata
• SSL enforcement option for secure connections
• Session protection using a configurable secret key base
• Integration with Docker and Docker Compose for deployment

Built with Ruby on Rails and Hotwire, the application is designed for users who prefer to maintain full control over their media files. It provides an administrative interface for system configuration and user management. The architecture allows for flexible database selection, making it suitable for both small home setups using SQLite and larger deployments requiring PostgreSQL. To ensure stability during updates, the system supports a structured upgrade path through Docker image pulls and container recreation.

Black Candy serves as a private audio streaming solution for individuals hosting their own music libraries on their own hardware.