From 7b04038a7f4b291bc05124c4b5300001dc94e13f Mon Sep 17 00:00:00 2001 From: Loic Bistuer Date: Sun, 1 Sep 2013 11:04:32 +0700 Subject: [PATCH] Fixed #20973 -- Document serving static files without django.contrib.staticfiles --- docs/howto/deployment/wsgi/modwsgi.txt | 9 +++-- docs/howto/static-files/index.txt | 52 +++++++++++++++++++++----- docs/ref/settings.txt | 13 +++++++ 3 files changed, 61 insertions(+), 13 deletions(-) diff --git a/docs/howto/deployment/wsgi/modwsgi.txt b/docs/howto/deployment/wsgi/modwsgi.txt index 1d11e94685b..9b7805c55e4 100644 --- a/docs/howto/deployment/wsgi/modwsgi.txt +++ b/docs/howto/deployment/wsgi/modwsgi.txt @@ -173,10 +173,11 @@ will be served using mod_wsgi:: Serving the admin files ======================= -Note that the Django development server automatically serves the static files -of the admin app (and any other installed apps), but this is not the case when -you use any other server arrangement. You're responsible for setting up Apache, -or whichever media server you're using, to serve the admin files. +When :mod:`django.contrib.staticfiles` is in :setting:`INSTALLED_APPS`, the +Django development server automatically serves the static files of the +admin app (and any other installed apps). This is however not the case when you +use any other server arrangement. You're responsible for setting up Apache, or +whichever Web server you're using, to serve the admin files. The admin files live in (:file:`django/contrib/admin/static/admin`) of the Django distribution. diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index b4231199163..57020910534 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -40,9 +40,9 @@ Configuring static files In addition to these configuration steps, you'll also need to actually serve the static files. - During development, this will be done automatically if you use - :djadmin:`runserver` and :setting:`DEBUG` is set to ``True`` (see - :func:`django.contrib.staticfiles.views.serve`). + During development, if you use :mod:`django.contrib.staticfiles`, this will + be done automatically by :djadmin:`runserver` when :setting:`DEBUG` is set + to ``True`` (see :func:`django.contrib.staticfiles.views.serve`). This method is **grossly inefficient** and probably **insecure**, so it is **unsuitable for production**. @@ -76,15 +76,49 @@ details on how ``staticfiles`` finds your files. application itself. -Serving files uploaded by a user -================================ +Serving static files during development. +======================================== + +If you use :mod:`django.contrib.staticfiles` as explained above, +:djadmin:`runserver` will do this automatically when :setting:`DEBUG` is set +to ``True``. If you don't have ``django.contrib.staticfiles`` in +:setting:`INSTALLED_APPS`, you can still manually serve static files using the +:func:`django.contrib.staticfiles.views.serve` view. + +This is not suitable for production use! For some common deployment +strategies, see :doc:`/howto/static-files/deployment`. + +For example, if your :setting:`STATIC_URL` is defined as ``/static/``, you can do +this by adding the following snippet to your urls.py:: + + from django.conf import settings + from django.conf.urls.static import static + + urlpatterns = patterns('', + # ... the rest of your URLconf goes here ... + ) + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT) + +.. note:: + + This helper function works only in debug mode and only if + the given prefix is local (e.g. ``/static/``) and not a URL (e.g. + ``http://static.example.com/``). + + Also this helper function only serves the actual :setting:`STATIC_ROOT` + folder; it doesn't perform static files discovery like + `:mod:`django.contrib.staticfiles`. + +Serving files uploaded by a user during development. +==================================================== During development, you can serve user-uploaded media files from :setting:`MEDIA_ROOT` using the :func:`django.contrib.staticfiles.views.serve` -view. This is not suitable for production use! For some common deployment +view. + +This is not suitable for production use! For some common deployment strategies, see :doc:`/howto/static-files/deployment`. -For example, if your :setting:`MEDIA_URL` is defined as '/media/', you can do +For example, if your :setting:`MEDIA_URL` is defined as ``/media/``, you can do this by adding the following snippet to your urls.py:: from django.conf import settings @@ -97,8 +131,8 @@ this by adding the following snippet to your urls.py:: .. note:: This helper function works only in debug mode and only if - the given prefix is local (e.g. ``/static/``) and not a URL (e.g. - ``http://static.example.com/``). + the given prefix is local (e.g. ``/media/``) and not a URL (e.g. + ``http://media.example.com/``). .. _staticfiles-testing-support: diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index b0bc020f477..a8b629e693e 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -1448,6 +1448,14 @@ Example: ``"/var/www/example.com/media/"`` See also :setting:`MEDIA_URL`. +.. warning:: + + :setting:`MEDIA_ROOT` and :setting:`STATIC_ROOT` must have different + values. Before :setting:`STATIC_ROOT` was introduced, it was common to + rely or fallback on :setting:`MEDIA_ROOT` to also serve static files; + however, since this can have serious security implications, there is a + validation check to prevent it. + .. setting:: MEDIA_URL MEDIA_URL @@ -1461,6 +1469,11 @@ to a non-empty value. Example: ``"http://media.example.com/"`` +.. warning:: + + :setting:`MEDIA_URL` and :setting:`STATIC_URL` must have different + values. See :setting:`MEDIA_ROOT` for more details. + .. setting:: MIDDLEWARE_CLASSES MIDDLEWARE_CLASSES