Skip to content
Klutch.sh Docs

Deploying Koel

Introduction

Koel is a modern, personal music streaming server that allows you to stream your music collection from anywhere with an internet connection. Built with Laravel and Vue.js, Koel provides a beautiful, responsive web interface reminiscent of Spotify but for your own music library.

Named after the bird known for its singing, Koel focuses on simplicity and elegance while providing essential features for personal music streaming. It automatically scans your music library, extracts metadata and album art, and presents everything in an intuitive interface.

Key highlights of Koel:

  • Beautiful Interface: Modern, Spotify-inspired design that works on any device
  • Smart Playlists: Create dynamic playlists based on rules and conditions
  • Instant Search: Find any song, album, or artist instantly
  • Scrobbling Support: Last.fm integration for music tracking
  • YouTube Integration: Search and play YouTube videos alongside your library
  • Equalizer: Built-in audio equalizer for customizing playback
  • Keyboard Shortcuts: Full keyboard navigation for power users
  • API Access: RESTful API for building custom integrations
  • Mobile Apps: Third-party apps available for iOS and Android
  • 100% Open Source: MIT licensed with active development

This guide walks through deploying Koel on Klutch.sh using Docker, configuring your music library, and streaming your collection.

Why Deploy Koel on Klutch.sh

Deploying Koel on Klutch.sh provides several advantages for music streaming:

Always-On Streaming: Your music is available 24/7 without running a local server.

Simplified Deployment: Klutch.sh builds and deploys Koel without complex Laravel setup.

Persistent Storage: Your music library and configurations survive restarts.

HTTPS by Default: Secure streaming with automatic SSL certificates.

GitHub Integration: Track configuration changes in version control.

Scalable Resources: Handle multiple concurrent streams with proper allocation.

Custom Domains: Stream from your own domain for a personalized experience.

Prerequisites

Before deploying Koel on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • A music collection in supported formats (MP3, FLAC, OGG, etc.)
  • Basic familiarity with Docker and Laravel applications
  • (Optional) Last.fm API credentials for scrobbling

Understanding Koel Architecture

Koel is built on a modern web stack:

Laravel Backend: PHP framework handling the API, authentication, and media serving.

Vue.js Frontend: Single-page application for the user interface.

MySQL/MariaDB Database: Stores user data, playlists, and music metadata.

FFmpeg: Handles audio transcoding for optimal streaming.

Media Scanner: Parses ID3 tags and extracts metadata from audio files.

Preparing Your Repository

Create a GitHub repository for your Koel deployment.

Repository Structure

koel-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM phanan/koel:latest


# Set environment variables
ENV APP_KEY=${APP_KEY}
ENV APP_ENV=production
ENV APP_DEBUG=false


# Database configuration
ENV DB_CONNECTION=mysql
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=${DB_PORT:-3306}
ENV DB_DATABASE=${DB_DATABASE}
ENV DB_USERNAME=${DB_USERNAME}
ENV DB_PASSWORD=${DB_PASSWORD}


# Music library path
ENV MEDIA_PATH=/music


# Streaming configuration
ENV STREAMING_METHOD=${STREAMING_METHOD:-php}
ENV OUTPUT_BIT_RATE=${OUTPUT_BIT_RATE:-128}


# Last.fm integration (optional)
ENV LASTFM_API_KEY=${LASTFM_API_KEY}
ENV LASTFM_API_SECRET=${LASTFM_API_SECRET}


# Expose the web interface
EXPOSE 80


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Advanced Dockerfile

For more control over your deployment:

FROM phanan/koel:latest


# Environment configuration
ENV APP_KEY=${APP_KEY}
ENV APP_ENV=production
ENV APP_DEBUG=false
ENV APP_URL=${APP_URL}


# Database
ENV DB_CONNECTION=mysql
ENV DB_HOST=${DB_HOST}
ENV DB_PORT=3306
ENV DB_DATABASE=${DB_DATABASE}
ENV DB_USERNAME=${DB_USERNAME}
ENV DB_PASSWORD=${DB_PASSWORD}


# Music configuration
ENV MEDIA_PATH=/music
ENV STREAMING_METHOD=php
ENV OUTPUT_BIT_RATE=128
ENV TRANSCODE_FLAC=true


# Memory settings for large libraries
ENV MEMORY_LIMIT=512M


# Last.fm
ENV LASTFM_API_KEY=${LASTFM_API_KEY}
ENV LASTFM_API_SECRET=${LASTFM_API_SECRET}


# YouTube (optional)
ENV YOUTUBE_API_KEY=${YOUTUBE_API_KEY}


# Expose port
EXPOSE 80


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Environment Variables Reference

