Use Koel to set up a personal audio streaming server

You can download this article in PDF format via the link below to support us.

Download the guide in PDF format

turn off


The prospect of having your own media streaming server is indeed exciting. Thanks to the excellent work of Opensource and the unremitting efforts of outstanding people around the world, you can have your own media streaming server to create wonderful music for you. One excellent open source media streaming server that you should check and get support is Koel.

Koel (also denoted by lowercase k as koel) is a simple web-based personal audio streaming service written in Vue on the client side and Laravel on the server side. For web developers, Koel uses some more modern web technologies-CSS grids, audio and drag and drop APIs to complete its work. Resources: (Cole)

“Those who can’t hear dancing are considered crazy, those who can’t hear music.”-Friedrich Nietzsche

Server requirements

Before a comfortable solution, Koel requires us to meet the following requirements:

  • All requirements of Laravel-PHP, OpenSSL,
  • composer
  • PHP>= 7.1.3
  • BCMath, Ctype, JSON, Mbstring, OpenSSL, PDO, token generator, XML PHP extension
  • If your library is large, please consider setting the memory_limit of PHP to an appropriate value (512M or higher).
  • MySQL, MariaDB, PostgresSQL or SQLite. In fact, any DBMS supported by Laravel can be used.
  • NodeJS latest stable yarn

Step 1: Update and install basic tools

After entering the terminal of the new Ubuntu server, update it and install the basic tools that will be used during the 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 set up the database

We will use MariaDB for this setup. Fortunately, we already have a detailed guide to install MariaDB 10.5. Check out how to install MariaDB 10 on Ubuntu 20.04 (Focal Fossa)

After installing the database, the next step is to create a database and user for our streaming server. So let’s proceed as follows. You can use different names to name the database and users at will, and make sure to use secure passwords.

$ 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 the web server

In order to provide Koel web pages, there must be a web server. Here, you can choose Apache or Nginx. We will use Nginx in this guide. In addition, as we have seen in the requirements, Koel requires PHP, so we must also set it up.

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

For more detailed information, we have a complete guide covering installing Nginx and PHP-FPM on Ubuntu 20.04.

Add recommended PHP settings

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

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

memory_limit = 512M

date.timezone = Africa/Nairobi

Install composer

Composer must be installed to install Koel’s dependencies. Do the following to set up the composer

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

Test whether composer has been successfully installed by running the composer version command

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

Step 4: Install Yarn and Node

In this step, we will enable the official Yarn repository, import the repository GPG key, and install the packages we are interested in. Let’s go ahead and execute the following command to import the GPG key of the repository and add the Yarn APT repository to your system:

Install Node.js

Install the node using the following command

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

Install yarn

Install Yarn using the following command

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

After the import is successful, the following command 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 where our web server will check out Koel files and provide files upon request. You can create a different object as needed. After creating the root directory, clone Koel’s files from Git, install all Node dependencies and 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 command 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 editing the file, initialize the database, and then start to provide services to 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 the Koel server from the browser, and it should be loaded. Point your browser to http://server-ip:8000 And the login screen shown below is displayed. Enter the email and password you set in the .env file above. If all goes well, the test is successful, so let’s continue to set up Koel for production.

Problem Ctrl + c Kill Cole test at the dock.

Create a new directory for documents | 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 some changes to the Nginx configuration defaults by adding the details required by Koel. Change to enable the site, back up the default file, and then create a new file with the new configuration.

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

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

$ 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 file permissions

In order for Nginx to read the file, we must grant it the correct permissions. Issue the following commands to complete the task.

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: Visit Koel’s web interface

To complete the setup of Koel Media Streaming Server, please point your browser to the IP or domain name of the web server that provides the file.[[[[http: //[ip-or-domain-name]. You should get a page similar to the one below, which is exactly the same as the one we interacted with earlier. Enter the email and password you set in the above .env file again.

Use Koel to set up a personal audio streaming server

After properly authenticated, you should enter the dashboard.

Use Koel to set up a personal audio streaming server

Step 7: Set up the media directory

You will notice that our streaming server does not have any media catalogs. In this example, we put the ~/Music directory to the location where Koel will get the media. I created “music“Directory, and then copy some music files (mp3, m4a, etc.) into it.

$ mkdir ~/Music

# Copy music/any media into this directory

When finished, log in to Koel Server again and click “Set value“And set the created directory as the media path, then click”Scan“.

Use Koel to set up a personal audio streaming server

The music file should function within your preferred time.

Use Koel to set up a personal audio streaming server

You can also add this command as a cron job, for example to run every midnight to synchronize your music files, in case you continue to add them to the media path

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

There we have guys. Koel’s client interface is similar to Spotify. So, when you search, sort, view by artist or album, create playlists (like/dislike songs), and create other users to share juice, you will feel at home.


When streaming a lot of music, you also need to perform other settings to fine-tune and optimize the server. For example, using Apache mod_xsendfile Modules and Nginx X-Accel module Make your streaming experience better. For more detailed information about Koel Media Streaming, please visit their website. Official documents And get all the power used by the streaming server.

Use the following guidelines to satisfy your curiosity:

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

You can download this article in PDF format via the link below to support us.

Download the guide in PDF format

turn off