Nov 9, 2024 3 min read

Koel: Self-Hosting Made Simple

Koel: Self-Hosting Made Simple
Table of Contents

Koel is a beautifully designed, self-hosted audio streaming application built with Laravel and Vue.js. It allows you to manage and stream your personal music library from anywhere, offering full control over your data without relying on third-party services. In this guide, we’ll cover everything from installation and configuration to backup, updates, and leveraging Koel’s unique features to maximize your streaming experience.

Installing Koel

πŸ“¦ Docker/Docker Compose Setup

Koel's Docker setup simplifies deployment, avoiding dependency conflicts and minimizing setup time. Here's how to get started:

  1. Create a project directory and add a docker-compose.yml file with the following content:

version: '3.8'

services:

koel:

image: koel/core:latest

container_name: koel

ports:

- "8000:8000" # Expose Koel on port 8000

volumes:

- ./music:/music # Your music directory

- ./config:/var/www/html/storage # Koel's configuration files

environment:

- DB_CONNECTION=mysql

- DB_HOST=db

- DB_PORT=3306

- DB_DATABASE=koel

- DB_USERNAME=koel_user

- DB_PASSWORD=secret

- APP_KEY=base64:YOUR_APP_KEY_HERE

- TRUSTED_PROXIES=*

depends_on:

- db

db:

image: mysql:5.7

container_name: koel_db

environment:

MYSQL_ROOT_PASSWORD=root_password

MYSQL_DATABASE=koel

MYSQL_USER=koel_user

MYSQL_PASSWORD=secret

volumes:

- db_data:/var/lib/mysql

volumes:

db_data:

  1. Run the following commands to start Koel:

docker-compose up -d

docker exec koel php artisan koel:init

The koel:init command initializes the database and generates essential configuration files. Replace YOUR_APP_KEY_HERE with a base64-encoded key generated using Laravel's php artisan key:generate command.

  1. Access Koel at http://<your-server-ip>:8000.

πŸš€ Manual Installation

For users who prefer a non-Docker setup, follow these steps to install Koel manually on a Linux server:

  1. Install system dependencies:

sudo apt update

sudo apt install -y git curl composer php php-mbstring php-xml php-bcmath php-tokenizer php-zip php-curl unzip mariadb-server nginx

  1. Clone the Koel repository:

git clone https://github.com/koel/koel.git

cd koel

  1. Install PHP dependencies:

composer install

  1. Configure the .env file with your database and app settings:

cp .env.example .env

nano .env

  1. Initialize the application:

php artisan koel:init

  1. Configure Nginx as the reverse proxy (see the next section).

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

To serve Koel via Nginx, create a server block configuration:

  1. Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/koel

  1. Add the following content:

server {

listen 80;

server_name yourdomain.com;

root /path/to/koel/public;

index index.php;

location / {

try_files $uri $uri/ /index.php?$query_string;

}

location ~ \.php$ {

include snippets/fastcgi-php.conf;

fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

include fastcgi_params;

}

location ~ /\.ht {

deny all;

}

}

  1. Enable the site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/koel /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx


πŸ”’ SSL/TLS Setup with Let’s Encrypt

Secure Koel with HTTPS using Let’s Encrypt:

  1. Install Certbot:

sudo apt install certbot python3-certbot-nginx

  1. Obtain an SSL certificate:

sudo certbot --nginx -d yourdomain.com

  1. Automate certificate renewals:

sudo systemctl enable certbot.timer


Logging and Debugging Koel

πŸ—ƒοΈ Enabling Debug Logs

To enable debug logs, edit .env and set APP_DEBUG to true:


nano /path/to/koel/.env


APP_DEBUG=true


πŸ“„ Viewing Logs

If you’re using Docker, view logs with:


docker logs koel

For manual installations, Koel logs are in the storage/logs/ directory:


tail -f /path/to/koel/storage/logs/laravel.log


πŸ› οΈ Troubleshooting Common Issues

  1. Database connection errors:
  • Verify database credentials in .env.

  • Test the connection: mysql -u koel_user -p -h localhost.

  1. Permission issues:
  • Adjust permissions: sudo chown -R www-data:www-data /path/to/koel.

Backup and Restore

πŸ—‚οΈ File-Based Backups

Backup Koel’s configuration and music files:


tar -czvf koel_backup.tar.gz /path/to/koel /path/to/music


πŸ”„ Database Backups

Export and import the database:


mysqldump -u koel_user -p --databases koel > koel_db_backup.sql

## Restore:

mysql -u koel_user -p < koel_db_backup.sql


πŸ“… Automated Backup Scripts

Create a cron job for automated backups:


echo "0 3 * * * tar -czvf /backups/koel_$(date +\%F).tar.gz /path/to/koel /path/to/music" | crontab -


Updating and Upgrading Koel

⬆️ Updating Docker Images

Pull the latest image and redeploy:


docker-compose pull

docker-compose up -d


πŸ› οΈ Manual Updates

Update via Git and Composer:


cd /path/to/koel

git pull origin master

composer install --no-dev

php artisan koel:init


Leveraging Koel’s Unique Features

πŸ”§ Enabling APIs

Koel provides RESTful APIs for programmatic access. Enable the API in .env:


KOEL_PUBLIC=true

Test the API using curl:


curl -X GET -H "Authorization: Bearer YOUR_API_TOKEN" http://yourdomain.com/api/songs


🌟 Advanced Configurations

Customize Koel by enabling advanced features like queue workers:


php artisan queue:work

Or integrate with third-party storage, such as Amazon S3, by configuring .env:


FILESYSTEM_DRIVER=s3

AWS_ACCESS_KEY_ID=your-key

AWS_SECRET_ACCESS_KEY=your-secret

AWS_BUCKET=your-bucket

AWS_REGION=your-region


Wrapping Up

Koel is a powerful, customizable solution for self-hosting your music library, giving you full control over your data and streaming experience. By following this guide, you can confidently deploy, configure, and manage Koel, ensuring it stays secure, up-to-date, and backed up. Dive into the provided examples, make it your own, and enjoy seamless music streaming from anywhere!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.