From 011b1846ea89cdb409f309bc99855a994db54c71 Mon Sep 17 00:00:00 2001 From: An Phan Date: Fri, 22 May 2026 15:38:19 +0200 Subject: [PATCH 1/3] fix: align image storage with koel/koel#2479 + allow Apache to follow symlinks --- CHANGELOG.md | 5 +++++ Dockerfile | 2 +- README.md | 2 +- apache.conf | 6 ++++++ docker-compose.dev.yml | 2 +- docker-compose.mysql.yml | 2 +- docker-compose.postgres.yml | 2 +- 7 files changed, 16 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fdb05ab..b5f2624 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Since this docker image only has one tag which is `latest`, there are no versions. However we'll write changes with the date at which they occured. +## 2026-05-22 +### Fixed +- ⚠ Image storage path moved to follow koel/koel#2479. If you're upgrading from a previous release, update your `docker-compose.yml` so the `image_storage` volume binds to `/var/www/html/storage/app/public/images` instead of `/var/www/html/public/img/storage`. Existing data in your `image_storage` volume / host bind transfers over automatically when you switch the mount point — files inside the volume don't move, only the mount path inside the container does. +- Apache now follows symlinks under the document root, fixing the `Symbolic link not allowed or link target not accessible: /var/www/html/public/storage` error introduced when the new image path was symlinked. + ## 2022-04-15 ### Changed - ⚠ BREAKING CHANGE: Image name has changed, it is now [`phanan/koel`](https://hub.docker.com/r/phanan/koel) instead of `hyzual/koel`. diff --git a/Dockerfile b/Dockerfile index 8da5412..7b42e53 100644 --- a/Dockerfile +++ b/Dockerfile @@ -105,7 +105,7 @@ RUN cp -R /tmp/koel/. /var/www/html \ # This declaration must be AFTER creating the folders and setting their permissions # and AFTER changing to non-root user. # Otherwise, they are owned by root and the user cannot write to them. -VOLUME ["/music", "/var/www/html/public/img/storage", "/var/www/html/storage/search-indexes"] +VOLUME ["/music", "/var/www/html/storage/app/public/images", "/var/www/html/storage/search-indexes"] RUN cd /var/www/html \ && php artisan route:cache \ diff --git a/README.md b/README.md index 869a816..979e9d8 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ docker exec --user www-data php artisan koel:sync | Path | Description | |---|---| | `/music` | Your music library. | -| `/var/www/html/public/img/storage` | Uploaded images (album art, user avatars, etc.). | +| `/var/www/html/storage/app/public/images` | Uploaded images (album art, user avatars, etc.). | | `/var/www/html/storage/search-indexes` | Search indexes for songs, albums, and artists. | ## Ports diff --git a/apache.conf b/apache.conf index f46933e..98ce5e2 100644 --- a/apache.conf +++ b/apache.conf @@ -11,6 +11,12 @@ ServerAdmin webmaster@localhost DocumentRoot /var/www/html/public + + Options +FollowSymLinks + AllowOverride All + Require all granted + + # Available loglevels: trace8, ..., trace1, debug, info, notice, warn, # error, crit, alert, emerg. # It is also possible to configure the loglevel for particular diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 2663072..87ef044 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -17,7 +17,7 @@ services: - DB_PASSWORD=password volumes: - music:/music - - image_storage:/var/www/html/public/img/storage + - image_storage:/var/www/html/storage/app/public/images - search_index:/var/www/html/storage/search-indexes - ./.env.koel:/var/www/html/.env - ./sql:/docker-entrypoint-initdb.d diff --git a/docker-compose.mysql.yml b/docker-compose.mysql.yml index 608a22e..c5e0b89 100644 --- a/docker-compose.mysql.yml +++ b/docker-compose.mysql.yml @@ -13,7 +13,7 @@ services: - DB_DATABASE=koel volumes: - music:/music - - image_storage:/var/www/html/public/img/storage + - image_storage:/var/www/html/storage/app/public/images - search_index:/var/www/html/storage/search-indexes - ./sql:/docker-entrypoint-initdb.d diff --git a/docker-compose.postgres.yml b/docker-compose.postgres.yml index d0dcff1..97eb6c0 100644 --- a/docker-compose.postgres.yml +++ b/docker-compose.postgres.yml @@ -14,7 +14,7 @@ services: - DB_DATABASE=koel volumes: - music:/music - - image_storage:/var/www/html/public/img/storage + - image_storage:/var/www/html/storage/app/public/images - search_index:/var/www/html/storage/search-indexes database: From ea745de67789182ae6cebaece470ab194cf51679 Mon Sep 17 00:00:00 2001 From: An Phan Date: Fri, 22 May 2026 15:57:03 +0200 Subject: [PATCH 2/3] fix: pre-create the image storage path so its ownership is correct --- Dockerfile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Dockerfile b/Dockerfile index 7b42e53..a366a66 100644 --- a/Dockerfile +++ b/Dockerfile @@ -81,6 +81,9 @@ RUN apt-get update \ # Create the search-indexes volume so it has the correct permissions && mkdir -p /var/www/html/storage/search-indexes \ && chown www-data:www-data /var/www/html/storage/search-indexes \ + # Same for the image storage volume + && mkdir -p /var/www/html/storage/app/public/images \ + && chown -R www-data:www-data /var/www/html/storage/app \ # Set locale to prevent removal of non-ASCII path characters when transcoding with ffmpeg # See https://github.com/koel/docker/pull/91 && echo "en_US.UTF-8 UTF-8" > /etc/locale.gen \ From 9501a4a823d89ec501e4254bb8cec80816e78884 Mon Sep 17 00:00:00 2001 From: An Phan Date: Sat, 23 May 2026 18:44:36 +0200 Subject: [PATCH 3/3] docs: warn users on 9.3.x that prior data may be lost --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b5f2624..41f0add 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ Since this docker image only has one tag which is `latest`, there are no version - ⚠ Image storage path moved to follow koel/koel#2479. If you're upgrading from a previous release, update your `docker-compose.yml` so the `image_storage` volume binds to `/var/www/html/storage/app/public/images` instead of `/var/www/html/public/img/storage`. Existing data in your `image_storage` volume / host bind transfers over automatically when you switch the mount point — files inside the volume don't move, only the mount path inside the container does. - Apache now follows symlinks under the document root, fixing the `Symbolic link not allowed or link target not accessible: /var/www/html/public/storage` error introduced when the new image path was symlinked. +> ⚠ **Heads-up if you already upgraded to a 9.3.x image before this fix.** koel/koel's `koel:init` ran a one-time `migrateLegacyImages` step that *moved* files (destructive) from `public/img/storage/` into the in-container `storage/app/public/images/`. On Docker that target was ephemeral, so the files were wiped on the next image pull and your `image_storage` volume / host bind is now empty. There's nothing this fix can do to recover that — restore from backup if you have one, or let koel re-fetch album / artist art from your source media on the next scan. + ## 2022-04-15 ### Changed - ⚠ BREAKING CHANGE: Image name has changed, it is now [`phanan/koel`](https://hub.docker.com/r/phanan/koel) instead of `hyzual/koel`.