Deploy Black Candy
Self-hosted music streaming server with web player and mobile apps
Just deployed
/var/lib/postgresql/data
Black Candy
Just deployed
/data
Deploy and Host Black Candy on Railway
Black Candy is a free, open-source (MIT) self-hosted music streaming server. It scans a folder of your music files, reads their tags and cover art, and gives you a web player with albums, artists, playlists, favorites and search, plus iOS and Android apps. It can transcode lossless files for mobile listening.
About Hosting Black Candy
Hosting Black Candy means running its Rails web app with background jobs, a database, and storage for your music that survives restarts. This template builds Black Candy 3.2.2 from the official image, pinned by digest, through a public GitHub repo, so new releases reach you as Railway update notices. Railway Postgres holds the library, users and job queue, and one volume holds your music and cover art. Upstream's default admin@admin.com / foobar account is replaced on first boot by your admin email and a generated password. It runs in about 0.3 GB of RAM, so it fits Railway's Free plan.
Common Use Cases
- Stream your own music collection from any browser, without a subscription
- Listen on your phone with the Black Candy iOS and Android apps, connected to your Railway URL
- Share one music library with family or friends, each with their own account and playlists
Dependencies for Black Candy Hosting
- PostgreSQL (Railway's Postgres service, included)
- A volume for your music and cover art (mounted at
/data, included)
Deployment Dependencies
- Black Candy: https://github.com/blackcandy-org/blackcandy
- Release deployed by this template: https://github.com/blackcandy-org/blackcandy/releases/tag/v3.2.2
- Upgrade guide: https://github.com/blackcandy-org/blackcandy/blob/master/docs/upgrade.md
- Template source (Dockerfile and start script): https://github.com/aalfath/blackcandy-railway-template
Implementation Details
Services:
- Black Candy: web UI, API and audio streaming on your public domain (health check
/up). Background jobs such as library sync run in the same container. The volume at/dataholds/data/music(your library) and/data/storage(cover art). - Postgres: the main database. On first boot the start script creates three companion databases on the same server for Black Candy's cache, live updates and job queue.
After the deploy:
- Open the Black Candy service's Variables tab and copy
BLACKCANDY_ADMIN_PASSWORD. Sign in at your Railway domain withBLACKCANDY_ADMIN_EMAIL(defaultadmin@example.com, which you can change at deploy) and that password. Change the password later under Update Profile. A redeploy never resets it. - Upload music with the Railway CLI. Paths start at the volume root:
railway volume files upload ./My-Album /music/My-Album - In Black Candy, open Settings and click Sync. The media path is already
/data/music.
Optional: add a Discogs token in Settings for artist and album images, and add users under Users. To update, apply Railway's update notice after you read the repo's CHANGELOG.md, and back up the volume and database first.
Why Deploy Black Candy on Railway?
Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.
By deploying Black Candy on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.
Template Content
