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:
- 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:
- 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.
- 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:
- 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
- Clone the Koel repository:
git clone https://github.com/koel/koel.git
cd koel
- Install PHP dependencies:
composer install
- Configure the
.env
file with your database and app settings:
cp .env.example .env
nano .env
- Initialize the application:
php artisan koel:init
- 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:
- Create a new Nginx configuration file:
sudo nano /etc/nginx/sites-available/koel
- 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;
}
}
- 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:
- Install Certbot:
sudo apt install certbot python3-certbot-nginx
- Obtain an SSL certificate:
sudo certbot --nginx -d yourdomain.com
- 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
- Database connection errors:
-
Verify database credentials in
.env
. -
Test the connection:
mysql -u koel_user -p -h localhost
.
- 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!