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

[phanan]

Summary

Fixes #220. koel/koel#2479 (v9.3.0) relocated user-uploaded images from public/img/storage/ to storage/app/public/images/ and exposed them via a symlink at public/storage/. The koel/docker image and compose files weren't updated to match, so:

1. Apache 2.4's default Options -SymLinksIfOwnerMatch rejected the new symlink — Symbolic link not allowed or link target not accessible: /var/www/html/public/storage (the 403 in the report).
2. The image_storage named volume was still bound to the old location. The new location (storage/app/public/images) was an ephemeral path inside the container, so it got wiped on each image pull. Users who upgraded 9.2 → 9.3 saw images work until the next container restart, then lost everything.

Changes

• apache.conf: added a <Directory /var/www/html/public> block with Options +FollowSymLinks.
• Dockerfile: VOLUME line now declares /var/www/html/storage/app/public/images (instead of the old public/img/storage). Anonymous-volume users get persistence at the new location by default.
• docker-compose.{mysql,postgres,dev}.yml: image_storage volume now binds to the new path.
• README.md: updated the volume table.
• CHANGELOG.md: upgrade note.

Migration story

The named volume's contents persist regardless of mount point. If a user just edits their docker-compose.yml to change the bind path from /var/www/html/public/img/storage → /var/www/html/storage/app/public/images, their existing image files appear at the new location automatically. No file copying needed.

Users who already upgraded to 9.3.x and lost data (the report's case) will need to restore from backup — there's nothing in this PR that can recover ephemeral-container data that was already wiped on a previous pull.

Test plan

• Build the image locally, run with the updated docker-compose.postgres.yml, verify images load (no 403, no missing files).
• Upgrade scenario: tag an existing volume from the old compose, swap the compose binding, restart container, verify images load.
• CI green.

Summary by CodeRabbit

• Bug Fixes

  • Uploaded images now persist and are served correctly after deployment.
  • Resolved webserver symlink errors so public assets are accessible.

• Documentation

  • Updated deployment docs to reflect the corrected image storage configuration.

• Note

  • If you previously upgraded to an older interim image, some files may have been moved into a transient location—you may need to restore or re-fetch missing images.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 18a5f5d8-a48a-4814-84a2-b5ecba908dab

📥 Commits

Reviewing files that changed from the base of the PR and between ea745de and 9501a4a.

📒 Files selected for processing (1)

• CHANGELOG.md

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

---

📝 Walkthrough

Walkthrough

Image storage mount target moved to /var/www/html/storage/app/public/images across Dockerfile and all compose files; the build creates that directory with www-data ownership. Apache virtual host now allows FollowSymLinks under /var/www/html/public. README and CHANGELOG updated to document the change and legacy upgrade notice.

Changes

Image Storage Path Upgrade

Layer / File(s)	Summary
Docker image storage volume migration Dockerfile, docker-compose.dev.yml, docker-compose.mysql.yml, docker-compose.postgres.yml	Create /var/www/html/storage/app/public/images at build with www-data ownership; update VOLUME and all image_storage compose mounts to target that path instead of public/img/storage.
Apache symlink following configuration apache.conf	Add <Directory /var/www/html/public> to the port 80 vhost enabling FollowSymLinks, AllowOverride All, and Require all granted.
Documentation and changelog updates README.md, CHANGELOG.md	README Volumes section reflects the new image path; CHANGELOG adds 2026-05-22 Fixed entry describing the mount path update, Apache symlink change, and a legacy 9.3.x upgrade caution.

sequenceDiagram
  participant Dockerfile
  participant docker_compose as docker-compose
  participant ContainerFilesystem
  participant Apache
  Dockerfile->>ContainerFilesystem: create /var/www/html/storage/app/public/images + chown www-data
  docker_compose->>ContainerFilesystem: mount image_storage -> /var/www/html/storage/app/public/images
  ContainerFilesystem->>Apache: serve image files via public/storage symlink

Loading

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• [Bug]: Album images are broken #220: Addresses the same image storage mount path change and Apache symlink-following fix described in that issue.

Poem

🐰 I hopped through folders, found a new home,
From public/img to storage where images roam,
Apache now follows each linking trail,
No more broken paths along the trail,
Happy hops — your pictures settle and bloom!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically summarizes the two main changes: aligning image storage paths with koel/koel#2479 and enabling Apache symlink following.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/image-storage-relocation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@Dockerfile`:
- Line 108: The Dockerfile declares a new VOLUME including
"/var/www/html/storage/search-indexes" without ensuring the directory exists or
has the correct ownership; pre-create that path and chown it to the runtime user
before the VOLUME instruction (e.g., use the same owner used for the other
writable mounts) so containers won’t get a root-owned directory that blocks
uploads — add a RUN step to mkdir -p "/var/www/html/storage/search-indexes" and
chown it appropriately prior to the VOLUME declaration.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a380aa40-40c0-4515-be12-def81159ab5a

📥 Commits

Reviewing files that changed from the base of the PR and between 4f62826 and 011b184.

📒 Files selected for processing (7)

• CHANGELOG.md
• Dockerfile
• README.md
• apache.conf
• docker-compose.dev.yml
• docker-compose.mysql.yml
• docker-compose.postgres.yml