Joseph Petitti — January 5, 2020

How to install Koel on Fedora 30

Koel is a cool web application built on PHP and Vue.js for streaming your music collection over the internet. Basically it's like having your own personal Spotify, except it's free and open source. Since I couldn't find any detailed guide for installing it and all its dependencies on a Fedora server, I decided to write my own.

Install Laravel

Koel depends on Laravel, a PHP web framework. Laravel in turn depends on PHP and composer.

Install a DBMS

If you already have a Datamase Management System server skip ahead to Install PHP. If not, you'll have to install one either locally or on a separate server. Laravel is compatible with several DBMSs, but I like MariaDB (the community-driven fork of MySQL) so that's what I'll use. Feel free to substitute PostreSQL, SQLite, or whatever else you prefer.

On the database server run

$ sudo dnf install mariadb-server

Now enable, start, and set up MariaDB by running:

$ sudo systemctl enable mariadb
$ sudo systemctl start mariadb
$ sudo mysql_secure_installation

Just press enter the first time it prompts for the root password because it hasn't been set yet. Then set the root password to something strong, and answer each of the questions. The recommended answer to each of them is 'Y'.

If MariaDB is running on a different server, the Koel server will still need to be able to access it. Install the mysql tool on the Koel server:

$ sudo dnf install mariadb

Install PHP and Composer

Now we have to install PHP and all the extensions that Laravel depends on.

$ sudo dnf install php \
php-common \
php-cli \
php-pdo \
php-mbstring \
php-zip \
php-xml \
php-cli \
php-json \
php-mysqli

Laravel uses Composer, a dependency manager for PHP. This can be installed with:

$ sudo dnf install composer

Now we can use composer to install Laravel globally.

$ composer global require "laravel/installer"

To make sure we can run the laravel command from anywhere, we need to add ~/.config/composer/vendor/bin to our PATH. Add this line to the end of ~/.bashrc:

export PATH="$PATH:$HOME/.config/composer/vendor/bin"

Reload the config file with $ source ~/.bashrc and run this to test if it worked:

$ laravel --version

You should get a nice message telling you the version of Laravel Installer you now have.

Install Node.js

Koel also uses Node.js, a JavaScript runtime environment, and Yarn, a JavaScript dependency manager. To install node on Fedora, just do

$ sudo dnf install nodejs

Yarn isn't in the official Fedora repos, so you'll have to add theirs. See here for the most up-to-date instructions for that. Then just run:

$ sudo dnf install yarn

One of the JavaScript packages that Koel depends on requires libpng development tools, so install them with

$ sudo dnf install libpng-devel

Now we're finally done with dependencies and can move on to install Koel itself!

Install Koel

Let's make a directory for the Koel installation (replace USER with your own username)

$ sudo mkdir /var/www/koel
$ sudo chown -R USER:USER /var/www/koel

Now clone the repo into that directory (# dnf install git if you don't already have it).

$ git clone --recurse-submodules https://github.com/phanan/koel.git /var/www/koel

We want to checkout the most recent stable version, so check the releases page to find out what that is. As of time of writing it's v4.2.2.

$ cd /var/www/koel
$ git checkout v4.2.2

Use composer to install all PHP dependencies

$ composer install

We're almost set, now we just have to set up a database user for Koel.

Prepare the database

These instructions are for MariaDB/MySQL, but other DBMSs should be similar. From the database server, which may be the same as the one you're installing Koel on, log into MySQL as root.

$ mysql -u root -p

Enter the MySQL root password when prompted.

If Koel is running on a different machine from your database, edit /etc/my.cnf. Add a [mysqld] section if it doesn't already exist, then add bind-address=0.0.0.0 below it. If there's a line containing skip-networking comment it out or delete it. This makes MariaDB listen to all IPv4 addresses rather than just localhost. Then $ sudo systemctl restart mariadb to reload the config.

Now we're going to create a database called koel and a user called koel-db-user with permissions for that database. Replace koel-pass with a strong password for the user. If Koel is running on a different host from the database replace localhost with the hostname or IP address of the Koel server below.

mysql> CREATE DATABASE koel DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
mysql> CREATE USER 'koel-db-user'@'localhost' IDENTIFIED BY 'koel-pass';
mysql> GRANT ALL PRIVILEGES ON koel.* TO 'koel-db-user'@'localhost' WITH GRANT OPTION;
mysql> exit;

Now return to the Koel server.

Final setup

Back on the Koel server, running this command will allow you to populate the .env file with your credentials, as well as pull in frontend dependencies with yarn. Make sure you're still in /var/www/koel, then do:

$ php artisan koel:init

Answer each of the prompted questions, including the database credentials you set up above. Now you're done! If you run $ php artisan serve you should be able to visit the web interface at http://localhost:8000.

This is just the development server, but the production server can be set up the same way as any other PHP application. I used Nginx with a config file based on the sample Nginx config.

Troubleshooting

Here's some advice to get through some of the issues I encountered.

First I faced an issue where Koel didn't have permission to write to the storage directory. Edit /etc/php-fpm.d/www.conf to see what user and group it's running as. I was using Nginx, so I set them both like so

user = nginx
group = nginx

Restart the php-fpm daemon to apply the change and set the Koel directory to be owned by that user and group.

$ sudo systemctl restart php-fpm
$ sudo chown -R nginx:nginx /var/www/koel

That should have fixed the issue, but for me it didn't. If you're on a Red Hat system and you've been banging your head against the wall for an hour trying to figure out why something that should work doesn't work, 99% of the time the issue is SELinux.

It turns out you need to explicitly give Nginx write permission for that directory in SELinux. You can use a tool called semanage to make this easier.

$ sudo dnf install policycoreutils-python-utils
$ sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/koel/storage(/.*)?"
$ sudo restorecon -R /var/www/koel/storage

Credit to this StackExchange post for that solution.

That managed to solve that permission issue, but I was still getting another. I had logs claiming permission was denied to access the database even though I made sure the host, port, username, database name, and password were correct. It turns out that SELinux was getting in the way here too. You need to explicitly allow Nginx to connect to databases over the network, which can be done with this command:

$ sudo setsebool -P httpd_can_network_connect_db=1

Credit to this StackOverflow post for that solution.

If your music collection is on a shared network drive, like mine, you'll need to explicitly allow Nginx to read from it too. Do one of the following, depending on the type of network drive you have:

$ sudo setsebool -P httpd_use_cifs on
$ sudo setsebool -P httpd_use_nfs on