innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Fixed #19897 - Updated static files howto. 

Thanks Jan Murre, Reinout van Rees and Wim Feijen,
plus Remco Wendt for reviewing.
This commit is contained in:
Tim Graham 2013-03-07 14:15:39 -05:00
parent c32fc79aa1
commit 6c730da1f6
22 changed files with 340 additions and 481 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/howto/deployment/checklist.txt
View File

@ -113,7 +113,7 @@ Static files are automatically served by the development server. In
production, you must define a :setting:`STATIC_ROOT` directory where production, you must define a :setting:`STATIC_ROOT` directory where
:djadmin:`collectstatic` will copy them. :djadmin:`collectstatic` will copy them.
See :doc:`/howto/static-files` for more information. See :doc:`/howto/static-files/index` for more information.
:setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL`
---------------------------------------------- ----------------------------------------------

3
docs/howto/index.txt
View File

@ -21,7 +21,8 @@ you quickly accomplish common tasks.
legacy-databases legacy-databases
outputting-csv outputting-csv
outputting-pdf outputting-pdf
static-files static-files/index
static-files/deployment
.. seealso:: .. seealso::

159
docs/howto/static-files/deployment.txt Normal file
View File

@ -0,0 +1,159 @@
======================
Deploying static files
======================
.. seealso::
For an introduction to the use of :mod:`django.contrib.staticfiles`, see
:doc:`/howto/static-files/index`.
.. _staticfiles-production:
Serving static files in production
==================================
The basic outline of putting static files into production is simple: run the
:djadmin:`collectstatic` command when static files change, then arrange for
the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
the static file server and served. Depending on :setting:`STATICFILES_STORAGE`,
files may need to be moved to a new location manually or the :func:`post_process
<django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method
of the ``Storage`` class might take care of that.
Of course, as with all deployment tasks, the devil's in the details. Every
production setup will be a bit different, so you'll need to adapt the basic
outline to fit your needs. Below are a few common patterns that might help.
Serving the site and your static files from the same server
-----------------------------------------------------------
If you want to serve your static files from the same server that's already
serving your site, the process may look something like:
* Push your code up to the deployment server.
* On the server, run :djadmin:`collectstatic` to copy all the static files
into :setting:`STATIC_ROOT`.
* Configure your web server to serve the files in :setting:`STATIC_ROOT`
under the URL :setting:`STATIC_URL`. For example, here's
:ref:`how to do this with Apache and mod_wsgi <serving-files>`.
You'll probably want to automate this process, especially if you've got
multiple web servers. There's any number of ways to do this automation, but
one option that many Django developers enjoy is `Fabric
<http://fabfile.org/>`_.
Below, and in the following sections, we'll show off a few example fabfiles
(i.e. Fabric scripts) that automate these file deployment options. The syntax
of a fabfile is fairly straightforward but won't be covered here; consult
`Fabric's documentation <http://docs.fabfile.org/>`_, for a complete
explanation of the syntax.
So, a fabfile to deploy static files to a couple of web servers might look
something like::
from fabric.api import *
# Hosts to deploy onto
env.hosts = ['www1.example.com', 'www2.example.com']
# Where your project code lives on the server
env.project_root = '/home/www/myproject'
def deploy_static():
with cd(env.project_root):
run('./manage.py collectstatic -v0 --noinput')
Serving static files from a dedicated server
--------------------------------------------
Most larger Django sites use a separate Web server -- i.e., one that's not also
running Django -- for serving static files. This server often runs a different
type of web server -- faster but less full-featured. Some common choices are:
* lighttpd_
* Nginx_
* TUX_
* Cherokee_
* A stripped-down version of Apache_
.. _lighttpd: http://www.lighttpd.net/
.. _Nginx: http://wiki.nginx.org/Main
.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
.. _Apache: http://httpd.apache.org/
.. _Cherokee: http://www.cherokee-project.com/
Configuring these servers is out of scope of this document; check each
server's respective documentation for instructions.
Since your static file server won't be running Django, you'll need to modify
the deployment strategy to look something like:
* When your static files change, run :djadmin:`collectstatic` locally.
* Push your local :setting:`STATIC_ROOT` up to the static file server into the
directory that's being served. `rsync <https://rsync.samba.org/>`_ is a
common choice for this step since it only needs to transfer the bits of
static files that have changed.
Here's how this might look in a fabfile::
from fabric.api import *
from fabric.contrib import project
# Where the static files get collected locally. Your STATIC_ROOT setting.
env.local_static_root = '/tmp/static'
# Where the static files should go remotely
env.remote_static_root = '/home/www/static.example.com'
@roles('static')
def deploy_static():
local('./manage.py collectstatic')
project.rsync_project(
remote_dir = env.remote_static_root,
local_dir = env.local_static_root,
delete = True
)
.. _staticfiles-from-cdn:
Serving static files from a cloud service or CDN
------------------------------------------------
Another common tactic is to serve static files from a cloud storage provider
like Amazon's S3 and/or a CDN (content delivery network). This lets you
ignore the problems of serving static files and can often make for
faster-loading webpages (especially when using a CDN).
When using these services, the basic workflow would look a bit like the above,
except that instead of using ``rsync`` to transfer your static files to the
server you'd need to transfer the static files to the storage provider or CDN.
There's any number of ways you might do this, but if the provider has an API a
:doc:`custom file storage backend </howto/custom-file-storage>` will make the
process incredibly simple. If you've written or are using a 3rd party custom
storage backend, you can tell :djadmin:`collectstatic` to use it by setting
:setting:`STATICFILES_STORAGE` to the storage engine.
For example, if you've written an S3 storage backend in
``myproject.storage.S3Storage`` you could use it with::
STATICFILES_STORAGE = 'myproject.storage.S3Storage'
Once that's done, all you have to do is run :djadmin:`collectstatic` and your
static files would be pushed through your storage package up to S3. If you
later needed to switch to a different storage provider, it could be as simple
as changing your :setting:`STATICFILES_STORAGE` setting.
For details on how you'd write one of these backends, see
:doc:`/howto/custom-file-storage`. There are 3rd party apps available that
provide storage backends for many common file storage APIs. A good starting
point is the `overview at djangopackages.com
<https://www.djangopackages.com/grids/g/storage-backends/>`_.
Learn more
==========
For complete details on all the settings, commands, template tags, and other
pieces included in :mod:`django.contrib.staticfiles`, see :doc:`the
staticfiles reference </ref/contrib/staticfiles>`.

