Skip to main content

Logo Koel

About​

Koel is a personal music streaming server.

Increasing the upload limit​

In order to increase the upload limit of the Koel App you need to edit two files with either the Web Terminal or the Web File manager.

Edit the /app/data/php.ini and add the following lines lines - in this example we set the limit to 1GB.

INI
; upload_max_filesize and post_max_size are set to 50M by default
upload_max_filesize = 1G
post_max_size = 1G

Save and close the file.

Now edit the /app/data/public/htaccess file. In this file you should find and edit the following two lines to also represent the new limit of 1GB:

htaccess
php_value upload_max_filesize 1G
php_value post_max_size 1G

Using a mounted volume for the media library​

Koel can stream music from a volume mounted into the app. Volumes appear inside the app container at /media/<volume-name>.

  1. Create a volume in the Volumes view and attach it to the Koel app as a mount.
  2. Open the Koel web UI, go to Settings and set the media path to /media/<volume-name>.
  3. Run a media scan.

The package whitelists /app/data/library and /media for x-sendfile streaming. Libraries placed in either location play without further configuration. The package does not support paths outside these two roots.

Volume permissions​

Volume contents are user data and can be shared across multiple apps. The Koel package does not adjust ownership or permissions on /media/<volume-name> — automatic changes would break other apps that share the same volume.

Koel runs as the www-data user inside the container (UID and GID 33). The library requires the following access for that user:

  • Read access on every directory and file — required for playback.
  • Write access on the library directory and its files — required to edit ID3 tags, delete songs, or upload new ones from the web UI.

Without the correct permissions, scans return empty results, playback fails, and library management actions show errors in the Koel UI.

Set permissions on the host filesystem before attaching the volume:

chown -R 33:33 /path/to/volume/on/host
chmod -R u+rwX,g+rX /path/to/volume/on/host

For CIFS volumes, pass uid=33,gid=33 (and file_mode / dir_mode as needed) in the mount options. CIFS does not honor chown from inside the container.

Use a dedicated volume for Koel when other apps on the same volume expect different ownership.