Listen to your own music-related files on the go, anytime you want. Koel is a web-based personal audio streaming service written in Vue on the client side and Laravel on the server side. streaming service written in Vue on the client side and Laravel on the server side.
Install it using Docker, following the official instructions. Click on the Github link in the instructions for more details. Official Docker images are also available.
https://hub.docker.com/r/phanan/koel
Now let’s get to work. The environment to be installed is Ubuntu 22.04 OS. First, we need to acquire the image.
docker pull phanan/koelNext, start the koel container according to the instructions. koel requires a database, but this Docker command does not include a database.
docker run -d --name koel \
-p 8888:80 \
-v music:/music \
-v covers:/var/www/html/public/img/covers \
-v search_index:/var/www/html/storage/search-indexes \
phanan/koelThe firewall was enabled, so open it.
ufw allow 8888/tcp
ufw statusThe database is located on a separate server in the same network, where MySQL Community Server is installed and an empty database is created. The database is located on a separate server within the same network, with a MySQL Community Server installed and an empty database created, and the user is allowed to connect and operate externally.
Database Configuration
As previously mentioned, the database was set up on a separate server within the same network. This server had MySQL Community Server installed, and users were allowed to connect and operate from external locations. However, when creating a MySQL container using Docker, external connections might be allowed by default. Although this is often restricted to localhost connections, in a typical MySQL installation, external connections must be manually enabled, which might cause some confusion.
Therefore, I will now explain how to set up a MySQL container using Docker, create the necessary users and databases, and allow external connections in a way that is easy for beginners to understand.
- Creating the MySQL Container
First, create a MySQL container using Docker. Keep in mind that external connections might be allowed by default, so make sure to check and adjust the settings as needed.docker run --name mysql-container -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest
This command will start the MySQL container and create a root user with the passwordmy-secret-pw. - Creating a New Database
Next, connect to the MySQL container and create a new database.docker exec -it mysql-container mysql -u root -p
Once you have access to the MySQL command line, create a new database.CREATE DATABASE mydatabase; - Creating a User and Granting Permissions
Create a user that is allowed to connect externally and grant the necessary permissions.CREATE USER 'newuser'@'%' IDENTIFIED BY 'userpassword';GRANT ALL PRIVILEGES ON mydatabase.* TO 'newuser'@'%';FLUSH PRIVILEGES;
The%symbol is a wildcard that allows connections from any external host, but you can specify a particular IP address for security purposes. - Verifying External Connections
Finally, confirm that the external connections are properly configured. This step is crucial from a security standpoint.
When the database is ready, enter the koel container and enter the command that allows initial configuration. Enter the container as the specified user.
docker exec --user www-data -it koel bash
php artisan koel:init --no-assets
After setting up the database name, user name, port number, etc., access it with a browser.
http://IP address:8888
Log in with the following email address and password
email: admin@koel.dev
password: KoelIsCool
To change these for better security, type the command
docker exec -it <container_name_for_koel> php artisan koel:admin:change-passwordNote that it was also possible to change the password by logging in with a browser instead of entering the command.
Since we are going to go through the trouble, let’s upload an mp3 file to check the operation.
The uploaded file will be saved under the following directory on the host side. Of course, you can also check it in the container.
/var/lib/docker/volumes/
cd /var/lib/docker/volumes/The koel container only supports the common web port, so consider installing a reverse proxy if you want to create SSL-capable pages.
In the previous guide, I explained how to set up the database on a separate server. This time, I will walk you through the steps to create containers for both Koel and the database on the same server. Additionally, as Koel has been updated over time, I will update the article accordingly. We will proceed based on the following GitHub page:
https://github.com/koel/docker
Cloning the Repository
First, clone the repository from GitHub. This command will create a clone and generate a directory containing the docker-compose.mysql.yml file.
git clone https://github.com/koel/docker.git
Using the docker-compose File
After cloning the repository, navigate to the directory containing the docker-compose.mysql.yml file and run the following command to start the containers.
docker-compose -f ./docker-compose.mysql.yml up -d
Depending on your environment, you may need to use the docker compose command as follows:
docker compose -f ./docker-compose.mysql.yml up -d
By following these steps, you should be able to set up both Koel and the database on the same server, making it easy for beginners to build the environment.
Initial Setup Procedures
When you run Koel for the first time, you’ll need to complete the following steps:
- Generate an APP_KEY
- Create an admin user
- Initialize the database
All of these steps can be accomplished at once by running the koel:init command.
Execution Steps
First, enter the Koel container by running the following command.
Replace <container_name_for_koel> with the actual name of your Koel container.
docker exec --user www-data -it <container_name_for_koel> bash
Once inside the container, run the following command to perform the initial setup:
php artisan koel:init --no-assets
The --no-assets option is used to skip building the front-end assets since they have already been generated by Koel’s “Release” GitHub action.
Default Admin Account
Note: Starting from version 5.1.0, Koel no longer asks for a username, email, and password for the admin account. Instead, it automatically creates an account with the following credentials:
- Email:
admin@koel.dev - Password:
KoelIsCool
Since this default password is not secure, make sure to change it through the user interface (by clicking on your profile picture) or by running the following command:
docker exec -it <container_name_for_koel> php artisan koel:admin:change-password
Note on Port 80 Conflicts
If port 80 is already in use on your host, you may encounter conflicts. In this case, you can either specify a different port in the docker-compose.yml file or stop the existing service. For example, to change the host-side port to 8080, configure it as follows:
ports:
- "8080:80"
This setting will redirect any access to port 8080 on the host to port 80 inside the container.
Note on Volume Mounting
The docker-compose.mysql.yml file specifies volumes for storing music files, cover images, and other data. These volumes link directories on the host side with directories inside the container, ensuring that the data is persisted.
If you want to specify a particular host directory, you can change the mount path in the docker-compose.mysql.yml file. For example, if you want to store music files in a specific directory on the host, you can configure it as follows:
volumes:
- /path/to/your/music:/music
By setting it up this way, your data will be saved in the specified directory on the host, and it will not be lost even if you recreate the container.