---
title: "Deploy Koel"
description: "Self-hosted personal music streaming server with a web player"
category: "Other"
url: https://railway.com/deploy/koel-1
---

# Deploy Koel

Self-hosted personal music streaming server with a web player

**[Deploy Koel on Railway](https://railway.com/template/koel-1)**

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

- **Creator:** Agaz Self-Host
- **Category:** Other
- **Total deploys:** 2

## Template content

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

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

### Koel https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/koel.png

- **Source:** https://github.com/aalfath/koel-railway-template
- **Health check:** /api/ping
- **Public domain:** Yes

## Documentation

# Deploy and Host Koel on Railway

Koel is a free, open-source personal music streaming server. You upload or scan your own music library and listen through a fast web player with playlists, smart playlists, favorites, lyrics, podcasts and an equalizer. It also supports multiple users, Last.fm and Spotify metadata, and Subsonic-compatible mobile apps.

## About Hosting Koel

Hosting Koel means running its PHP web app (Apache with mod_php) next to a database, keeping your music, artwork and search index on persistent storage, and making sure the first admin account is not left on a default password. This template deploys Koel 9.15.0 from the official `phanan/koel` image, pinned by digest, together with Railway's Postgres. A volume at `/data` holds your music, artwork and search index. On every start, Koel's own installer runs migrations, and the first admin gets a generated password instead of the upstream default. Railway provides the HTTPS domain, health check, restarts and private networking.

## Common Use Cases

* Stream your own music collection from any browser, without a subscription
* Share a family or team music library with separate user accounts and playlists
* Listen on your phone through Subsonic-compatible apps, and follow podcasts in the same place

## Dependencies for Koel Hosting

* PostgreSQL (Railway's Postgres service, included)
* A volume for music, artwork and the search index (mounted at `/data`, included)

### Deployment Dependencies

* Koel: https://koel.dev and https://github.com/koel/koel
* Official Docker image and its documentation: https://github.com/koel/docker
* Release deployed by this template: https://github.com/koel/koel/releases/tag/v9.15.0
* Template source (Dockerfile and start script): https://github.com/aalfath/koel-railway-template

### Implementation Details

After the deploy, open the Koel service's Variables tab in Railway and copy `KOEL_ADMIN_PASSWORD`. Log in at your Railway domain with `KOEL_ADMIN_EMAIL` (default `admin@koel.dev`) and that password. You can change both later in Koel's profile page; the template never overwrites a password you have changed.

Add music by uploading songs in Koel's web UI. They are stored under `/data/music`, and Koel rescans that folder daily. Optional integrations go on the Koel service as extra variables: `LASTFM_API_KEY` and `LASTFM_API_SECRET`, `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`, or S3 storage (`STORAGE_DRIVER` and the `AWS_*` settings from Koel's `.env.example`). If you add a custom domain, update `APP_URL` to match it.

Updates: the Koel service builds from the template's GitHub repository. When a new Koel version is pinned there, Railway shows you an "update available" notice, and you choose when to apply it. Read the repository's `CHANGELOG.md` first.

## Why Deploy Koel 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 Koel 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

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — Self-hosted virtual tabletop for role-playing games (license required)
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/koel-1
