Koel: Self-Hosting Made Simple

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:

2. 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.

3. 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

2. Clone the Koel repository:

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

cd koel

3. Install PHP dependencies:

composer install

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

cp .env.example .env

nano .env

5. Initialize the application:

php artisan koel:init

6. 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

2. 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;

}

}

3. 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

2. Obtain an SSL certificate:

sudo certbot --nginx -d yourdomain.com

3. 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.

2. 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!