Skip to main content

How to install Koel, an opensource music streaming app

koel logoKoel is an opensource web based music streaming server, similar to Subsonic or Sonerezh, written in Vue (client side) and Laravel (Server side), and is based on latest technologies (HTML5, ES6 etc…).


You will need PHP 5.6 at least, while the new v7 as been extensively tested and works great!

Koel is simple with a modern design and is mobile responsive. Simply specify where your songs are and it will scan your specified folder(s)


koel main

The strength of Koel relies probably in its extensive API and the fact that is have been built for developers. You will be able to select different ways to stream (PHP? x-sendfile? x-accel-redirect?).

You will probably feel quite at home if you use Spotify since, its interface is indeed of copy of it.

The best is to let you try it with their demo.

Interested to give it a shot, here is how to install koel on your server (Debian in my case)



1) Get PHP 5.6 or later

Before to start, you’ll need to check your PHP version and ensure you have PHP 5.6 or above. To know it, simply run:

If your distribution is too old (My virtualmachine is on Wheezy), you will need to modify your sources.list to add new repo. If you want to get the PHP 5.6, run the following:


2) Install nodejs and npm on your system if not done already

– If you use Ubuntu or a recent version of Debian (>Jessie), simple run (as root)

– For Debian users still on Wheezy (Time to dist-upgrade!), you can install nodejs from wheezy-backports. If you don’t have them in your source.list, you will need to add the line

to your /etc/apt/source.list file, then run

to update the packages list and then install nodejs with the following command:

and for npm, you can use the installer (still in root)


3) Clone their git repository
4) Install composer and use NPM to manage  dependencies

You will need to run:

This will download from github all the needed dependencies. But since you will download a lot of dependencies from them, you will need to register and create a Token to go over the API limit. At certain point of time, you will need to enter it. Check Github doc for the detail.


5) Create a database and update the conf file

To run koel, you will need to create a database (Either MySQL, PGSQL or Microsoft SQL). I’ll be using MySQL and you can easily create a database with phpmyadmin for example.

Once done, edit the configuration file to fill in your database credentials and the initial admin account

You can actually configure many settings in the file (default bitrate output, etc…). Feel free to adapt the default configuration to your system and needs.

6) Initialize the instance
This will use npm to do the final installations.


7) Launch the instance

Still in root (or with sudo), simply run:

And you should be able to access to your new Koel instance through http://localhost:8000

If you want to access through your local network or a public IP, run instead:

And you’re good!

koel - login

If you have any questions, feel free to check their issue tracker on github.

Leave a Reply

Your email address will not be published. Required fields are marked *