Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #20973 -- Document serving static files without django.contrib.…

…staticfiles
  • Loading branch information...
commit 7b04038a7f4b291bc05124c4b5300001dc94e13f 1 parent dd65607
@loic loic authored timgraham committed
View
9 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.
View
52 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:
View
13 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
Please sign in to comment.
Something went wrong with that request. Please try again.