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:

php -v

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:

echo "deb wheezy-php56 all" >> /etc/apt/sources.list.d/dotdeb.list
echo "deb-src wheezy-php56 all" >> /etc/apt/sources.list.d/dotdeb.list
wget -O- | apt-key add –
sudo apt-get update
sudo apt-get install php5


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)

apt-get install nodejs npm

– 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

deb wheezy-backports main

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

apt-get update

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

apt-get install nodejs nodejs-legacy curl

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

curl | sh


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

You will need to run:

curl -s | php
mv composer.phar /usr/bin/composer
npm install
composer install
gulp --production

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

nano .env

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
php artisan koel:init

This will use npm to do the final installations.


7) Launch the instance

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

php artisan serve

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:

php artisan serve --host

And you’re good!

koel - login

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


Loves to discover web-based apps to install on his own server@home and write articles about it


Add a comment