The prospect of having your own media streaming server can be indeed exhilarating. Thanks to the good work of Opensource and the relentless hard work by awesome people around the world, you can have your own media streaming server purring and creating fantastic music for you. One amazing opensource media streaming server you should check out for and support is Koel.

Koel (also stylized as koel, with a lowercase k) is a simple web-based personal audio streaming service written in Vue on the client-side and Laravel on the server-side. Targeting web developers, Koel embraces some of the more modern web technologies – CSS grid, audio, and drag-and-drop API to name a few – to do its job. Source: (Koel)

“And those who were seen dancing were thought to be insane by those who could not hear the music.”
Friedrich Nietzsche

Server Requirements

Koel has the following requirements it asks of us before it can settle comfortably:

  • All requirements by Laravel – PHP, OpenSSL,
  • Composer
  • PHP >= 7.1.3
  • BCMath, Ctype, JSON, Mbstring, OpenSSL, PDO, Tokenizer, XML PHP Extension
  • Consider setting PHP’s memory_limit to a good value (512M or better) if you have a big library.
  • MySQL, MariaDB, PostgresSQL, or SQLite. Actually, any DBMS supported by Laravel should work.
  • NodeJS latest stable with yarn

Step 1: Update and install essential tools

Once in the terminal of your fresh Ubuntu server, update it and install essential tools we shall use in our installation process

sudo apt update && sudo apt upgrade
sudo apt install vim git unzip nginx curl build-essential libpng-dev gcc make ffmpeg -y

Step 2: Install and setup database

We are going to use MariaDB for this setup. Fortunately, we have a detailed guide already to get MariaDB 10.5 installed. Check out How To Install MariaDB 10 on Ubuntu 20.04 (Focal Fossa)

After you have the database installed, the next step is to create a database and user for our streaming server. Let us therefore go ahead and get this done as shown below. You are free to name your database and user differently and ensure you use a safe password.

$ mysql -u root -p
Enter password: 

MariaDB [(none)]> CREATE DATABASE koeldb;
MariaDB [(none)]> CREATE USER 'koeluser'@'localhost' IDENTIFIED BY 'StrongPassword';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON koeldb . * TO 'koeluser'@'localhost';
MariaDB [(none)]> exit;

Step 3: Install PHP and configure a web server

In order to get Koel web pages served, there has to be a webserver. Here, you have the freedom of either picking Apache or Nginx. We shall use Nginx in this guide. Additionally, as we have seen in the requirements, Koel needs PHP and therefore we will have to set it up as well.

sudo apt install php php-cli php-fpm php-json php-common php-mysql php-zip php-gd  php-mbstring php-curl php-xml php-pear php-bcmath php-tokenizer openssl php-json -y

Fore more details, we have a complete guide that covers the installation of Nginx and PHP-FPM on Ubuntu 20.04.

Add recommemded PHP Settings

Open up your php-fpm ini file and add/edit the details shown below. They include Timezone, and memory limit settings. Add your date.timezone and change memory_limit to 512MB or more.

$ sudo vim /etc/php/7.4/fpm/php.ini

memory_limit = 512M

date.timezone = Africa/Nairobi

Install composer

Composer is required to in order to get Koel’s dependencies installed. Do the following to setup composer

cd ~
curl -sS -o composer-setup.php
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Test if composer is successfully installed by running the composer version command

$ composer -V
Composer version 1.10.9 2020-07-16 12:57:00

Step 4: Get Yarn and Node installed

In this step, we will enable the official Yarn repository, import the repository GPG key, and install the packages of our interest. Let us proceed to import the repository’s GPG key and add the Yarn APT repository to your system by issuing the commands below:

Install Node.js

Install Node using the commands below

curl -sL | sudo -E bash -
sudo apt install nodejs

Install Yarn

Install Yarn as well using the commands below

curl -sS | sudo apt-key add -
echo "deb stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

After the importation is successful, the command below will update the package list and install yarn.

sudo apt update
sudo apt install --no-install-recommends yarn

Step 5: Prepare Koel Project

The root directory is the folder in which our Webserver will check out for Koel’s files and serve them upon request. You can create a different one according to your needs. After creating the root directory, clone Koel’s files from Git, install all Node dependencies as well as PHP dependencies using Yarn and Composer respectively.

cd ~
composer global require laravel/installer
git clone  --recursive
cd koel
npm install
npm audit fix
npm audit fix --force ## If there are vulnerabilities remaining
composer install

The above commands will take some time to complete.

Edit .env file containing Database details

$ vim .env


ADMIN_NAME="Koel Admin"
[email protected]


The full path of ffmpeg binary.

After you are done editing the file, initialize the database and then start serving the site.

