[5 Mins Docker Series] Koel - An Open Source Personel Music Streaming Software - NETSEC


Learning, Sharing, Creating

Cybersecurity Memo

Wednesday, December 7, 2022

[5 Mins Docker Series] Koel - An Open Source Personel Music Streaming Software

Koel is a web-based audio streaming service written in the Laravel PHP framework. It allows you to stream your personal music collection and access it from anywhere in the world. It supports multiple media formats, including AAC, OGG, WMA, FLAC, and APE.

Project site: https://koel.dev/

Koel has the official iOS and Android mobile app, Koel Player. It can connect to your koel-powered server and enjoy the music whenever you may roam, without the unfortunate limitations of the mobile web version. It is also Open-Source, of course. 

In this post, you will learn how to install Koel Music Streaming Server using Docker on a free Onracle Free Tier Ubuntu 20.04 machine.


In this lab, I am using Ubuntu 20.04 VM in Oracle Cloud Free tier as an example. All following commands are based on this Ubuntu 20.04 version Oracle Cloud platform. Please adjust it accordingly if you are using different system or platform. 

For more details about docker, Portainer, NPM configuration, please check following posts:
Commands list after run "sudo -i":

1 System update:

apt update -y && apt upgrade -y

2 Increase SWAP size to at least 1024MB

wget https://raw.githubusercontent.com/51sec/swap/main/swap.sh && bash swap.sh

3 Install Docker and Docker-Compose:

apt install docker.io -y 
apt install docker-compose -y 

4 Install Portainer (Optional):

docker volume create portainer_data

docker run -d -p 9000:9000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

5 Install NPM (Nginx Proxy Manager) (Optional)

docker run -d -p 80:80 -p 81:81 -p 443:443 --name npm --restart unless-stopped -v ./letsencrypt:/etc/letsencrypt -v ./data:/data  jc21/nginx-proxy-manager:latest

6 Install htop program (Optional)

apt install htop -y

7 Enable BBR on Ubuntu 20.04 (Optional)

Open the following configuration file vi /etc/sysctl.conf to enable enable TCP BBR.

vi /etc/sysctl.conf

At the end of the config file, add the following lines.


Save the file, and refresh your configuration by using this command,

sysctl -p


root@vps:~# sysctl -p
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

Now, Verify if BBR is enabled in your system,

sysctl net.ipv4.tcp_congestion_control


root@vps:~# sysctl net.ipv4.tcp_congestion_control
net.ipv4.tcp_congestion_control = bbr


8 Enable IPv6 and Limit Log File Size (Optional)

Add customized self defined IPv6 address segment to enable container's IPv6 fucntion. And limit log file's size and numbers in case log file to fill all hard drive's space. 

cat > /etc/docker/daemon.json << EOF
    "log-driver": "json-file",
    "log-opts": {
        "max-size": "20m",
        "max-file": "3"
    "ipv6": true,
    "fixed-cidr-v6": "fd00:dead:beef:c0::/80",

Restart Docker service:

systemctl restart docker

Koel Docker Installation Steps

Koel has an official Docker image: koel/docker. The latest version is now at phanan/koel:latest.

If you do not have your own vps, you also can experience it by using https://labs.play-with-docker.com/

1 Run with docker-compose and MySQL

docker-compose is the easiest way to get started. It will start both the database container and this image. Clone this repository and edit docker-compose.mysql.yml. Make sure to replace passwords !

2 Check out the ./docker-compose.mysql.yml file for more details.

version: '3'
    image: phanan/koel
      - database
      - 80:80
      - DB_CONNECTION=mysql
      - DB_HOST=database
      - DB_USERNAME=koel
      - DB_PASSWORD=<koel_password>
      - DB_DATABASE=koel
      - music:/music
      - covers:/var/www/html/public/img/covers
      - search_index:/var/www/html/storage/search-indexes
    image: mysql/mysql-server:5.7
      - db:/var/lib/mysql
      - MYSQL_ROOT_PASSWORD=<root_password>
      - MYSQL_DATABASE=koel
      - MYSQL_USER=koel
      - MYSQL_PASSWORD=<koel_password>
    driver: local
    driver: local
    driver: local
    driver: local

3 Then run docker-compose:

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

To stop and remove running containers we brought up, using following two commands:

mv docker-compose.mysql.yml docker-compose.yml

docker-compose down

root@koel-ubuntu-1:~# docker-compose down
Stopping root_koel_1     ... done
Stopping root_database_1 ... done
Removing root_koel_1     ... done
Removing root_database_1 ... done
Removing network root_default

First Run - Init the api and default admin account

On the first run, you will need to:
  • Generate APP_KEY
  • Create an admin user
  • Initialize the database

All these steps are achieved by running koel:init once:

Replace <container_name_for_koel> in the command by the actual container name.

docker exec --user www-data -it <container_name_for_koel> bash

# Once inside the container, you can run commands:

$ php artisan koel:init --no-assets

--no-assets option tells the init command to skip building the front-end assets, as they have been generated by Koel's "Release" GitHub action.

Or directly using to run init command:

docker exec -it root_koel_1 php artisan koel:init

Once inited, it creates one admin account automatically with the following credentials: email: [email protected] password: KoelIsCool

Make sure to change this unsecure password with the user interface (click on your profile picture) or by running the following command:

$ docker exec -it <container_name_for_koel> php artisan koel:admin:change-password

No comments:

Post a Comment