fix: align image storage with koel/koel#2479 + allow Apache to follow symlinks (#221)

* fix: align image storage with koel/koel#2479 + allow Apache to follow symlinks

* fix: pre-create the image storage path so its ownership is correct

* docs: warn users on 9.3.x that prior data may be lost

---------

Co-authored-by: An Phan <aph@qwello.eu>

Author: phanan

CHANGELOG.md

@@ -5,6 +5,13 @@ 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.
+
+> ⚠ **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`.

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 \
@@ -105,7 +108,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 \

README.md

@@ -114,7 +114,7 @@ docker exec --user www-data <koel_container> 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

apache.conf

@@ -11,6 +11,12 @@
     ServerAdmin webmaster@localhost
     DocumentRoot /var/www/html/public
 
+    <Directory /var/www/html/public>
+        Options +FollowSymLinks
+        AllowOverride All
+        Require all granted
+    </Directory>
+
     # Available loglevels: trace8, ..., trace1, debug, info, notice, warn,
     # error, crit, alert, emerg.
     # It is also possible to configure the loglevel for particular

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

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
 

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: