How to Set Up Your Personal Music Streaming Server with Koel: A Step-by-Step Guide

Are you tired of relying on third-party music streaming services that limit your control over your music library? Imagine having your own personal music streaming server, where you can access your favorite tunes anytime, anywhere, without interruptions. Enter Koel, an open-source, self-hosted music streaming solution that’s both powerful and user-friendly.

In this comprehensive guide, we’ll walk you through everything you need to know about Koel and how to set it up in your home lab. Whether you’re a seasoned tech enthusiast or a beginner, this step-by-step tutorial will help you create your very own music streaming server.

What Is Koel?

Koel is an open-source web application designed to stream music directly from your personal server. It offers a sleek, modern interface that rivals popular commercial platforms like Spotify or Apple Music. With Koel, you can enjoy complete control over your music library, create custom playlists, and access your tunes from any device with an internet connection.

Koel’s standout features include:

Beautiful Interface: A clean, intuitive design that makes navigation seamless.
Customizable Playlists: Organize your music exactly how you want it.
Advanced Search: Find tracks, albums, or artists with ease.
Multi-User Support: Share your server with family or friends.

Koel is perfect for music enthusiasts who want to break free from the limitations of traditional streaming services and enjoy a personalized listening experience.

Why Host Your Own Music Streaming Server?

Hosting your own music streaming server comes with several benefits:

Uninterrupted Access: No ads, no premium subscriptions, just your music whenever you want it.
Privacy: Your music library remains entirely under your control, without third-party tracking.
Customization: Tailor your server to your preferences, from playlists to interface tweaks.
Cost-Effective: Eliminate recurring subscription fees for popular streaming services.

How to Install Koel in Your Home Lab

Setting up Koel is straightforward, especially if you’re familiar with Docker and command-line interfaces. Follow these steps to get your music streaming server up and running.

Step 1: Clone Koel’s GitHub Repository

Start by cloning Koel’s official Docker repository. Open your terminal and SSH into your Proxmox LXC (or your preferred environment). Use the following command to clone the repository:

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

TIP:
If you prefer, you can download the ZIP file directly from the repository and extract it to your desired location.

Step 2: Navigate to the Koel Folder

Once the repository is cloned, navigate to the newly created koel folder:

cd koel
ls

This will display the contents of the repository, including the Docker Compose files.

Step 3: Configure the Docker Compose File

Koel supports multiple databases. For this guide, we’ll use MySQL. Open the docker-compose.mysql.yml file using a text editor like nano:

nano docker-compose.mysql.yml

Make the necessary changes to the file. Here’s an example configuration:

version: '3'

services:
  koel:
    image: phanan/koel
    depends_on:
      - database
    ports:
      - 8011:80
    environment:
      - DB_CONNECTION=mysql
      - DB_HOST=database
      - DB_USERNAME=koel
      - DB_PASSWORD=
      - DB_DATABASE=koel
      - TRANSCODE_FLAC=false
      - FORCE_HTTPS=true
    volumes:
      - /home/admin/music:/music
      - covers:/var/www/html/public/img/covers
      - search_index:/var/www/html/storage/search-indexes

  database:
    image: mariadb:10.11
    volumes:
      - db:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=
      - MYSQL_DATABASE=koel
      - MYSQL_USER=koel
      - MYSQL_PASSWORD=

volumes:
  db:
    driver: local
  covers:
    driver: local
  search_index:
    driver: local

Key Changes:

Changed the default port to 8011 to avoid conflicts with other services.
Added bind mounts for the music directory and other volumes.
Included environment variables for HTTPS and FLAC transcoding.

Save the file by pressing Ctrl + X, then Y, and Enter.

Step 4: Deploy the Koel Container

Run the following command to deploy the Koel container:

sudo docker-compose -f ./docker-compose.mysql.yml up -d

Once the deployment is complete, verify that the container is running:

sudo docker ps

Configuring Koel for First-Time Use

After installation, you’ll need to perform some initial setup tasks:

Step 1: Generate an App Key and Initialize the Database

Log into the Koel container using the following command:

sudo docker exec --user www-data -it <koel_container_name> bash

Generate the app key and initialize the database:

php artisan koel:init --no-assets

Step 2: Access the Koel Interface

Open your browser and navigate to http://<your-ip>:8011. You’ll be greeted with a login screen. Use the default credentials:

Email: [email protected]
Password: KoelIsCool

NOTE:
Change the default credentials immediately after logging in for security.

Step 3: Scan Your Music Library

If you’ve already added music to the directory specified in the Docker Compose file, you’ll need to perform a manual scan. Go to Settings > Scan to update your library.

Managing Your Music Library

Koel makes it easy to manage your music:

Upload Songs: Drag and drop files directly into the web interface.
Create Playlists: Organize your favorite tracks into custom playlists.
Advanced Search: Quickly find any song, album, or artist.

Conclusion

Congratulations! You’ve successfully set up your own personal music streaming server using Koel. With its user-friendly interface and powerful features, Koel is the perfect solution for anyone looking to take control of their music library.

Stay tuned for our next guide, where we’ll explore more exciting tools to enhance your home lab. Until then, happy streaming—and happy homelabbing!