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.
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
$ 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
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.
$ 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
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!
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
$ 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
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
koel-db-user with permissions for that database.
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
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.
Back on the Koel server, running this command will allow you to populate
.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
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.
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
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