Code

Opened 5 years ago

Closed 3 years ago

Last modified 3 years ago

#10650 closed (fixed)

Clarify use of MEDIA_ROOT in default settings.py

Reported by: tvon Owned by: jjconti
Component: Documentation Version: 1.0
Severity: Keywords: pycamp2010
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

I had a bit of a palm-to-face moment when I realized that MEDIA_ROOT was *not* a place to stick media files to be served up by the development server. Maybe the bizarre way in which my brain functions made me the one and only person that would make this mistake (seriously, it's possible), but I figure this coudl also be a point of confusion for people new to Django, so I propose a small adjustment to the generated settings.py:

From:

# Absolute path to the directory that holds media.
# Example: "/home/media/media.lawrence.com/"
MEDIA_ROOT = ''

To:

# Absolute path to the directory that will hold uploaded media.
# Example: "/home/media/media.lawrence.com/"
MEDIA_ROOT = ''

Attachments (1)

10650_jjconti.diff (540 bytes) - added by jjconti 4 years ago.
Add suggested line of doc.

Download all attachments as: .zip

Change History (19)

comment:1 Changed 5 years ago by thatch

  • Component changed from Uncategorized to File uploads/storage
  • milestone set to 1.2
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Design decision needed

comment:2 Changed 5 years ago by vak

he-he, I use django one year but am still having broken img, css, js when using runserver. neither docu nor settings.py gave me a clear view on what and where is token from... ;)

comment:3 follow-up: Changed 5 years ago by Muhammad Alkarouri

By looking at the internet, I say this is a serious conceptual bug in Django.

I have spent some time trying to wrap my head around this. And you get all kind of different advice. For example,you get this http://oebfare.com/blog/2007/dec/31/django-and-static-files/ which I have to admit was following for some time. On the other hand, the documentation for static files is actually correct (http://docs.djangoproject.com/en/dev/howto/static-files/) and it suggests a new setting, STATIC_DOC_ROOT, for that.

My suggestion would be to:

  1. Clarify the documentation of MEDIA_ROOT and MEDIA_URL as per the bug report
  1. Give more visibility to django.views.static.serve as a debug time way of serving static files. Practically every project needs to serve static files, and there is no point in not standardising the process.
  1. Explain clearly the alternative way in deployment time. For example, if deployed behind apache/mod_wsgi, the static directory can be configured directly from apache as part of the deployment process.

If this is acceptable, I may look into providing the specific documentation patches needed, though I have to say I do not know where to start at the moment.

comment:4 in reply to: ↑ 3 ; follow-up: Changed 5 years ago by ramiro

Replying to Muhammad Alkarouri:

  1. Give more visibility to django.views.static.serve as a debug time way of serving static files. Practically every project needs to serve static files, and there is no point in not standardising the process.

This is also covered bi #11229.

I'd suggest to attack item 1 in this ticket as originally reported, and to open another one for item 3 so not to broaden its scope.

comment:5 in reply to: ↑ 4 Changed 5 years ago by malkarouri

Replying to ramiro:

I'd suggest to attack item 1 in this ticket as originally reported, and to open another one for item 3 so not to broaden its scope.

Good point. I'd say that #11229 actually covers item 3 rather than 2. I may open another ticket for item 2 once I figure out what I think is wrong with http://docs.djangoproject.com/en/dev/howto/static-files/ , if anything.

So I think this ticket can be resolved by accepting the original proposed solution and making corresponding changes to the documentation http://docs.djangoproject.com/en/dev/ref/settings/#media-root .

comment:6 Changed 5 years ago by thiggins

  • Summary changed from Clarify use of MEDIA_ROOT in default settings.py to Commented on original ticket

I want to confirm that the description given for MEDIA_ROOT, "absolute path to the directory that holds media," is, like the word media itself, too vague to convey a determinate meaning. At the least, an uninitiated person will have difficulty with it. Let me further suggest the following additional refinement:

# Absolute path to the directory that will hold uploaded media.
# Example: "/home/media/uploaded-media.lawrence.com/"
MEDIA_ROOT = ''

We know that lawrence.com is a newspaper outlet. One tends to associate newspapers with outbound media, mainly. This change removes a semantic stumbling-block.

Finally, if someone could prevail upon Brian Rosner to update or amend his blog post, http://oebfare.com/blog/2007/dec/31/django-and-static-files/, that would be helpful.

comment:7 Changed 5 years ago by thiggins

  • Summary changed from Commented on original ticket to Commented on description of MEDIA_ROOT

