starred/koel-koel

Fork 0

mirror of https://github.com/koel/koel.git synced 2026-04-25 16:56:02 +03:00

[GH-ISSUE #667] Available documentation for non-dev installation #478

New issue

Closed

opened 2026-02-26 02:33:20 +03:00 by kerem · 5 comments

kerem commented

2026-02-26 02:33:20 +03:00

Owner

Originally created by @kevinboulain on GitHub (Oct 15, 2017).
Original GitHub issue: https://github.com/koel/koel/issues/667

Hi there,

I was wondering if there was some documentation about installing Koel with minimum rights and such (I'm actually running the v3.6.2 release)?
By looking around in the previous issues I saw that you don't want to maintain an installation guide for every different OS and I can understand that.
However, this seems more related to documenting how Koel works and what it expects about its environment so maybe it could be documented to ease a proper non-dev setup?

Here is what I came up with but I don't have much knowledge of PHP/Laravel/Koel/... so please don't hesitate to correct me if I am wrong!

Basic authorization

As I understand it, the front-end part will make use of the Authorization header, conflicting with any basic authentication on top of Koel that a web server may have setup (it works fine to get on the login page but once you try to login, the Authorization header generated by Koel won't be accepted by the web server).
Is there a way to allow basic authentication on the server side (and let Koel use another header)?

Rights

For security purposes, if I want to make the source code read-only so that the PHP processes can't modify it, I'll have to monitor the log file and slowly add more and more permissions on the repository's files as I encounter poblems.

So far everything seems to work by widening the permissions on the following files and folders (I'm trying out the sqlite database without the patch from #599 by setting DB_CONNECTION=sqlite-e2e which seems to work fine for with 1k+ tracks so I'm wondering if the pull request is really needed?):

access to the sqlite database and its journal:

chown root:www-data database
chmod 775 database
chown www-data: database/e2e.sqlite

logs (and other stuff that I don't know but seems required):

chown -R www-data: storage

covers caching (generated during synchronization)

chown www-data: public/img/covers/

Logs

Okay, so in the previous point I added permissions to the storage directory, mainly for the laravel.log file. Does this file need to be rotated? It seems to only get written to when there is a traceback so not much should be written to this file once everything is properly setup.

Also, I can't figure out if there is a way to enable more verbose logging on Koel side (served pages, logged in users, ...).

External access

This one worries me a little and may be a no go but I don't fully grasp the details for now.

By looking around in the issues, I saw that Pusher and Sentry are/were used (it seems Pusher is only a component for Koel and not a service which needs to be contacted, am I right?).
If Koel sends information to some external services (beside the enabled third parties plugins), could this be documented and opt-in by default (I am thinking about Sentry which seems to have been removed but such features that send information on my behalf shouldn't be enabled by default)?

And that's all I can think about for now, thanks for reading and thanks for your work :)

Regards.

Originally created by @kevinboulain on GitHub (Oct 15, 2017). Original GitHub issue: https://github.com/koel/koel/issues/667 Hi there, I was wondering if there was some documentation about installing Koel with minimum rights and such (I'm actually running the `v3.6.2` release)? By looking around in the previous issues I saw that you don't want to maintain an installation guide for every different OS and I can understand that. However, this seems more related to documenting how Koel works and what it expects about its environment so maybe it could be documented to ease a proper non-dev setup? --- Here is what I came up with but I don't have much knowledge of PHP/Laravel/Koel/... so please don't hesitate to correct me if I am wrong! #### Basic authorization As I understand it, the front-end part will make use of the `Authorization` header, conflicting with any basic authentication on top of Koel that a web server may have setup (it works fine to get on the login page but once you try to login, the `Authorization` header generated by Koel won't be accepted by the web server). Is there a way to allow basic authentication on the server side (and let Koel use another header)? #### Rights For security purposes, if I want to make the source code read-only so that the PHP processes can't modify it, I'll have to monitor the log file and slowly add more and more permissions on the repository's files as I encounter poblems. So far everything seems to work by widening the permissions on the following files and folders (I'm trying out the sqlite database without the patch from #599 by setting `DB_CONNECTION=sqlite-e2e` which seems to work fine for with 1k+ tracks so I'm wondering if the pull request is really needed?): - access to the sqlite database and its journal: ```shell chown root:www-data database chmod 775 database chown www-data: database/e2e.sqlite ``` - logs (and other stuff that I don't know but seems required): ```shell chown -R www-data: storage ``` - covers caching (generated during synchronization) ``` chown www-data: public/img/covers/ ``` #### Logs Okay, so in the previous point I added permissions to the `storage` directory, mainly for the `laravel.log` file. Does this file need to be rotated? It seems to only get written to when there is a traceback so not much should be written to this file once everything is properly setup. Also, I can't figure out if there is a way to enable more verbose logging on Koel side (served pages, logged in users, ...). #### External access This one worries me a little and may be a no go but I don't fully grasp the details for now. By looking around in the issues, I saw that Pusher and Sentry are/were used (it seems Pusher is only a component for Koel and not a service which needs to be contacted, am I right?). If Koel sends information to some external services (beside the enabled third parties plugins), could this be documented and opt-in by default (I am thinking about Sentry which seems to have been removed but such features that send information on my behalf shouldn't be enabled by default)? --- And that's all I can think about for now, thanks for reading and thanks for your work :) Regards.

kerem closed this issue

2026-02-26 02:33:20 +03:00

kerem commented

2026-02-26 02:33:20 +03:00

Author

Owner

@phanan commented on GitHub (Oct 15, 2017):

Hi there. Thanks for expressing your concerns. I'll try to answer them one by one below, feel free to let me know if anything is unclear and/or needs to be discussed further:

Basic authorization

You're right: Koel makes use of the Authorization: Bearer header. IMO this is quite a standard, and any conflict with "basic authentications" on top of Koel should be considered an edge case and won't be supported. Actually, I don't quite get the issue here – doesn't basic auth use Authorization: Basic instead? Anyway, this much likely will remain as it is now.

Rights

I really don't see the necessity to "secure" the server side by altering the default file/folder permissions that way. But of course, if you have valid reasons to do so, the server-side part of Koel is nothing more than a normal PHP application, and you have total control over it. There's nothing specific for Koel to do here.

Logs

I myself don't have to rotate log, but again, it's up to you. As Koel is built on Laravel, If you want more granular control over its logging, I'd suggest reading Laravel's dosc.

External access

Pusher is not used – not in the current stable version. Even if it's to be used in a future version, it would be totally optional, just like how YouTube and Last.fm are atm. Sentry, on the other hand, was purely experimental and had been removed after @X-Ryl669 kindly expressed his (and others') concern regarding privacy.

@phanan commented on GitHub (Oct 15, 2017): Hi there. Thanks for expressing your concerns. I'll try to answer them one by one below, feel free to let me know if anything is unclear and/or needs to be discussed further: ## Basic authorization You're right: Koel makes use of the `Authorization: Bearer` header. IMO this is quite a standard, and any conflict with "basic authentications" on top of Koel should be considered an edge case and won't be supported. Actually, I don't quite get the issue here – doesn't basic auth use `Authorization: Basic` instead? Anyway, this much likely will remain as it is now. ## Rights I really don't see the necessity to "secure" the server side by altering the default file/folder permissions that way. But of course, if you have valid reasons to do so, the server-side part of Koel is nothing more than a normal PHP application, and you have total control over it. There's nothing specific for Koel to do here. ## Logs I myself don't have to rotate `log`, but again, it's up to you. As Koel is built on Laravel, If you want more granular control over its logging, I'd suggest reading [Laravel's dosc](https://laravel.com/docs/5.4/errors). ## External access Pusher is not used – not in the current stable version. Even if it's to be used in a future version, it would be totally optional, just like how YouTube and Last.fm are atm. Sentry, on the other hand, was purely experimental and had been removed after @X-Ryl669 kindly expressed his (and others') concern regarding privacy.

kerem commented

2026-02-26 02:33:20 +03:00

Author

Owner

@kevinboulain commented on GitHub (Oct 15, 2017):

Regarding the Authorization: Basic ... header: yes, I saw that Koel was sending Authorization: Bearer (null|$token) however it seems it's actually overwriting the basic part in my case so the server requiring the header is denying further requests (maybe appending to the header would resolve the issue).
If I don't need to expose Koel to the world, an easy way to deny access would be with an htpasswd (I could deny access based on IP but it make sharing way more difficult).

This leads me to the basic security setup: the best practices would be to disallow the application to overwrite its sources (look at how much WordPress users are complaining about their PHP files being modified and as such, need to reinstall it because now the whole installation is compromised... I'm not saying Koel would have the same problem, just that's is easy to avoid). I also chroot'd Koel via PHP-FPM and everything is working so far so I'm quite happy with the actual setup.
If you don't say much about the files list that I posted, I'll assume it's fairly standard (once you know a bit of Laravel?) and enough for Koel to work (it wasn't that hard to come with the list but the user still have to try out a couple of times before getting it right so a little documentation about which directories need to be writable by Koel would have been nice).

I'll check out out Laravel documentation a bit more.

Finally, for the privacy parts, it's nice to see it's not overlooked.

Thanks!

PS: should the wiki remains closed? I could have shared some notes like I did in #661 and you wouldn't have to maintain it, that's the goal of a community wiki (that could help a little bit some people looking at how much issues there are about installation problems) :)

@kevinboulain commented on GitHub (Oct 15, 2017): Regarding the `Authorization: Basic ...` header: yes, I saw that Koel was sending `Authorization: Bearer (null|$token)` however it seems it's actually overwriting the basic part in my case so the server requiring the header is denying further requests (maybe appending to the header would resolve the issue). If I don't need to expose Koel to the world, an easy way to deny access would be with an htpasswd (I could deny access based on IP but it make sharing way more difficult). This leads me to the basic security setup: the best practices would be to disallow the application to overwrite its sources (look at how much WordPress users are complaining about their PHP files being modified and as such, need to reinstall it because now the whole installation is compromised... I'm not saying Koel would have the same problem, just that's is easy to avoid). I also chroot'd Koel via PHP-FPM and everything is working so far so I'm quite happy with the actual setup. If you don't say much about the files list that I posted, I'll assume it's fairly standard (once you know a bit of Laravel?) and enough for Koel to work (it wasn't that hard to come with the list but the user still have to try out a couple of times before getting it right so a little documentation about which directories need to be writable by Koel would have been nice). I'll check out out Laravel documentation a bit more. Finally, for the privacy parts, it's nice to see it's not overlooked. Thanks! PS: should the wiki remains closed? I could have shared some notes like I did in #661 and you wouldn't have to maintain it, that's the goal of a community wiki (that could help a little bit some people looking at how much issues there are about installation problems) :)

kerem commented

2026-02-26 02:33:20 +03:00

Author

Owner

@phanan commented on GitHub (Oct 15, 2017):

The wiki is not closed, it's just moved to https://github.com/koel/docs/.

@phanan commented on GitHub (Oct 15, 2017): The wiki is not closed, it's just moved to https://github.com/koel/docs/.

kerem commented

2026-02-26 02:33:20 +03:00

Author

Owner

@kevinboulain commented on GitHub (Oct 15, 2017):

Yeah, I know you moved the wiki but you could have enabled users to edit the repository's wiki and just tell them to write/read the installation tutorials there (could be less issues and work for you).

By the way, I modified resources/assets/js/services/http.js and tried to add the Basic ... part in axios.interceptors.request.use, it seems it's not supported to have two authentication methods here (and thinking about it, I'm not sure the JavaScript code could retrieve the information given to the browser anyway) [EDIT: I mean, if a put only the Basic one, the web server accepts it but not Koel (of course), but I can't seem to make it work with both].
So unless Koel uses another header to do its authentication (which it seems doesn't please you), the Basic one doesn't seem possible.

@kevinboulain commented on GitHub (Oct 15, 2017): Yeah, I know you moved the wiki but you could have enabled users to edit the repository's wiki and just tell them to write/read the installation tutorials there (could be less issues and work for you). By the way, I modified `resources/assets/js/services/http.js` and tried to add the `Basic ...` part in `axios.interceptors.request.use`, it seems it's not supported to have two authentication methods here (and thinking about it, I'm not sure the JavaScript code could retrieve the information given to the browser anyway) [**EDIT**: I mean, if a put only the Basic one, the web server accepts it but not Koel (of course), but I can't seem to make it work with both]. So unless Koel uses another header to do its authentication (which it seems doesn't please you), the Basic one doesn't seem possible.

kerem commented

2026-02-26 02:33:20 +03:00

Author

Owner

@X-Ryl669 commented on GitHub (Oct 16, 2017):

What are you trying to achieve with basic authentication ?

If you intend to have your own CMS or login system, then you can have a look at my fork. What I did is:

Write a small .php file that's bootstrapping the Laravel app, and mainly, the JWT token generation. This file does use its own authentication, so you can have basic authentication going here if you want.
Modify JS code to bypass the authentication login form when authentication token is provided (by my new file)

Hope it helps.

@X-Ryl669 commented on GitHub (Oct 16, 2017): What are you trying to achieve with basic authentication ? If you intend to have your own CMS or login system, then you can have a look at my fork. What I did is: 1. Write a small `.php` file that's bootstrapping the Laravel app, and mainly, the JWT token generation. This file does use its own authentication, so you can have basic authentication going here if you want. 2. Modify JS code to bypass the authentication login form when authentication token is provided (by my new file) Hope it helps.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/koel-koel#478

No description provided.

Rows
Columns