Clarify use of MEDIA_ROOT in default settings.py

[Tom von Schwerdtner]

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 = ''

[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... ;)

[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

2. 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.

3. 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.

[Ramiro Morales]

Replying to Muhammad Alkarouri:

2. 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.

[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 .

[thiggins]

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.

[Brian Rosner]

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

[Brian Rosner]

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 ;-)

[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!

[James Bennett]

This is really a documentation issue masquerading as something else.

[jjconti]

Files to modify?

django/conf/global_settings.py

[jjconti]

Add suggested line of doc.

[Ramiro Morales]

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

[Russell Keith-Magee]

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.

[Russell Keith-Magee]

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

[Ramiro Morales]

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

[Ramiro Morales]

(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