---
title: "Deploy Black Candy"
description: "Self-hosted music streaming server with web player and mobile apps"
category: "Storage"
url: https://railway.com/deploy/black-candy
---

# Deploy Black Candy

Self-hosted music streaming server with web player and mobile apps

**[Deploy Black Candy on Railway](https://railway.com/template/black-candy)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/black-candy/manifest.json

- **Creator:** Agaz Self-Host
- **Category:** Storage

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### Black Candy https://raw.githubusercontent.com/blackcandy-org/blackcandy/v3.2.2/app/assets/images/logo.svg

- **Source:** https://github.com/aalfath/blackcandy-railway-template
- **Health check:** /up
- **Public domain:** Yes

## Documentation

# 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 `/data` holds `/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:

1. Open the Black Candy service's Variables tab and copy `BLACKCANDY_ADMIN_PASSWORD`. Sign in at your Railway domain with `BLACKCANDY_ADMIN_EMAIL` (default `admin@example.com`, which you can change at deploy) and that password. Change the password later under Update Profile. A redeploy never resets it.
2. Upload music with the Railway CLI. Paths start at the volume root: `railway volume files upload ./My-Album /music/My-Album`
3. 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.



## Similar templates

- [RustFS | (Just Updated) S3 Object Store, Public URL and Keys Set](https://railway.com/deploy/rustfs-or-just-updated-s3-object-store-p) — S3-compatible object store, keys and public URL preset, volume kept
- [TimescaleDB](https://railway.com/deploy/timescaledb-railway-template) — A PostgreSQL-based time-series database for analytics on Railway.
- [Neo4j 2026.10 Community](https://railway.com/deploy/neo4j-202610-community) — Neo4j graph database with APOC, Browser, Bolt TCP proxy and a volume

Open this page in a browser: https://railway.com/deploy/black-candy