527
docs/howto/static-files/index.txt
View File

@ -1,314 +1,79 @@
===================== ===================================
Managing static files Managing static files (CSS, images)
===================== ===================================
Django developers mostly concern themselves with the dynamic parts of web Websites generally need to serve additional files such as images, JavaScript,
applications -- the views and templates that render anew for each request. But or CSS. In Django, we refer to these files as "static files". Django provides
web applications have other parts: the static files (images, CSS, :mod:`django.contrib.staticfiles` to help you manage them.
Javascript, etc.) that are needed to render a complete web page.
For small projects, this isn't a big deal, because you can just keep the This page describes how you can serve these static files.
static files somewhere your web server can find it. However, in bigger
projects -- especially those comprised of multiple apps -- dealing with the
multiple sets of static files provided by each application starts to get
tricky.
That's what ``django.contrib.staticfiles`` is for: it collects static files Configuring static files
from each of your applications (and any other places you specify) into a ========================
single location that can easily be served in production.
.. note:: 1. Make sure that ``django.contrib.staticfiles`` is included in your
If you've used the `django-staticfiles`_ third-party app before, then
``django.contrib.staticfiles`` will look very familiar. That's because
they're essentially the same code: ``django.contrib.staticfiles`` started
its life as `django-staticfiles`_ and was merged into Django 1.3.
If you're upgrading from ``django-staticfiles``, please see `Upgrading from
django-staticfiles`_, below, for a few minor changes you'll need to make.
.. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/
Using ``django.contrib.staticfiles``
====================================
Basic usage
-----------
1. Put your static files somewhere that ``staticfiles`` will find them.
By default, this means within ``static/`` subdirectories of apps in your
:setting:`INSTALLED_APPS`. :setting:`INSTALLED_APPS`.
Your project will probably also have static assets that aren't tied to a 2. In your settings file, define :setting:`STATIC_URL`, for example::
particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of
filesystem directories to check when loading static files. It's a search
path that is by default empty. See the :setting:`STATICFILES_DIRS` docs
how to extend this list of additional paths.
Additionally, see the documentation for the :setting:`STATICFILES_FINDERS` STATIC_URL = '/static/'
setting for details on how ``staticfiles`` finds your files.
2. Make sure that ``django.contrib.staticfiles`` is included in your 3. In your templates, either hardcode the url like
:setting:`INSTALLED_APPS`. ``/static/my_app/myexample.jpg`` or, preferably, use the
:ttag:`static<staticfiles-static>` template tag to build the URL for the given
relative path by using the configured :setting:`STATICFILES_STORAGE` storage
(this makes it much easier when you want to switch to a content delivery
network (CDN) for serving static files).
For :ref:`local development<staticfiles-development>`, if you are using .. _staticfiles-in-templates:
:ref:`runserver<staticfiles-runserver>` or adding
:ref:`staticfiles_urlpatterns<staticfiles-development>` to your
URLconf, you're done with the setup -- your static files will
automatically be served at the default (for
:djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`
of ``/static/``.
3. You'll probably need to refer to these files in your templates. The
easiest method is to use the included context processor which allows
template code like:
.. code-block:: html+django .. code-block:: html+django
<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" /> {% load staticfiles %}
<img src="{% static "my_app/myexample.jpg" %}" alt="My image"/>
See :ref:`staticfiles-in-templates` for more details, **including** an 3. Store your static files in a folder called ``static`` in your app. For
alternate method using a template tag. example ``my_app/static/my_app/myimage.jpg``.
Deploying static files in a nutshell Now, if you use ``./manage.py runserver``, all static files should be served
------------------------------------ automatically at the :setting:`STATIC_URL` and be shown correctly.
When you're ready to move out of local development and deploy your project: Your project will probably also have static assets that aren't tied to a
particular app. In addition to using a ``static/`` directory inside your apps,
you can define a list of directories (:setting:`STATICFILES_DIRS`) in your
settings file where Django will also look for static files. For example::
1. Set the :setting:`STATIC_URL` setting to the public URL for your static STATICFILES_DIRS = (
files (in most cases, the default value of ``/static/`` is just fine). os.path.join(BASE_DIR, "static"),
'/var/www/static/',
2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path
you'd like your static files collected to when you use the
:djadmin:`collectstatic` management command. For example::
STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
3. Run the :djadmin:`collectstatic` management command::
./manage.py collectstatic
This'll churn through your static file storage and copy them into the
directory given by :setting:`STATIC_ROOT`.
4. Deploy those files by configuring your webserver of choice to serve the
files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.
:ref:`staticfiles-production` covers some common deployment strategies
for static files.
Those are the **basics**. For more details on common configuration options,
read on; for a detailed reference of the settings, commands, and other bits
included with the framework see
:doc:`the staticfiles reference </ref/contrib/staticfiles>`.
.. note::
In previous versions of Django, it was common to place static assets in
:setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both
at :setting:`MEDIA_URL`. Part of the purpose of introducing the
``staticfiles`` app is to make it easier to keep static files separate
from user-uploaded files.
For this reason, you need to make your :setting:`MEDIA_ROOT` and
:setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and
:setting:`STATIC_URL`. You will need to arrange for serving of files in
:setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with
user-uploaded files at all. You can, however, use
:func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`
in development; see :ref:`staticfiles-other-directories`.
.. _staticfiles-in-templates:
Referring to static files in templates
======================================
At some point, you'll probably need to link to static files in your templates.
You could, of course, simply hardcode the path to you assets in the templates:
.. code-block:: html
<img src="http://static.example.com/static/myimage.jpg" alt="Sample image" />
Of course, there are some serious problems with this: it doesn't work well in
development, and it makes it *very* hard to change where you've deployed your
static files. If, for example, you wanted to switch to using a content
delivery network (CDN), then you'd need to change more or less every single
template.
A far better way is to use the value of the :setting:`STATIC_URL` setting
directly in your templates. This means that a switch of static files servers
only requires changing that single value. Much better!
Django includes multiple built-in ways of using this setting in your
templates: a context processor and a template tag.
With a context processor
------------------------
The included context processor is the easy way. Simply make sure
``'django.core.context_processors.static'`` is in your
:setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're
editing that setting by hand it should look something like::
TEMPLATE_CONTEXT_PROCESSORS = (
'django.core.context_processors.debug',
'django.core.context_processors.i18n',
'django.core.context_processors.media',
'django.core.context_processors.static',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
) )
Once that's done, you can refer to :setting:`STATIC_URL` in your templates: See the documentation for the :setting:`STATICFILES_FINDERS` setting for
details on how ``staticfiles`` finds your files.
.. code-block:: html+django .. admonition:: Static file namespacing
<img src="{{ STATIC_URL }}images/hi.jpg" alt="Hi!" /> Now we *might* be able to get away with putting our static files directly
in ``my_app/static/`` (rather than creating another ``my_app``
subdirectory), but it would actually be a bad idea. Django will use the
last static file it finds whose name matches, and if you had a static file
with the same name in a *different* application, Django would be unable to
distinguish between them. We need to be able to point Django at the right
one, and the easiest way to ensure this is by *namespacing* them. That is,
by putting those static files inside *another* directory named for the
application itself.
If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not
using :class:`~django.template.RequestContext` when rendering the template.
As a brief refresher, context processors add variables into the contexts of Serving files uploaded by a user
every template. However, context processors require that you use ================================
:class:`~django.template.RequestContext` when rendering templates. This happens
automatically if you're using a :doc:`generic view </ref/class-based-views/index>`,
but in views written by hand you'll need to explicitly use ``RequestContext``
To see how that works, and to read more details, check out
:ref:`subclassing-context-requestcontext`.
Another option is the :ttag:`get_static_prefix` template tag that is part of During development, you can serve user-uploaded media files from
Django's core. :setting:`MEDIA_ROOT` 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`.
With a template tag For example, if your :setting:`MEDIA_URL` is defined as '/media/', you can do
------------------- this by adding the following snippet to your urls.py::
The more powerful tool is the :ttag:`static<staticfiles-static>` template
tag. It builds the URL for the given relative path by using the configured
:setting:`STATICFILES_STORAGE` storage.
.. code-block:: html+django
{% load staticfiles %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!"/>
It is also able to consume standard context variables, e.g. assuming a
``user_stylesheet`` variable is passed to the template:
.. code-block:: html+django
{% load staticfiles %}
<link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />
.. note::
There is also a template tag named :ttag:`static` in Django's core set
of :ref:`built in template tags<ref-templates-builtins-tags>` which has
the same argument signature but only uses `urlparse.urljoin()`_ with the
:setting:`STATIC_URL` setting and the given path. This has the
disadvantage of not being able to easily switch the storage backend
without changing the templates, so in doubt use the ``staticfiles``
:ttag:`static<staticfiles-static>`
template tag.
.. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin
.. _staticfiles-development:
Serving static files in development
===================================
The static files tools are mostly designed to help with getting static files
successfully deployed into production. This usually means a separate,
dedicated static file server, which is a lot of overhead to mess with when
developing locally. Thus, the ``staticfiles`` app ships with a
**quick and dirty helper view** that you can use to serve files locally in
development.
This view is automatically enabled and will serve your static files at
:setting:`STATIC_URL` when you use the built-in
:ref:`runserver<staticfiles-runserver>` management command.
To enable this view if you are using some other server for local development,
you'll add a couple of lines to your URLconf. The first line goes at the top
of the file, and the last line at the bottom::
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
# ... the rest of your URLconf goes here ...
urlpatterns += staticfiles_urlpatterns()
This will inspect your :setting:`STATIC_URL` setting and wire up the view
to serve static files accordingly. Don't forget to set the
:setting:`STATICFILES_DIRS` setting appropriately to let
``django.contrib.staticfiles`` know where to look for files additionally to
files in app directories.
.. warning::
This will only work if :setting:`DEBUG` is ``True``.
That's because this view is **grossly inefficient** and probably
**insecure**. This is only intended for local development, and should
**never be used in production**.
Additionally, when using ``staticfiles_urlpatterns`` your
:setting:`STATIC_URL` setting can't be empty or a full URL, such as
``http://static.example.com/``.
For a few more details on how the ``staticfiles`` can be used during
development, see :ref:`staticfiles-development-view`.
.. _staticfiles-other-directories:
Serving other directories
-------------------------
.. currentmodule:: django.views.static
.. function:: serve(request, path, document_root, show_indexes=False)
There may be files other than your project's static assets that, for
convenience, you'd like to have Django serve for you in local development.
The :func:`~django.views.static.serve` view can be used to serve any directory
you give it. (Again, this view is **not** hardened for production
use, and should be used only as a development aid; you should serve these files
in production using a real front-end webserver).
The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
``staticfiles`` is intended for static assets and has no built-in handling
for user-uploaded files, but you can have Django serve your
:setting:`MEDIA_ROOT` by appending something like this to your URLconf::
from django.conf import settings
# ... the rest of your URLconf goes here ...
if settings.DEBUG:
urlpatterns += patterns('',
url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
'document_root': settings.MEDIA_ROOT,
}),
)
Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
``'/media/'``. This will call the :func:`~django.views.static.serve` view,
passing in the path from the URLconf and the (required) ``document_root``
parameter.
.. currentmodule:: django.conf.urls.static
.. function:: static(prefix, view='django.views.static.serve', **kwargs)
Since it can become a bit cumbersome to define this URL pattern, Django
ships with a small URL helper function
:func:`~django.conf.urls.static.static` that takes as parameters the prefix
such as :setting:`MEDIA_URL` and a dotted path to a view, such as
``'django.views.static.serve'``. Any other function parameter will be
transparently passed to the view.
An example for serving :setting:`MEDIA_URL` (``'/media/'``) during
development::
from django.conf import settings from django.conf import settings
from django.conf.urls.static import static from django.conf.urls.static import static
@ -319,190 +84,36 @@ development::
.. note:: .. note::
This helper function will only be operational in debug mode and if 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. the given prefix is local (e.g. ``/static/``) and not a URL (e.g.
``http://static.example.com/``). ``http://static.example.com/``).
.. _staticfiles-production: Deployment
==========
Serving static files in production :mod:`django.contrib.staticfiles` provides a convenience management command
================================== for gathering static files in a single directory so you can serve them easily.
The basic outline of putting static files into production is simple: run the 1. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd
:djadmin:`collectstatic` command when static files change, then arrange for like to serve these files, for example::
the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
the static file server and served.
Of course, as with all deployment tasks, the devil's in the details. Every STATIC_ROOT = "/var/www/example.com/static/"
production setup will be a bit different, so you'll need to adapt the basic
outline to fit your needs. Below are a few common patterns that might help.
Serving the app and your static files from the same server 2. Run the :djadmin:`collectstatic` management command::
----------------------------------------------------------
If you want to serve your static files from the same server that's already ./manage.py collectstatic
serving your site, the basic outline gets modified to look something like:
* Push your code up to the deployment server. This will copy all files from your static folders into the
* On the server, run :djadmin:`collectstatic` to copy all the static files :setting:`STATIC_ROOT` directory.
into :setting:`STATIC_ROOT`.
* Point your web server at :setting:`STATIC_ROOT`. For example, here's
:ref:`how to do this under Apache and mod_wsgi <serving-files>`.
You'll probably want to automate this process, especially if you've got 3. Use a webserver of your choice to serve the
multiple web servers. There's any number of ways to do this automation, but files. :doc:`/howto/static-files/deployment` covers some common deployment
one option that many Django developers enjoy is `Fabric`__. strategies for static files.
__ http://fabfile.org/
Below, and in the following sections, we'll show off a few example fabfiles
(i.e. Fabric scripts) that automate these file deployment options. The syntax
of a fabfile is fairly straightforward but won't be covered here; consult
`Fabric's documentation`__, for a complete explanation of the syntax..
__ http://docs.fabfile.org/
So, a fabfile to deploy static files to a couple of web servers might look
something like::
from fabric.api import *
# Hosts to deploy onto
env.hosts = ['www1.example.com', 'www2.example.com']
# Where your project code lives on the server
env.project_root = '/home/www/myproject'
def deploy_static():
with cd(env.project_root):
run('./manage.py collectstatic -v0 --noinput')
Serving static files from a dedicated server
--------------------------------------------
Most larger Django apps use a separate Web server -- i.e., one that's not also
running Django -- for serving static files. This server often runs a different
type of web server -- faster but less full-featured. Some good choices are:
* lighttpd_
* Nginx_
* TUX_
* Cherokee_
* A stripped-down version of Apache_
.. _lighttpd: http://www.lighttpd.net/
.. _Nginx: http://wiki.nginx.org/Main
.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
.. _Apache: http://httpd.apache.org/
.. _Cherokee: http://www.cherokee-project.com/
Configuring these servers is out of scope of this document; check each
server's respective documentation for instructions.
Since your static file server won't be running Django, you'll need to modify
the deployment strategy to look something like:
* When your static files change, run :djadmin:`collectstatic` locally.
* Push your local :setting:`STATIC_ROOT` up to the static file server
into the directory that's being served. ``rsync`` is a good
choice for this step since it only needs to transfer the
bits of static files that have changed.
Here's how this might look in a fabfile::
from fabric.api import *
from fabric.contrib import project
# Where the static files get collected locally
env.local_static_root = '/tmp/static'
# Where the static files should go remotely
env.remote_static_root = '/home/www/static.example.com'
@roles('static')
def deploy_static():
local('./manage.py collectstatic')
project.rsync_project(
remote_dir = env.remote_static_root,
local_dir = env.local_static_root,
delete = True
)
.. _staticfiles-from-cdn:
Serving static files from a cloud service or CDN
------------------------------------------------
Another common tactic is to serve static files from a cloud storage provider
like Amazon's S3__ and/or a CDN (content delivery network). This lets you
ignore the problems of serving static files, and can often make for
faster-loading webpages (especially when using a CDN).
When using these services, the basic workflow would look a bit like the above,
except that instead of using ``rsync`` to transfer your static files to the
server you'd need to transfer the static files to the storage provider or CDN.
There's any number of ways you might do this, but if the provider has an API a
:doc:`custom file storage backend </howto/custom-file-storage>` will make the
process incredibly simple. If you've written or are using a 3rd party custom
storage backend, you can tell :djadmin:`collectstatic` to use it by setting
:setting:`STATICFILES_STORAGE` to the storage engine.
For example, if you've written an S3 storage backend in
``myproject.storage.S3Storage`` you could use it with::
STATICFILES_STORAGE = 'myproject.storage.S3Storage'
Once that's done, all you have to do is run :djadmin:`collectstatic` and your
static files would be pushed through your storage package up to S3. If you
later needed to switch to a different storage provider, it could be as simple
as changing your :setting:`STATICFILES_STORAGE` setting.
For details on how you'd write one of these backends,
:doc:`/howto/custom-file-storage`.
.. seealso::
The `django-storages`__ project is a 3rd party app that provides many
storage backends for many common file storage APIs (including `S3`__).
__ http://s3.amazonaws.com/
__ http://code.larlet.fr/django-storages/
__ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html
Upgrading from ``django-staticfiles``
=====================================
``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to
``django.contrib.staticfiles``, you'll need to make a few changes:
* Application files should now live in a ``static`` directory in each app
(`django-staticfiles`_ used the name ``media``, which was slightly
confusing).
* The management commands ``build_static`` and ``resolve_static`` are now
called :djadmin:`collectstatic` and :djadmin:`findstatic`.
* The settings ``STATICFILES_PREPEND_LABEL_APPS``,
``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
removed.
* The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the
new :setting:`STATICFILES_FINDERS`.
* The default for :setting:`STATICFILES_STORAGE` was renamed from
``staticfiles.storage.StaticFileStorage`` to
``staticfiles.storage.StaticFilesStorage``
* If using :ref:`runserver<staticfiles-runserver>` for local development
(and the :setting:`DEBUG` setting is ``True``), you no longer need to add
anything to your URLconf for serving static files in development.
Learn more Learn more
========== ==========
This document has covered the basics and some common usage patterns. For This document has covered the basics and some common usage patterns. For
complete details on all the settings, commands, template tags, and other pieces complete details on all the settings, commands, template tags, and other pieces
include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference included in :mod:`django.contrib.staticfiles`, see :doc:`the staticfiles
</ref/contrib/staticfiles>`. reference </ref/contrib/staticfiles>`.

3
docs/index.txt
View File

@ -99,6 +99,7 @@ to know about views via the links below:
:doc:`Decorators <topics/http/decorators>` :doc:`Decorators <topics/http/decorators>`
* **Reference:** * **Reference:**
:doc:`Built-in Views <ref/views>` |
:doc:`Request/response objects <ref/request-response>` | :doc:`Request/response objects <ref/request-response>` |
:doc:`TemplateResponse objects <ref/template-response>` :doc:`TemplateResponse objects <ref/template-response>`
@ -191,7 +192,7 @@ testing of Django applications:
:doc:`Overview <howto/deployment/index>` | :doc:`Overview <howto/deployment/index>` |
:doc:`WSGI servers <howto/deployment/wsgi/index>` | :doc:`WSGI servers <howto/deployment/wsgi/index>` |
:doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` | :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
:doc:`Handling static files <howto/static-files>` | :doc:`Deploying static files <howto/static-files/deployment>` |
:doc:`Tracking code errors by email <howto/error-reporting>` :doc:`Tracking code errors by email <howto/error-reporting>`
The admin The admin

2
docs/intro/overview.txt
View File

@ -272,7 +272,7 @@ following blocks." In short, that lets you dramatically cut down on redundancy
in templates: each template has to define only what's unique to that template. in templates: each template has to define only what's unique to that template.
Here's what the "base.html" template, including the use of :doc:`static files Here's what the "base.html" template, including the use of :doc:`static files
</howto/static-files>`, might look like: </howto/static-files/index>`, might look like:
.. code-block:: html+django .. code-block:: html+django

2
docs/intro/tutorial06.txt
View File

@ -108,7 +108,7 @@ loaded in the bottom right of the screen.
These are the **basics**. For more details on settings and other bits included These are the **basics**. For more details on settings and other bits included
with the framework see with the framework see
:doc:`the static files howto </howto/static-files>` and the :doc:`the static files howto </howto/static-files/index>` and the
:doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying :doc:`the staticfiles reference </ref/contrib/staticfiles>`. :doc:`Deploying
static files </howto/static-files/deployment>` discusses how to use static static files </howto/static-files/deployment>` discusses how to use static
files on a real server. files on a real server.

29
docs/ref/contrib/staticfiles.txt
View File

@ -12,7 +12,8 @@ can easily be served in production.
.. seealso:: .. seealso::
For an introduction to the static files app and some usage examples, see For an introduction to the static files app and some usage examples, see
:doc:`/howto/static-files`. :doc:`/howto/static-files/index`. For guidelines on deploying static files,
see :doc:`/howto/static-files/deployment`.
.. _staticfiles-settings: .. _staticfiles-settings:
@ -326,9 +327,18 @@ files:
Static file development view Static file development view
---------------------------- ----------------------------
.. currentmodule:: django.contrib.staticfiles
The static files tools are mostly designed to help with getting static files
successfully deployed into production. This usually means a separate,
dedicated static file server, which is a lot of overhead to mess with when
developing locally. Thus, the ``staticfiles`` app ships with a
**quick and dirty helper view** that you can use to serve files locally in
development.
.. highlight:: python .. highlight:: python
.. function:: django.contrib.staticfiles.views.serve(request, path) .. function:: views.serve(request, path)
This view function serves static files in development. This view function serves static files in development.
@ -355,9 +365,10 @@ primary URL configuration::
Note, the beginning of the pattern (``r'^static/'``) should be your Note, the beginning of the pattern (``r'^static/'``) should be your
:setting:`STATIC_URL` setting. :setting:`STATIC_URL` setting.
Since this is a bit finicky, there's also a helper function that'll do this for you: Since this is a bit finicky, there's also a helper function that'll do this for
you:
.. function:: django.contrib.staticfiles.urls.staticfiles_urlpatterns() .. function:: urls.staticfiles_urlpatterns()
This will return the proper URL pattern for serving static files to your This will return the proper URL pattern for serving static files to your
already defined pattern list. Use it like this:: already defined pattern list. Use it like this::
@ -368,8 +379,18 @@ already defined pattern list. Use it like this::
urlpatterns += staticfiles_urlpatterns() urlpatterns += staticfiles_urlpatterns()
This will inspect your :setting:`STATIC_URL` setting and wire up the view
to serve static files accordingly. Don't forget to set the
:setting:`STATICFILES_DIRS` setting appropriately to let
``django.contrib.staticfiles`` know where to look for files in addition to
files in app directories.
.. warning:: .. warning::
This helper function will only work if :setting:`DEBUG` is ``True`` This helper function will only work if :setting:`DEBUG` is ``True``
and your :setting:`STATIC_URL` setting is neither empty nor a full and your :setting:`STATIC_URL` setting is neither empty nor a full
URL such as ``http://static.example.com/``. URL such as ``http://static.example.com/``.
That's because this view is **grossly inefficient** and probably
**insecure**. This is only intended for local development, and should
**never be used in production**.

7
docs/ref/django-admin.txt
View File

@ -761,7 +761,8 @@ Serving static files with the development server
By default, the development server doesn't serve any static files for your site By default, the development server doesn't serve any static files for your site
(such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If (such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If
you want to configure Django to serve static media, read :doc:`/howto/static-files`. you want to configure Django to serve static media, read
:doc:`/howto/static-files/index`.
shell shell
----- -----
@ -1289,7 +1290,7 @@ collectstatic
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
This command is only available if the :doc:`static files application This command is only available if the :doc:`static files application
</howto/static-files>` (``django.contrib.staticfiles``) is installed. </howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
Please refer to its :djadmin:`description <collectstatic>` in the Please refer to its :djadmin:`description <collectstatic>` in the
:doc:`staticfiles </ref/contrib/staticfiles>` documentation. :doc:`staticfiles </ref/contrib/staticfiles>` documentation.
@ -1298,7 +1299,7 @@ findstatic
~~~~~~~~~~ ~~~~~~~~~~
This command is only available if the :doc:`static files application This command is only available if the :doc:`static files application
</howto/static-files>` (``django.contrib.staticfiles``) is installed. </howto/static-files/index>` (``django.contrib.staticfiles``) is installed.
Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles
</ref/contrib/staticfiles>` documentation. </ref/contrib/staticfiles>` documentation.

1
docs/ref/index.txt
View File

@ -25,3 +25,4 @@ API Reference
urls urls
utils utils
validators validators
views

2
docs/ref/settings.txt
View File

@ -2437,7 +2437,7 @@ Example: ``"/var/www/example.com/static/"``
If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
(default) the :djadmin:`collectstatic` management command will collect static (default) the :djadmin:`collectstatic` management command will collect static
files into this directory. See the howto on :doc:`managing static files into this directory. See the howto on :doc:`managing static
files</howto/static-files>` for more details about usage. files</howto/static-files/index>` for more details about usage.
.. warning:: .. warning::

6
docs/ref/templates/builtins.txt
View File

@ -2418,8 +2418,10 @@ slightly different call::
The :mod:`staticfiles<django.contrib.staticfiles>` contrib app also ships The :mod:`staticfiles<django.contrib.staticfiles>` contrib app also ships
with a :ttag:`static template tag<staticfiles-static>` which uses with a :ttag:`static template tag<staticfiles-static>` which uses
``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the ``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the
given path. Use that instead if you have an advanced use case such as given path (rather than simply using :func:`urlparse.urljoin` with the
:ref:`using a cloud service to serve static files<staticfiles-from-cdn>`:: :setting:`STATIC_URL` setting and the given path). Use that instead if you
have an advanced use case such as :ref:`using a cloud service to serve
static files<staticfiles-from-cdn>`::
{% load static from staticfiles %} {% load static from staticfiles %}
<img src="{% static "images/hi.jpg" %}" alt="Hi!" /> <img src="{% static "images/hi.jpg" %}" alt="Hi!" />

14
docs/ref/urls.txt
View File

@ -44,6 +44,20 @@ The ``optional_dictionary`` and ``optional_name`` parameters are described in
patterns you can construct. The only limit is that you can only create 254 patterns you can construct. The only limit is that you can only create 254
at a time (the 255th argument is the initial prefix argument). at a time (the 255th argument is the initial prefix argument).
static()
--------
.. function:: static.static(prefix, view='django.views.static.serve', **kwargs)
Helper function to return a URL pattern for serving files in debug mode::
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = patterns('',
# ... the rest of your URLconf goes here ...
) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
url() url()
----- -----

48
docs/ref/views.txt Normal file
View File

@ -0,0 +1,48 @@
==============
Built-in Views
==============
.. module:: django.views
:synopsis: Django's built-in views.
Several of Django's built-in views are documented in
:doc:`/topics/http/views` as well as elsewhere in the documentation.
Serving files in development
----------------------------
.. function:: static.serve(request, path, document_root, show_indexes=False)
There may be files other than your project's static assets that, for
convenience, you'd like to have Django serve for you in local development.
The :func:`~django.views.static.serve` view can be used to serve any directory
you give it. (This view is **not** hardened for production use and should be
used only as a development aid; you should serve these files in production
using a real front-end webserver).
The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.
``django.contrib.staticfiles`` is intended for static assets and has no
built-in handling for user-uploaded files, but you can have Django serve your
:setting:`MEDIA_ROOT` by appending something like this to your URLconf::
from django.conf import settings
# ... the rest of your URLconf goes here ...
if settings.DEBUG:
urlpatterns += patterns('',
url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {
'document_root': settings.MEDIA_ROOT,
}),
)
Note, the snippet assumes your :setting:`MEDIA_URL` has a value of
``'/media/'``. This will call the :func:`~django.views.static.serve` view,
passing in the path from the URLconf and the (required) ``document_root``
parameter.
Since it can become a bit cumbersome to define this URL pattern, Django
ships with a small URL helper function :func:`~django.conf.urls.static.static`
that takes as parameters the prefix such as :setting:`MEDIA_URL` and a dotted
path to a view, such as ``'django.views.static.serve'``. Any other function
parameter will be transparently passed to the view.

2
docs/releases/1.3-alpha-1.txt
View File

@ -72,7 +72,7 @@ at :setting:`STATIC_URL`.
See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
for more details or learn how to :doc:`manage static files for more details or learn how to :doc:`manage static files
</howto/static-files>`. </howto/static-files/index>`.
``unittest2`` support ``unittest2`` support
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~

2
docs/releases/1.3-beta-1.txt
View File

@ -37,7 +37,7 @@ Based on feedback from the community this release adds two new options to the
See the :doc:`staticfiles reference documentation </ref/contrib/staticfiles>` See the :doc:`staticfiles reference documentation </ref/contrib/staticfiles>`
for more details, or learn :doc:`how to manage static files for more details, or learn :doc:`how to manage static files
</howto/static-files>`. </howto/static-files/index>`.
Translation comments Translation comments
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~

2
docs/releases/1.3.txt
View File

@ -115,7 +115,7 @@ at :setting:`STATIC_URL`.
See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` See the :doc:`reference documentation of the app </ref/contrib/staticfiles>`
for more details or learn how to :doc:`manage static files for more details or learn how to :doc:`manage static files
</howto/static-files>`. </howto/static-files/index>`.
unittest2 support unittest2 support
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~

2
docs/releases/1.4-alpha-1.txt
View File

@ -578,7 +578,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your web server serves the files correctly. The development are configured and your web server serves the files correctly. The development
server continues to serve the admin files just like before. Don't hesitate to server continues to serve the admin files just like before. Don't hesitate to
consult the :doc:`static files howto </howto/static-files>` for further consult the :doc:`static files howto </howto/static-files/index>` for further
details. details.
In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.

2
docs/releases/1.4-beta-1.txt
View File

@ -646,7 +646,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your web server serves the files correctly. The development are configured and your web server serves the files correctly. The development
server continues to serve the admin files just like before. Don't hesitate to server continues to serve the admin files just like before. Don't hesitate to
consult the :doc:`static files howto </howto/static-files>` for further consult the :doc:`static files howto </howto/static-files/index>` for further
details. details.
In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.

2
docs/releases/1.4.txt
View File

@ -708,7 +708,7 @@ If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g.
``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT`
are configured and your Web server serves those files correctly. The are configured and your Web server serves those files correctly. The
development server continues to serve the admin files just like before. Read development server continues to serve the admin files just like before. Read
the :doc:`static files howto </howto/static-files>` for more details. the :doc:`static files howto </howto/static-files/index>` for more details.
If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g.
``http://media.example.com/admin/``), make sure to also set your ``http://media.example.com/admin/``), make sure to also set your

2
docs/topics/files.txt
View File

@ -5,7 +5,7 @@ Managing files
This document describes Django's file access APIs for files such as those This document describes Django's file access APIs for files such as those
uploaded by a user. The lower level APIs are general enough that you could use uploaded by a user. The lower level APIs are general enough that you could use
them for other purposes. If you want to handle "static files" (JS, CSS, etc), them for other purposes. If you want to handle "static files" (JS, CSS, etc),
see :doc:`/howto/static-files`. see :doc:`/howto/static-files/index`.
By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and
:setting:`MEDIA_URL` settings. The examples below assume that you're using these :setting:`MEDIA_URL` settings. The examples below assume that you're using these

2
docs/topics/testing/overview.txt
View File

@ -1102,7 +1102,7 @@ out the `full reference`_ for more details.
.. note:: .. note::
``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app ``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app
</howto/static-files>` so you'll need to have your project configured </howto/static-files/index>` so you'll need to have your project configured
accordingly (in particular by setting :setting:`STATIC_URL`). accordingly (in particular by setting :setting:`STATIC_URL`).
.. note:: .. note::