Koel Install Guide

Koel is a web-based music library that can be accessed from any device with a web browser. It is a great alternative to Spotify, Apple Music, and other streaming services. It looks and runs fantastic on desktop or mobile, and from my experience is easy on my phone’s data plan.

This article assumes you have a basic understanding of Linux and the command line. When editing text on the server, it is assumed that you use Vim as your text editor. If you do not, you can replace vim with your text editor of choice (Like nano).

It is also assumed that your server is running Debian 11 or a similar distribution.

Installation and setup

Install necessary dependencies:

First, make sure you update everything on your server

apt update && sudo apt upgrade
apt autoremove

Next, we need to get the latest version of PHP, currently 8.1, this involves setting up a new PPA

apt -y install lsb-release apt-transport-https ca-certificates wget
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
apt update
apt install php8.1 -y

Now that PHP 8.1 is installed let’s get some common packages most PHP apps need, this may be a shotgun approach, but I install all of these whenever working with PHP

apt install php8.1-common php8.1-fpm php8.1-mysql php8.1-sqlite3 php8.1-xml php8.1-xmlrpc php8.1-curl php8.1-gd php8.1-imagick php8.1-cli php8.1-dev php8.1-imap php8.1-mbstring php8.1-opcache php8.1-soap php8.1-zip php8.1-redis php8.1-intl -y

We also need to configure PHP just a little, this is necessary for Koel to work properly

vim /etc/php/8.1/fpm/php.ini

Change the following lines:

upload_max_filesize = 32M 
post_max_size = 48M 
memory_limit = 512M # Minimum is 512M for Koel
max_execution_time = 600 

Now we download and install Composer, nodejs, npm, yarn, mariadb, nginx, and git

# Following three lines are for installing the latest version nodejs
apt install curl software-properties-common -y
curl -sL https://deb.nodesource.com/setup_18.x | sudo bash - 
apt install nodejs -y
npm install --global yarn
apt install composer npm mariadb-server nginx git -y

Finally, lets install Koel

cd /var/www
mkdir koel && cd koel
git clone https://github.com/koel/koel.git .
git checkout latest
composer install

With Koel setup, it’s going to need mariadb to work correctly. The framework Koel uses (Laravel) is going to handle migrations for us, but we need to run the secure installation script and create a database first.

mysql_secure_installation
mariadb

Once in the mariadb shell, create a database and user for Koel to use.

CREATE
DATABASE koel;
CREATE
USER 'koel'@'localhost' IDENTIFIED BY 'yourpasswordhere';
GRANT ALL PRIVILEGES ON koel.* TO
'koel'@'localhost';
FLUSH
PRIVILEGES;
exit;

Now we can let Koel do some magic, set up the database, and compile the front-end client for us.

php artisan koel:init

Select mysql as the database type (mariadb is mysql to Koel), the host should be localhost and just hit enter to use the default mysql port. Next just enter the database name, user, and password you created earlier when prompted. You can also set a media path, I suggest reading the Adding Music section of this guide before setting this.

Finally, create a new nginx site for Koel

vim /etc/nginx/sites-available/koel

Copy the following into the file, replacing the server_name with your domain name

server {
    listen 80;
    server_name koel.example.com;
    root /var/www/koel/public;
    index index.php index.html index.htm index.nginx-debian.html;
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock;
    }
    location ~ /\.ht {
        deny all;
    }
}

Now enable and start nginx, enable the site, and restart nginx

systemctl enable nginx
systemctl start nginx
ln -s /etc/nginx/sites-available/koel /etc/nginx/sites-enabled/
systemctl restart nginx

Don’t forget to open port 80 in your firewall!

ufw allow 80

If you haven’t already, make sure to get a domain and point it to the IP of your server. Since this is a personal and private music server, I suggest any cheap subdomain and whatever domain name you want, it’s not important as long as you can remember it, we just need it for SSL.

With the domain properly pointing to the server, and the server name set properly in the nginx config it is time to issue a Let’s Encrypt certificate.

apt install python3-certbot-nginx
certbot --nginx --register-unsafely-without-email

and set a cron job to renew the cert before it expires

crontab -e

and add the following line

0 0 * * * certbot renew --nginx

Now you can run the Koel admin command to configure a new password. It will also give you the email used to sign in, this can be changed from inside the web app

php artisan koel:admin:change-password

Congrats! With this, you now have a personal music service running on your server and the admin login (be sure to change that email!). You can access it by going to your domain name in a web browser. When first visiting your site, you may notice symphony giving write permission errors, this is because Koel needs to write to the storage directory (and sometimes other directories). You can fix this with chown and/or chmod. Please be careful when doing this! If you notice something isn’t working always check the log file, and change read/write permissions where appropriate.

Adding Music

When first running php artisan koel:init you will be prompted to set a media path. This is where Koel will look for music files. You can set this to any directory on your server, but I suggest creating a new directory for Koel to use, and if you plan on having a lot of media, I suggest attaching a separate drive to your server, this just helps to keep things clean and your media separate. You can also check out my helpful Python script for bulk downloading with spotDL.

Regardless of how you set up your media folder, once you have added songs, simply run php artisan koel:sync to add them to the database and see them show up on Koel. You can also run php artisan koel:sync --force to force a rescan of the media folder, this is helpful when you miss thumbnails or change some files around.

Updating Koel

Updating Koel is straightforward, here I show an update from v6.7.1 to v6.7.2

When you see the update notice in the info pane:

Just run the following:

cd /var/www/koel
git pull
# You will see the new version tag in the git output
git checkout v6.7.2 # Replace with the version you see in the git output
composer install
php artisan koel:init # This will run migrations and recompile the front end, plus whatever else is needed

If you have trouble with the above commands, be sure to check that version’s release notes on the Koel GitHub page, there may be extra steps depending on the release.

Finally, if you find anything to be incorrect or outdated in this article, please email me (linked in the sidebar).