How to Install Koel Music Streaming Server on Ubuntu 18.04

Koel is a web-based personal audio streaming app written in Vue.js on the client-side and Laravel on the server-side. This tutorial will cover how to install Koel on Ubuntu 18.04 based server.

Prerequisites

A server running Ubuntu 18.04.
A non-root sudo user.
Make sure everything is updated.
```
$ sudo apt update && sudo apt upgrade
```

Few packages that your system needs.

$ sudo apt install ca-certificates curl unzip build-essential libpng-dev gnupg2 lsb-release ufw -y

Some of these packages may already be installed on your system.

Configure Firewall

The first step is to configure the firewall. Before we enable the firewall, we need to allow SSH ports otherwise we will get locked out of our server.

$ sudo ufw allow OpenSSH

Enable the firewall.

$ sudo ufw enable

Allow HTTP and HTTPS ports.

$ sudo ufw allow http
$ sudo ufw allow https

Check the status of the firewall.

$ sudo ufw status

You should see a similar output.

Status: active
To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443/tcp                    ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443/tcp (v6)               ALLOW       Anywhere (v6)

Install Git

We will start by installing Git.

$ sudo apt install git -y
$ git config --global user.name "Your Name"
$ git config --global user.email "[email protected]"

Install Node.js

We will be installing Node 10.x instead of the latest 12.x because Koel packages some outdated libraries which are not compatible with Node 12.

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt install -y nodejs

Check if Node is properly installed.

$ node --version

You should see a similar output.

v10.17.0

Install Yarn

Install the Yarn package manager.

$ curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
$ echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
$ sudo apt update && sudo apt install -y yarn

Check if Yarn is working correctly.

$ yarn --version

You should see a similar output.

1.19.1

Install PHP

Install PHP 7.2 with all its required extensions.

$ sudo apt install -y php7.2-fpm php7.2-mbstring php7.2-bcmath php7.2-xml php7.2-mysql php7.2-curl php7.2-zip

Check if PHP is working correctly.

$ php --version

You should see a similar output.

PHP 7.2.24-1+ubuntu18.04.1+deb.sury.org+1 (cli) (built: Oct 24 2019 18:29:11) ( NTS )
Copyright (c) 1997-2018 The PHP Group
Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies
    with Zend OPcache v7.2.24-1+ubuntu18.04.1+deb.sury.org+1, Copyright (c) 1999-2018, by Zend Technologies

Install MariaDB

MariaDB is a drop-in replacement for MySQL which means commands to run and operate MariaDB are the same as those for MySQL. To install MariaDB issue the following commands.

$ sudo apt install mariadb-server

Check if MariaDB installed correctly.

$ mysql --version

You should see the following output.

mysql  Ver 15.1 Distrib 10.1.41-MariaDB, for debian-linux-gnu (x86_64) using readline 5.2

Run the following command to perform default configuration such as giving a root password, removing anonymous users, disallowing root login remotely and dropping test tables. Enter yes for everything and set up a root password.

$ sudo mysql_secure_installation

There is a caveat with setting up the root password. MariaDB by default allows system root users to log in to MariaDB without a password. But if you are going to use a 3rd party application to access via root, a password is a must otherwise apps like PHPMyAdmin will fail. For this, you need to disable the plugin-based authentication which is the default option on MariaDB.

To Disable plugin authentication and restore the root password, enter the MySQL prompt first by using the following command.

$ sudo mysql -u root

Now enter the following commands to disable the plugin authentication.

use mysql;
update user set plugin='' where User='root';
flush privileges;
exit

After this restart your MariaDB service.

$ sudo systemctl restart mariadb.service

That's it. Next time you want to login to MySQL, use the following command

$ sudo mysql -u root -p

Enter your root password when prompted.

Configure MariaDB for Koel

Now we need to set up a database to use for the Koel application. To do that login to MySQL prompt. We will assume that you are using the default authentication method of MariaDB ( i.e. without using root password) for the rest of the tutorial.

$ sudo mysql -u root

Once at the prompt, enter the following commands which will set up a database named koelmusic and a database user named koeluser and grant it access to the database.

mysql> CREATE DATABASE koelmusic;
mysql> CREATE USER 'koeluser'@'localhost' IDENTIFIED BY 'yourpassword';
mysql> GRANT ALL PRIVILEGES ON koelmusic.* TO 'koeluser'@'localhost';
mysql> FLUSH PRIVILEGES;
mysql> exit

Install Nginx

Install Nginx server.

$ sudo apt install nginx

Check if it is working correctly.

$ nginx -v

You should see the following output.

nginx version: nginx/1.14.0 (Ubuntu)

Run the following command to add a configuration file for Koel.

