Koel Deployment and Usage Guide

Prerequisites

Before installing Koel, ensure you have the following:

PHP 8.1+ with extensions: mbstring, pdo, pdo_mysql, openssl, curl, exif, fileinfo, tokenizer, xml, gd, zip
Composer for PHP dependency management
Node.js 16+ and npm for front-end assets
MySQL 5.7+ or MariaDB 10.3+ (PostgreSQL also supported)
Web server (Apache, Nginx, or PHP's built-in server for development)
FFmpeg (optional, for audio processing)
cURL (for Last.fm integration)
Git for cloning the repository

Installation

1. Clone the Repository

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

2. Install Dependencies

# Install PHP dependencies
composer install

# Install Node.js dependencies and build assets
npm install
npm run build

3. Environment Configuration

# Copy the environment template
cp .env.example .env

# Generate application key
php artisan key:generate

# Configure your database settings in .env
# Example for MySQL:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=koel
DB_USERNAME=your_username
DB_PASSWORD=your_password

4. Run Installation Wizard

php artisan koel:init

This command will guide you through the installation process, including database setup and initial configuration.

Configuration

Environment Variables

Key environment variables to configure in .env:

# Application
APP_NAME=Koel
APP_ENV=production
APP_DEBUG=false
APP_URL=http://your-koel-domain.com

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=koel
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Media Storage
MEDIA_PATH=/path/to/your/music/folder

# Optional Integrations
LASTFM_API_KEY=your_lastfm_api_key
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
YOUTUBE_API_KEY=your_youtube_api_key

# Cache and Session
CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

Media Folder

Set the MEDIA_PATH environment variable to point to your music folder:

MEDIA_PATH=/var/www/koel/music

Build & Run

Development

# Start the development server
php artisan serve

# Watch for front-end changes
npm run watch

Production

# Compile assets for production
npm run build

# Run migrations
php artisan migrate

# Start queue worker (optional, for background tasks)
php artisan queue:work

# Set up scheduler (for periodic tasks)
* * * * * cd /path-to-your-koel-project && php artisan schedule:run >> /dev/null 2>&1

Deployment

Platform Recommendations

DigitalOcean App Platform - Recommended for easy deployment

One-click deployment available
Automatic SSL certificates
Scalable infrastructure

Docker - For containerized deployment

# Build Docker image
docker build -t koel .

# Run container
docker run -d -p 8000:80 koel

Shared Hosting - For traditional hosting environments

Ensure PHP 8.1+ and MySQL are available
Set up cron jobs for scheduled tasks

Production Checklist

Set APP_DEBUG=false in production
Configure proper file permissions
Set up SSL certificates
Configure backup strategies
Monitor logs and performance

Troubleshooting

Common Issues

Database Connection Issues

# Check database connection
php artisan tinker
DB::connection()->getPdo();

Asset Compilation Errors

# Clear compiled assets
rm -rf public/build
npm run build

Permission Issues

# Set proper permissions
chmod -R 755 storage bootstrap/cache
chown -R www-data:www-data /path/to/koel

Media Folder Not Found

# Ensure media path exists and is readable
ls -la /path/to/your/music/folder

Health Check

# Run Koel's doctor command
php artisan koel:doctor

Debug Mode

Enable debug mode temporarily to get more detailed error messages:

APP_DEBUG=true

Remember to disable debug mode in production for security reasons.

Log Files

Check log files for detailed error information:

tail -f storage/logs/laravel.log

For additional help, visit the Official Documentation or join the community support channels.

How to Deploy & Use phanan/koel