Serving Uploaded Media in Production: How a Small PR Became a Hardened Fix in BrightBean Studio

A candid look at a fix where the maintainer did most of the work after the first commit.

Réponse courte

In production, BrightBean Studio wrote uploaded files to disk but answered every request for them with a 404, which also broke publishing. The pull request replaced a DEBUG-only media route with a setting-controlled one. A maintainer then fixed a syntax error in the original commit and pushed three more commits that scoped and hardened the route. The result was merged as PR #156 and closed issue #130.

The problem

BrightBean Studio is a Django app for managing and publishing social media content. Issue #130 reported a self-hosted Docker deployment using local file storage. The file existed on disk:

$-rw-r--r-- 1 root root 10285 Jul 23 17:03 Leads.png

but the request returned Not Found: /media/media_library/2026/07/Leads.png. The reporter traced it. Production settings force DEBUG = False, and Django's static() helper only adds media routes when DEBUG is on.

What the PR proposed

The first commit added a SERVE_MEDIA setting, on by default for local storage and always off for S3. It also replaced the DEBUG-gated helper with a django.views.static.serve route guarded by that flag. The change touched five files, with 21 lines added and 7 removed. Its description claimed a regression test, but the original commit included none; the tests described below came from the maintainer.

What the maintainer added

The maintainer's first commit message is blunt. In the original change, "config/settings/base.py did not parse: the closing brace of STORAGES["default"] and the AWS_S3_ENDPOINT_URL assignment shared a line, so every environment failed to boot regardless of storage backend and all four CI jobs failed."

From there, the maintainer's commits:

• Moved route construction into config.urls.media_urlpatterns() and refused to build a catch-all pattern when the media prefix is empty.
• Served /media/ directly from Caddy, which also gives uploads byte-range support for video seeking.
• Exempted /media/ from the terms-of-service middleware and skipped RBAC context resolution for static and media paths.
• Limited the public route to an allowlist of upload prefixes (media_library/, avatars/, workspaces/icons/), so internal comment attachments are not publicly readable.
• Stored uploads under the extension their sniffed MIME type justifies, closing a content-type issue with polyglot files.
• Added tests/test_media_routing.py and further tests for the setting.

One finding raised the stakes. Because the publisher sends media URLs to platforms that fetch them server-side, "the 404 fixed here was failing publishes, not just thumbnails."

By the numbers

• Repository: brightbeanxyz/brightbean-studio, 2,612 stars (Nov 3, 2026), Python, AGPL-3.0
• Files changed: 18
• Lines: +807 / -15 (the original commit was +21 / -7)
• Commits: 5 (1 from the PR author, 4 from a maintainer)
• Opened: Aug 21, 2026. Merged: Sep 17, 2026. Time to merge: 27 days, 4 hours
• Review: merged by the maintainer who extended it

How the review went

The first public reaction came from a user affected by the bug: "Thanks for the pull request. It will be great it this is merged." The maintainer then took the branch over and pushed the commits above. One of their commits attributes three of the findings to an automated code review pass.

Takeaways

• The diagnosis and direction were right, but the first patch didn't boot. That is the honest part of this story.
• Media serving touches routing, auth middleware, a reverse proxy and file validation. A narrow first patch was never going to cover all of it, and the maintainer's commits show why.

FAQ

Is media now public?

Only the allowlisted prefixes are served without authentication. According to the maintainer's commit, this is necessary because publishing platforms fetch those files server-side. Comment attachments are served behind a workspace membership check.

Where can I read more?

See the pull request and the original issue.

Le but

A pull request can be valuable even when it isn't the final word. Here it put a concrete change in front of the maintainer, who turned it into a fix they were willing to ship.