Black Candy
Self-hosted music streaming server, your personal music center
Alternative to: spotify, apple music, plex
Black Candy is a self-hosted music streaming server for your own music library, with a clean web player and native mobile apps for iOS, Android, and F-Droid. It scans and organizes your local audio files, streams them to any browser or device, and supports multi-user access, playlists, and a full-featured admin panel, all deployable via Docker.
Black Candy Docker Compose example
Self-host Black Candy on your own server, homelab, or VPS starting from this Docker Compose example.
It runs Black Candy in Docker containers using the official ghcr.io/blackcandy-org/blackcandy:latest image, with persistent volumes and automatic restarts preconfigured.
Review the environment variables and adjust them to your setup, save the file as compose.yml (or docker-compose.yml), and start the stack with docker compose up -d.
services:
app:
image: ghcr.io/blackcandy-org/blackcandy:latest
restart: unless-stopped
volumes:
- storage:/rails/storage
- media:/media_data
environment:
# Secret used to encrypt sessions and other security-sensitive data. Generate one with `openssl rand -hex 64`. If left unset, Black Candy generates a new value on every restart, which invalidates all existing sessions.
SECRET_KEY_BASE: "changeme"
# Path inside the container where Black Candy looks for your music library. Files placed in the "media" volume are served from here; the media path can also be changed later from the web settings page.
MEDIA_PATH: "/media_data"
# Database adapter to use: "sqlite" (default, self-contained, stored in the storage volume) or "postgresql".
DB_ADAPTER: "sqlite"
# Force all access to the app over SSL/HTTPS. Leave "false" when TLS is terminated by an upstream reverse proxy.
FORCE_SSL: "false"
volumes:
storage:
media:
Values set to changeme are required — replace them with your own
values before starting Black Candy.
Prefer a managed setup? WinterFlow installs, configures, and updates Black Candy for you using this same Docker Compose configuration.