[GH-ISSUE #1305] Support Subdirectory Installation

kerem commented

2026-02-26 02:34:10 +03:00

Owner

Originally created by @sergiud on GitHub (Apr 13, 2021).
Original GitHub issue: https://github.com/koel/koel/issues/1305

Describe the bug

I'm running Koel at a non-root location http://myurl/sub/. This mostly works as expected. However, very few links still point to http://myurl/ instead of http://myurl/sub/. Specifically,

static js and img objects are expected to be in the root at http://myurl/js/ and http://myurl/img/ instead of http://myurl/sub/js/ and http://myurl/sub/img/
Both View/edit profile in the header at the upper-right and artist and album links for the currently played track in the footer ignore the /sub part. User profile details can still be accessed under Manage/Users.

To reproduce
Install Koel in a subfolder.

Expected behavior
All links are correct and subfolder location is not ignored.

Environment

Koel v5.1.0
Debian Buster
Chromium 89
PHP v7.3
Node N/A

Originally created by @sergiud on GitHub (Apr 13, 2021). Original GitHub issue: https://github.com/koel/koel/issues/1305 **Describe the bug** I'm running Koel at a non-root location `http://myurl/sub/`. This mostly works as expected. However, very few links still point to `http://myurl/` instead of `http://myurl/sub/`. Specifically, * static `js` and `img` objects are expected to be in the root at `http://myurl/js/` and `http://myurl/img/` instead of `http://myurl/sub/js/` and `http://myurl/sub/img/` * Both *View/edit profile* in the header at the upper-right and artist and album links for the currently played track in the footer ignore the `/sub` part. User profile details can still be accessed under *Manage/Users*. **To reproduce** Install Koel in a subfolder. **Expected behavior** All links are correct and subfolder location is not ignored. **Environment** - Koel v5.1.0 - Debian Buster - Chromium 89 - PHP v7.3 - Node N/A

kerem

2026-02-26 02:34:10 +03:00

closed this issue
added the
[Type] Enhancement

PR Welcome

Feature Request
labels

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@phanan commented on GitHub (Apr 16, 2021):

Koel doesn't officially support subfolder installations though.

@phanan commented on GitHub (Apr 16, 2021): Koel doesn't officially support subfolder installations though.

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@sergiud commented on GitHub (Apr 16, 2021):

Thanks for the feedback.

Possibly I missed this information, but I could not find this restriction in the documentation. According to your previous comment and PR #673 non-root installations are expected to work.

Since these are minor issues, it would be nice if these remaining problems could be resolved as well.

@sergiud commented on GitHub (Apr 16, 2021): Thanks for the feedback. Possibly I missed this information, but I could not find this restriction in the documentation. According to [your previous comment](https://github.com/koel/koel/issues/529#issuecomment-348958601) and PR #673 non-root installations are expected to work. Since these are minor issues, it would be nice if these remaining problems could be resolved as well.

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@sergiud commented on GitHub (Apr 16, 2021):

@fieteboerner Do you happen to know why the links in the header and the footer still make requests to the root URL? All other links seem to work.

@sergiud commented on GitHub (Apr 16, 2021): @fieteboerner Do you happen to know why the links in the header and the footer still make requests to the root URL? All other links seem to work.

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@phanan commented on GitHub (Apr 16, 2021):

Sorry for the confusion. You're right, there was a PR to support this but apparently, it doesn't work so well now. I'm open to a fix :)

@phanan commented on GitHub (Apr 16, 2021): Sorry for the confusion. You're right, there was a PR to support this but apparently, it doesn't work so well now. I'm open to a fix :)

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@sergiud commented on GitHub (Apr 16, 2021):

Great, thank you!

@sergiud commented on GitHub (Apr 16, 2021): Great, thank you!

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@Jodge65 commented on GitHub (Oct 18, 2021):

I'm very interested in this issue, because it's seems to be linked to reverse proxy error.
I'm not hundred percent sure that the following information are relevant for sub-directory problem.

I do some research, and i found the following information :

The player cannot load because of a missing dot in the src

Those lines are generated by an app.js script:

The variable o.p is "/" instead of "./", i try to edit on the go, and it was working.

Unfortunately, i'm not familiar enough with js/ts to locate the part of code that generated this file

@Jodge65 commented on GitHub (Oct 18, 2021): I'm very interested in this issue, because it's seems to be linked to reverse proxy error. I'm not hundred percent sure that the following information are relevant for sub-directory problem. I do some research, and i found the following information : ![image](https://user-images.githubusercontent.com/13049502/137791771-9936b6a4-79c0-4dcb-b99c-3cedaeee76c2.png) The player cannot load because of a missing dot in the src Those lines are generated by an app.js script: ![image](https://user-images.githubusercontent.com/13049502/137791352-4547949a-4659-46b3-9e3e-eb52f9f20fee.png) The variable o.p is "/" instead of "./", i try to edit on the go, and it was working. Unfortunately, i'm not familiar enough with js/ts to locate the part of code that generated this file

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@sergiud commented on GitHub (Oct 19, 2021):

You don't actually need a reverse proxy. For reference, this is how I integrated Koel into an Nginx server instance:

location ~ ^/(js|img) {
    rewrite ^/(.*)$ /music/$1 permanent;
}

location ^~ /music {
    alias           /var/www/koel/public;
    index           index.php;

    gzip            on;
    gzip_types      text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript application/json;
    gzip_comp_level 9;

    if (!-e $request_filename) {
        rewrite ^ /music/index.php last;
    }

    location ~ /media/ {
        internal;

        alias      $upstream_http_x_media_root;

        access_log /var/log/nginx/koel.access.log;
        error_log  /var/log/nginx/koel.error.log;
    }

    location ~ \.php$ {
        fastcgi_param     PATH_INFO $fastcgi_path_info;
        fastcgi_param     PATH_TRANSLATED $document_root$fastcgi_path_info;
        fastcgi_param     SCRIPT_FILENAME $request_filename;

        fastcgi_pass              php;
        fastcgi_index             index.php;
        fastcgi_split_path_info   ^(.+\.php)(/.+)$;
        fastcgi_intercept_errors  on;
        include                   fastcgi_params;
    }
}

You would include the conf in your nginx.conf and then access Koel under <URL>/music.

@sergiud commented on GitHub (Oct 19, 2021): You don't actually need a reverse proxy. For reference, this is how I integrated Koel into an Nginx server instance: ```nginx location ~ ^/(js|img) { rewrite ^/(.*)$ /music/$1 permanent; } location ^~ /music { alias /var/www/koel/public; index index.php; gzip on; gzip_types text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript application/json; gzip_comp_level 9; if (!-e $request_filename) { rewrite ^ /music/index.php last; } location ~ /media/ { internal; alias $upstream_http_x_media_root; access_log /var/log/nginx/koel.access.log; error_log /var/log/nginx/koel.error.log; } location ~ \.php$ { fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; fastcgi_param SCRIPT_FILENAME $request_filename; fastcgi_pass php; fastcgi_index index.php; fastcgi_split_path_info ^(.+\.php)(/.+)$; fastcgi_intercept_errors on; include fastcgi_params; } } ``` You would include the conf in your `nginx.conf` and then access Koel under `<URL>/music`.

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@sergiud commented on GitHub (Sep 23, 2022):

As of Koel 6.2.0, subdirectory installation is still not fully supported. Why close the issue?

@sergiud commented on GitHub (Sep 23, 2022): As of Koel 6.2.0, subdirectory installation is still not fully supported. Why close the issue?

kerem commented

2026-02-26 02:34:11 +03:00

Author

Owner

@PermaFreez commented on GitHub (Feb 24, 2023):

I would like to see this resolved too.

@PermaFreez commented on GitHub (Feb 24, 2023): I would like to see this resolved too.

kerem referenced this issue

2026-02-26 02:34:38 +03:00

[GH-ISSUE #1676] Album Shuffle #917

Rows
Columns

[GH-ISSUE #1305] Support Subdirectory Installation #754