$ php artisan koel:init --no-interaction

##You should see the message below when it ends
🎆  Success! Koel can now be run from localhost with `php artisan serve`.
Again, visit 📙 for the official documentation.
Feeling generous and want to support Koel's development? Check out 🤗
Thanks for using Koel. You rock! 🤘

$ php artisan serve --host

##You will see a message like:
Laravel development server started: <>

At this point, you can load your Koel server from the browser and it should load. Point your browser to http://server-ip:8000 and a login screen like below will show up. Enter the email and password that you set in the .env file above. If it all goes well, the test was successful, so let us proceed to setup Koel for production.

koel login 1

Issue Ctrl+c at the terminal to kill koel test.

Create a new directory to be used as the Document| webroot for koel and copy Koel files and folders into it.

sudo mkdir /var/www/html/streaming/
sudo mv ~/koel /var/www/html/streaming/

Configure Nginx

We have to make a few changes to the Nginx configuration defaults by adding the details we need for Koel. Change into sites-enabled, back up the default file, and create a new one with new configurations.

cd /etc/nginx/sites-enabled/
sudo mv default /tmp

Create a new file and add the details shown below. If you have an FQDN, replace with it.

$ sudo vim /etc/nginx/sites-enabled/koel.conf

server {
        listen       80 default_server;
        listen       [::]:80 default_server;
        root         /var/www/html/streaming/koel;
        index index.html index.htm index.php;

        location / {
                try_files $uri /index.php$is_args$args;

        location ~ \.php$ {
        fastcgi_pass unix:/run/php/php7.4-fpm.sock;
        fastcgi_index index.php;
        fastcgi_read_timeout 240;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_split_path_info ^(.+.php)(/.+)$;

Change Koel’s files permissions

In order for Nginx to read the files, we have to grant it correct rights and the right permissions. Issue the commands below to get that done.

sudo mkdir /var/www/html/streaming/koel/storage/logs
sudo chown -R www-data:www-data /var/www/html/streaming/
sudo chmod -R 755 /var/www/html/streaming/
sudo systemctl restart nginx php7.4-fpm

Step 6: Access Koel’s Web Interface

To complete setting up Koel Media Streaming Server, point your browser to the IP or domain name of the webserver serving the files. [http://[ip-or-domain-name]. You should get a page like below which is exactly the same as the one we had interacted with before. Again enter the email and password that you had set in the .env file above.

koel login 2

You should be ushered into the dashboard when well authenticated.

koel dashboard 2

Step 7: Setting a Media directory

You will notice that our streaming server does not have any media directory. For this example, we are going to make ~/Music directory the place Koel will be fetching our media. I created the “Music” directory and copied some music files (mp3,m4a, etc) into it.

$ mkdir ~/Music

# Copy music/any media into this directory

After you are done, log back into Koel Server and click on “Settings” and set the created directory as the Media Path then click on “Scan“.

koel dashboard set media path 3

And your music files should avail themselves for your felicity time.

koel music playing 5

This command can also be added as a cron job, for example to run every midnight o sync your music files in case you keep adding them into the media path

0 0 * * * cd /var/www/html/streaming/koel/ && /usr/bin/php artisan koel:sync >/dev/null 2>&1

And there we have it guys. Koel’s client interface looks like Spotify. So you will feel right at home as you search, sort, view by artists or albums, create playlists, like/unlike songs, and create other users to share the juices.


There are other settings you should to do to fine-tune and optimize your server when Streaming Music heavily. For example, using Apache’s mod_xsendfile module and Nginx’s X-Accel module to make your streaming experience far better. For more details about Koel Media Streaming, kindly visit their Official Documentation and get all the electricity the Streaming server was built with.

Satiate your curiosity with the guides below:

Install Plex Media Server on CentOS 8 / CentOS 7

How To Install VLC Media Player on Debian 10 (Buster)

Install Kodi Media Server on Fedora

How to Install Plex Media Server on Ubuntu and Arch Linux

Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


  1. I am now stuck at this point.

    “warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to av
    oid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.
    [1/4] Resolving packages…
    success Already up-to-date.
    Done in 0.66s.
    yarn run v1.22.5
    $ cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js –progress –hide-modules –config=node_modules/laravel-mix/setup/webpack.config.js –colo
    [webpack-cli] Error: Unknown option ‘–hide-modules’
    [webpack-cli] Run ‘webpack –help’ to see available commands and options
    error Command failed with exit code 2.
    info Visit for documentation about this command.
    Oops! Koel installation or upgrade didn’t finish successfully.
    Please try again, or visit for manual installation.
     Sorry for this. You deserve better.”


Please enter your comment!
Please enter your name here