$ sudo nano /etc/nginx/sites-available/koel.conf

Paste the following code in the editor.

server {
  listen          *:80;
  server_name     koel.example.com;
  root            /var/www/koel;
  index           index.php;

  gzip            on;
  gzip_types      text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript application/json;
  gzip_comp_level  9;

  # Whitelist only index.php, robots.txt, and some special routes
  if ($request_uri !~ ^/$|index\.php|robots\.txt|(public|api)/|remote|api-docs|sw\.js) {
    return 404;
  }

  location /media/ {
    internal;

    alias       $upstream_http_x_media_root;

    access_log /var/log/nginx/koel.access.log;
    error_log  /var/log/nginx/koel.error.log;
  }

  location / {
    try_files   $uri $uri/ /index.php?$args;
  }

  location ~ \.php$ {
    try_files $uri $uri/ /index.php?$args;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass  unix:/var/run/php/php7.2-fpm.sock;
    fastcgi_index index.php;
    fastcgi_split_path_info   ^(.+\.php)(/.+)$;
    fastcgi_intercept_errors  on;
    include  fastcgi_params;
  }
}

This file assumes that we will be installing Koel to the domain koel.example.com and in the directory /var/www/koel.

Activate this configuration file by linking it to the sites-enabled directory.

$ sudo ln -s /etc/nginx/sites-available/koel.conf /etc/nginx/sites-enabled/

Test the configuration.

$ sudo nginx -t

You should see the following output indicating your configuration is correct.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload the Nginx service.

$ sudo systemctl reload nginx

Install Composer

This is the last thing we need before we move ahead to the installation.

Enter the following commands to install Composer.

$ php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
$ php composer-setup.php
$ php -r "unlink('composer-setup.php');"
$ sudo mv composer.phar /usr/local/bin/composer

Check if it is working correctly.

$ composer --version

You should see the following output.

Composer version 1.9.1 2019-11-01 17:20:17

Install Koel

Create an empty document root folder for Koel.

$ sudo mkdir -p /var/www/koel

The -p argument ensures that parent directories var and www are automatically created if they don't exist.

Navigate to the document root folder.

$ cd /var/www/koel

Change ownership of the document root to user which is the non-root user we have used for the tutorial.

$ sudo chown -R user:user /var/www/koel

Clone the Koel Git repository and checkout its latest version. You can check the latest version from its releases page.

$ git clone --recurse-submodules https://github.com/phanan/koel.git .
$ git checkout v4.1.1

Install the dependencies.

$ composer install

Run the following command to set up the database and admin account. Enter mysql as the database type, skip the port and enter database credentials we created above. For the media folder, you can enter something like /home/user/songs.

$ php artisan koel:init

Change the ownership of the document root folder back to the www-data user.

$ sudo chown -R www-data:www-data /var/www/koel

The setup is now complete. Open koel.example.com in your browser and log in with the credentials you created above and start streaming. Koel's website is accessible via mobile as well.

Configure Koel

There are more details that you can configure by editing the .env file with the following command.

$ sudo nano /var/www/koel/.env

Here you can enter your SMTP details, configure Youtube and Last.fm for Koel and do a lot more stuff.

Reload Nginx server to implement the changes.

If you want to reset your admin password, you can do that by issuing the following command.

$ php artisan koel:admin:change-password

If you want to scan the media library for updated files, you can do so by the following command.

$ php artisan koel:sync

You should see the following output.

Koel syncing started.
953/953 [????????????????????????????] 100%
Completed! 944 new or updated song(s), 0 unchanged song(s), and 9 invalid file(s).

Suffix the command with -v flag which will give you more details like syncing errors.

You can even set this command as a cron job, for example, to run every midnight. To do that run the following command.

$ crontab -e

Select 1(nano) as your editor.

Paste the following line at the end of the file.

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

Save the file by pressing Ctrl + X and entering Y when prompted. Now, your media library will get synced every midnight.

For more stuff refer to the official Koel documentation.

Setting up HTTPS using Let's Encrypt

For using Let's encrypt, we need to install the Certbot package.

Add the repository.

$ sudo add-apt-repository ppa:certbot/certbot

Install Certbot.

$ sudo apt install python-certbot-nginx

Install the certificate.

$ sudo certbot --nginx -d koel.example.com

If this is your first time with the tool on this server, you need to agree to the terms and enter your email address. Say no when asked if you want to share your email with the EFF foundation.

If that’s successful, certbot will ask how you’d like to configure your HTTPS settings.

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
-------------------------------------------------------------------------------
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
-------------------------------------------------------------------------------
Select the appropriate number [1-2] then [enter] (press 'c' to cancel):