Opened 15 years ago

Closed 13 years ago

Last modified 13 years ago

#10650 closed (fixed)

Clarify use of MEDIA_ROOT in default settings.py

Reported by: Tom von Schwerdtner 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: no UI/UX: no

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 14 years ago.
Add suggested line of doc.

Download all attachments as: .zip

Change History (19)

comment:1 by thatch, 15 years ago

Component: UncategorizedFile uploads/storage
milestone: 1.2
Triage Stage: UnreviewedDesign decision needed

comment:2 by vak, 15 years ago

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 by Muhammad Alkarouri, 15 years ago

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.

in reply to:  3 ; comment:4 by Ramiro Morales, 15 years ago

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.

in reply to:  4 comment:5 by malkarouri, 15 years ago

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 by thiggins, 15 years ago

Summary: Clarify use of MEDIA_ROOT in default settings.pyCommented 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 by thiggins, 15 years ago

Summary: Commented on original ticketCommented on description of MEDIA_ROOT

comment:8 by Brian Rosner, 15 years ago

Summary: Commented on description of MEDIA_ROOTClarify 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 by Brian Rosner, 15 years ago

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 by thiggins, 15 years ago

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 by James Bennett, 14 years ago

Component: File uploads/storageDocumentation

This is really a documentation issue masquerading as something else.

comment:12 by jjconti, 14 years ago

Owner: changed from nobody to jjconti
Status: newassigned

Files to modify?

django/conf/global_settings.py

by jjconti, 14 years ago

Attachment: 10650_jjconti.diff added

Add suggested line of doc.

comment:13 by jjconti, 14 years ago

Keywords: pycamp2010 added

comment:14 by Ramiro Morales, 14 years ago

Triage Stage: Design decision neededReady for checkin

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

comment:15 by Russell Keith-Magee, 14 years ago

Triage Stage: Ready for checkinAccepted

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 by Russell Keith-Magee, 14 years ago

milestone: 1.2

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

comment:17 by Ramiro Morales, 13 years ago

Resolution: fixed
Status: assignedclosed

(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 by Ramiro Morales, 13 years ago

(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

Note: See TracTickets for help on using tickets.
Back to Top