Say which side of the volume mount has to match the download client - #1
Merged
Conversation
added 2 commits
July 29, 2026 22:52
The downloads volume comment never said which side of the colon it meant, and
its example contradicted the line beneath it: it said "if qBittorrent says
/downloads/complete, mount it at /downloads/complete" above a mapping that ends
in :/downloads. A reader could not tell whether to change the right side, and
the library volume two lines up gets this right ("the left side is the host; the
right side must match LIBRARY_PATH"), so the inconsistency read as meaningful.
Reported by a user who had followed other apps' instructions asking for the host
path -- both readings are half true, which is exactly the problem.
It now names the sides, works the example through with both changing, covers the
client-on-the-host case where they end up identical, and says where qBittorrent
and SABnzbd display the value so it can be copied rather than guessed.
A wrong mount also failed unhelpfully. It reported "download path does not
exist", which sends people hunting for a download that is sitting in their
client -- the file is fine, this process just cannot see that path. The reason
now says "in this container", names the path tried, and gives both remedies.
map_remote_path warns when the path it returns is not openable, and it is the
only place that knows both the reported and translated paths -- the difference
between them is the whole diagnosis, and it distinguishes a missing mount from a
mapping whose local side is wrong.
Also covers map_remote_path with tests, which had none: prefix rewriting,
longest-match-wins regardless of row order, half-filled rows being ignored, and
Windows-style remote paths.
165 tests pass.
The README carried the identical wording to the compose file -- "mount the downloads volume at the path your download client reports", with no mention of which side of the colon, above a docker run example ending in :/downloads. A fix that landed in only one of the two places would have left the contradiction intact for anyone reading the other. It now says the container side is the one that must match, shows a mapping with both sides differing, names where qBittorrent and SABnzbd display the value, and covers the client-on-the-host case. Also documents what the remote path mapping section could not say before: the log now names both the reported and the translated path, which is what distinguishes "no mapping matched" from "a mapping matched and its local side is wrong".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The downloads volume comment in
docker-compose.ymlnever said which side of the colon it meant, and its example contradicted the line beneath it:A reader cannot tell whether to change the right side. The library volume two lines up gets this right — "the left side is the host; the right side must match LIBRARY_PATH" — so the inconsistency reads as meaningful rather than accidental.
Reported by a user who had followed other apps' instructions asking for the host path, while another reader took it as the container path. Both readings are half true, which is the problem: the host side only has to be the directory holding the files, and the container side is the one that must match what the client reports.
Docs
The comment now names the sides, works the example through with both sides changing, covers the client-on-the-host case where they end up identical, and says where qBittorrent and SABnzbd display the value so it can be copied rather than guessed.
A wrong mount also failed unhelpfully
It reported
download path does not exist, which sends people hunting for a download that is sitting in their client — the file is fine, this process just cannot see that path.map_remote_pathwarns when the path it returns is not openable. It is the only place that knows both the reported and the translated path, and the difference between them is the whole diagnosis — it distinguishes a missing mount from a mapping whose local side is wrong.Tests
map_remote_pathhad none. Added: prefix rewriting, longest-match-wins regardless of row order, half-filled mapping rows being ignored, Windows-style remote paths, and the warning behaviour both ways.149 tests pass.
docker compose configvalidates.🤖 Generated with Claude Code