comment:8 Changed 5 years ago by brosner

  • Summary changed from Commented on description of MEDIA_ROOT to Clarify use of MEDIA_ROOT in default settings.py

The summary field isn't a summary of your comment, but rather the ticket title. ;-) Reverting.

comment:9 Changed 5 years ago by brosner

Help me here. I understand the splitting of MEDIA_ROOT and what the documentation suggests STATIC_DOC_ROOT. Which, by the way, was added well after my blog post went up. What I don't get is why this is such an issue? I've used MEDIA_ROOT for both static media and uploaded media (as it is used for prepending the upload_to path) with no issues. There was no conceptual issue I see there. I wouldn't put completely missing the point pass me at this point ;-)

comment:10 Changed 5 years ago by thiggins

Brian, thanks for tuning in. Your latest point is well taken. After all, MEDIA_ROOT is just a root. It could easily have two folders under it, one for incoming and one for outgoing media. I also see that the ongoing process of software/documentation design has created the appearance of a conceptual disparity between the very terse official documentation and your blog post. I think what is desired first by the uninitiated, like myself and perhaps vak and Muhammad Alkarouri above, is a clear path to getting pages served, while still in the development phase, with CSS and images intact. Your blog attempts to assist with this, and I promise to study it again with improved insight.

I had been having a several-days-long email conversation with my CS graduate son on the correct setup of MEDIA_ROOT. I took the point of view that it is for all static files. He insisted that it is for uploads only, pointing to this ticket, and saying:

"Read this ticket. Someone even mentions the blog post you linked. http://code.djangoproject.com/ticket/10650

Notice in the blog post he makes use of MEDIA_ROOT and MEDIA_URL himself, passing it along to static.serve. He could have called these settings anything. He's confusing people by using settings that Django uses for something else.

Unfortunately, Django is also at fault for being far too vague in its docs about what MEDIA_ROOT and MEDIA_URL are used for. Searching through Django's code confirms that MEDIA_ROOT & MEDIA_URL are used for file upload, and that MEDIA_URL is provided as a convenience to templates via the default context processors (available when using RequestContext?)."

Thus persuaded, I agreed with him, but now see that what we have is merely a conceptual misunderstanding; if we users wire everything right we will get good results even if we put MEDIA_ROOT to the additional use of housing our served static media. STATIC_DOC_ROOT is a suggestion, and could be under MEDIA_ROOT anyway, and perhaps that would typically be sensible. Tidying up the ideas presented in the official documentation would have helped speed my process along, however.

By the way, I would not personally say "Django is at fault." This is a wonderful product in the throes of a major creative upheaval and I am very excited about the extraordinary results I am seeing. Keep up the good work, please!

comment:11 Changed 4 years ago by ubernostrum

  • Component changed from File uploads/storage to Documentation

This is really a documentation issue masquerading as something else.

comment:12 Changed 4 years ago by jjconti

  • Owner changed from nobody to jjconti
  • Status changed from new to assigned

Files to modify?

django/conf/global_settings.py

Changed 4 years ago by jjconti

Add suggested line of doc.

comment:13 Changed 4 years ago by jjconti

  • Keywords pycamp2010 added

comment:14 Changed 4 years ago by ramiro

  • Triage Stage changed from Design decision needed to Ready for checkin

Patch also applies to 1.1.X branch with a line offset warning.

comment:15 Changed 4 years ago by russellm

  • Triage Stage changed from Ready for checkin to Accepted

This isn't ready for trunk. As the discsussion on this ticket indicates, it isn't just a matter of changing global_settings.py (which is largely invisible to the end user) -- there's a clarification of the role of MEDIA_ROOT and MEDIA_URL that is required.

comment:16 Changed 4 years ago by russellm

  • milestone 1.2 deleted

Deferring due to the absence of a trunk-ready patch.

comment:17 Changed 3 years ago by ramiro

  • Resolution set to fixed
  • Status changed from assigned to closed

(In [14560]) Fixed #10650 -- Clarified description of MEDIA_ROOT in setting files. Thanks jjconti, tvon, vak, Muhammad Alkarouri and thiggins for their work.

comment:18 Changed 3 years ago by ramiro

(In [14561]) [1.2.X] Fixed #10650 -- Clarified description of MEDIA_ROOT in setting files. Thanks jjconti, tvon, vak, Muhammad Alkarouri and thiggins for their work.

Backport of [14560] from trunk

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.