VariableRequiredDefaultDescription
APP_KEYYes-Laravel encryption key (base64:32-char-string)
APP_URLYes-Full URL of your Koel instance
DB_HOSTYes-MySQL/MariaDB host
DB_DATABASEYes-Database name
DB_USERNAMEYes-Database username
DB_PASSWORDYes-Database password
MEDIA_PATHNo/musicPath to music files
STREAMING_METHODNophpStreaming method (php, x-sendfile, x-accel-redirect)
OUTPUT_BIT_RATENo128Bitrate for transcoded audio
LASTFM_API_KEYNo-Last.fm API key for scrobbling
LASTFM_API_SECRETNo-Last.fm API secret
YOUTUBE_API_KEYNo-YouTube API key for video integration

Deploying Koel on Klutch.sh

    Generate an APP_KEY

    Generate a Laravel encryption key:

    Terminal window
    php -r "echo 'base64:'.base64_encode(random_bytes(32)).PHP_EOL;"

    Or use OpenSSL:

    Terminal window
    echo "base64:$(openssl rand -base64 32)"

    Set Up MySQL Database

    Deploy a MySQL or MariaDB database on Klutch.sh or use an external service. Note the connection details.

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Koel deployment configuration"
    git remote add origin https://github.com/yourusername/koel-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “koel” or “music-server”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select the repository containing your Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80

    Set Environment Variables

    Add the following environment variables:

    VariableValue
    APP_KEYYour generated Laravel key
    APP_URLhttps://your-app-name.klutch.sh
    DB_HOSTYour database host
    DB_DATABASEkoel
    DB_USERNAMEYour database username
    DB_PASSWORDYour database password
    LASTFM_API_KEYYour Last.fm API key (optional)
    LASTFM_API_SECRETYour Last.fm API secret (optional)

    Attach Persistent Volumes

    Add storage for your music:

    Mount PathRecommended SizePurpose
    /music100+ GBMusic library storage
    /var/www/html/storage5 GBCovers, cache, and logs

    Deploy Your Application

    Click Deploy to start the build process.

    Run Initial Setup

    After deployment, run the initial setup:

    Terminal window
    php artisan koel:init

    Upload Your Music

    Transfer your music files to the /music volume.

    Access Koel

    Once deployed, access Koel at https://your-app-name.klutch.sh.

Initial Configuration

Creating an Admin Account

During first run, create your admin account:

  1. Access the Koel web interface
  2. Complete the registration form
  3. Log in with your credentials

Scanning Your Music Library

Trigger a library scan:

  1. Log in as admin
  2. Click the gear icon for settings
  3. Click “Scan” to index your music

Or via command line:

Terminal window
php artisan koel:sync

Enabling Last.fm Scrobbling

Connect your Last.fm account:

  1. Go to Settings > Profile
  2. Click “Connect to Last.fm”
  3. Authorize the connection
  4. Your plays will now be scrobbled

Organizing Your Music

/music/
├── Artist Name/
│   ├── Album Name (Year)/
│   │   ├── 01 - Track Title.mp3
│   │   ├── 02 - Track Title.mp3
│   │   └── cover.jpg
│   └── Another Album/
└── Another Artist/

Supported Formats

  • MP3
  • FLAC
  • OGG
  • AAC
  • M4A
  • OPUS

Metadata Best Practices

  • Ensure ID3 tags are properly filled
  • Embed album art when possible
  • Use consistent naming conventions

Creating Playlists

Manual Playlists

Create static playlists:

  1. Click the + icon next to Playlists
  2. Name your playlist
  3. Drag songs to add them

Smart Playlists

Create dynamic playlists based on rules:

  1. Create a new Smart Playlist
  2. Add rules (genre, year, play count, etc.)
  3. Songs matching the rules are automatically included

Example rules:

  • Genre is “Rock” AND Year > 2020
  • Play Count > 10 AND Added < 30 days ago

Mobile Access

Third-Party Apps

Several mobile apps support Koel’s API:

  • KoelPlayer (iOS): Native iOS client
  • Auryo (Android): Third-party Android client

Progressive Web App

Koel works as a PWA:

  1. Open Koel in your mobile browser
  2. Add to home screen
  3. Use like a native app

Troubleshooting

Music Not Appearing

  • Verify files are in the MEDIA_PATH directory
  • Check that file permissions allow reading
  • Run a manual sync command

Playback Issues

  • Ensure audio files are not corrupted
  • Check streaming method configuration
  • Verify FFmpeg is available for transcoding

Slow Library Scan

  • Large libraries take time to scan
  • Check for unreadable files
  • Monitor PHP memory usage

Additional Resources

Conclusion

Deploying Koel on Klutch.sh gives you a beautiful, personal music streaming service accessible from anywhere. With persistent storage for your music library and automatic HTTPS, you can enjoy your music collection on any device without relying on subscription services.

Whether you’re streaming at home or on the go, Koel on Klutch.sh provides the perfect blend of simplicity and functionality for personal music streaming.