Installing Koel: Your Personal Music Streaming Server

Koel in Proxmox LXC!!!

Harish Thangadurai
6 min readMay 19, 2024

In the previous article, we delved into the step-by-step process of installing Watchtower in our Home Lab.

Now, let’s focus on another valuable tool to host our very own music streaming server in our Home Lab — Koel.

What is Koel?

Koel is an open-source web application that allows users to stream their music library directly from their own server. With its modern and user-friendly interface, Koel provides a seamless listening experience, reminiscent of popular commercial music streaming platforms. Whether you’re at home or on the go, Koel lets you access your favorite tunes from any device with an internet connection.

Key features of Koel include:

  1. Beautiful Interface
  2. Customizable Playlists
  3. Advanced Searching
  4. Multi-User Support

Steps to install Koel:

  • We’ll be cloning Koel’s official GitHub repository and then deploying the docker-compose file using CLI.
  • First, let us head to the Koel’s docker repository by clicking on the link —
  • Now we can click on the Code option and copy the Web URL link so that we’ll be able to clone the repository. Downloading the ZIP file and extracting the file contents directly to our LXC would also work.
  • Now we can SSH into our Proxmox LXC and use our Promox console to log in. I’ll SSH into mine.
  • Now we can clone the repo by typing in the below command.
git clone koel

Note: The URL given above is the Web URL that we copied from Koel’s repository. ‘koel’ is the folder name where the contents will be copied to.

  • We have now successfully cloned the repository. Now we can enter into the folder ‘koel’.
cd koel
  • We can see various files from the repo that we cloned just now. Now we can make changes to the docker-compose file of our choice depending on the database that we like to host. I’ll just go with the MySQL database.
nano docker-compose.mysql.yml
  • Now, we can make changes to the docker-compose file depending on our needs. I’ll make a few configuration changes to the file.
version: '3'
image: phanan/koel
- database
- 8011:80
- DB_HOST=database
- /home/admin/music:/music
- covers:/var/www/html/public/img/covers
- search_index:/var/www/html/storage/search-indexes
image: mariadb:10.11
- db:/var/lib/mysql
driver: local
driver: local
driver: local
  • Now there are a couple of changes that I have added above. I changed the default port from 80 to 8011 as 80 is occupied in my LXC by Ngnix Proxy Manager.
  • I’ve also changed the volume mount of the music directory with bind mount to a folder in which I have already mounted my music folder from my NAS using NFS.
  • I’ve also added 2 more environment variables ‘TRANSCODE_FLAC’ and ‘FORCE_HTTPS’. Since I was facing issues with HTTPS when configuring my reverse proxy, I’ve added this flag. The TRANSCODE_FLAC variable is used to control the transcoding of FLAC files to MP3 during playback.

Note: The ‘FORCE_HTTPS’ environment variable is not required if there are no issues after configuring Koel along with a reverse proxy. This variable can be removed if a reverse proxy is also not used.

  • Make sure to make the needed changes to the docker-compose file and don’t miss out on adding the passwords for the databases in the file.
  • Once done we can save the file by clicking on Ctrl + X followed by Y and then enter.
  • Now, we can deploy the container by typing in the below command.
sudo docker-compose -f ./docker-compose.mysql.yml up -d

Note: ‘docker-compose.mysql.yml’ is the name of the compose file that we edited and saved just now

  • We have now successfully deployed our Koel instance. We can see if the container has started running by typing in the below command.
sudo docker ps

We have successfully installed the Koel instance in our Home Lab. We now need to make a few more configurations before we can start using it.

Configuring Koel:

  • On the first run, we will need to generate APP_KEY, create an admin user, and initialize the database.
  • All these steps can be achieved by running the below commands. First, we need to log in to the docker container.
sudo docker exec --user www-data -it <koel_container_name> bash

Note: Make sure to replace <koel_container_name> with your own before running the above command.

To find the name of your docker container if not sure, you can type in the below command.

sudo docker ps --format '{{.Names}}'
  • I’ll type in the command with the name of my Koel docker container.
  • Now we can type in the below command to configure for the first run.
php artisan koel:init --no-assets
  • We have now successfully configured our Koel instance. We can now open our instance by typing in IP:8011 (8011 is the port number that I used in my docker-compose file)
  • We will be greeted with the above login screen. Now we can type in the default credentials to log into the same

Default Credentials:
Password: KoelIsCool

Note: Make sure to change the default credentials once after logging in

  • We have now successfully logged in. Initially, the songs will not be shown in our Koel instance if there are any already in the directory that we gave in our docker-compose file.
  • To bring those, we need to perform a manual scan. Also, every time we add new songs to the directory we would need to perform a manual scan for the songs to be reflected in our Koel instance.
  • To perform a manual scan, we can click on the Settings option from the menu on the left side.
  • Now we can click on the Scan option to perform a manual scan of our music directory. Once done, the songs in the directory will be available in our Koel instance.
  • We can also upload songs to the directory directly via Koel. To do this, we can click on the Upload option again from the menu on the left side.
  • Here, we can drag and drop or upload our music files directly and it will be available in our Koel instance without the need for a manual scan.

We have now successfully installed and configured our Koel instance. Now we will have our very own private music streaming service available at all times without any interruption.

In this article, we have explored Koel and went into the step-by-step process of deploying the same in our Home Lab.

In the next article, we will be looking into another service that we will be deploying in our Home Lab. Stay tuned for more detailed instructions on expanding our Home Labbing capabilities.

Happy Homelabbing!!!



Harish Thangadurai

👨‍💻 Automation Engineer | 🌍Tech Explorer | 🧠 Lifelong Learner