Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Reworded parts of the staticfiles documentation after receiving vario…

…us user feedback. Thanks, all!

git-svn-id: http://code.djangoproject.com/svn/django/trunk@15369 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 8fe42053bcec02769ae76b238d43086eb021ca89 1 parent e3d322e
@jezdez jezdez authored
View
203 docs/howto/static-files.txt
@@ -7,18 +7,19 @@ Managing static files
.. versionadded:: 1.3
Django developers mostly concern themselves with the dynamic parts of web
-applications -- the views and templates that render anew for each request. But
-web applications have other parts: the static media files (images, CSS,
+applications -- the views and templates that render new for each request. But
+web applications have other parts: the static files (images, CSS,
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 media
-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.
+For small projects, this isn't a big deal, because you can just keep the
+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 media from each
-of your applications (and any other places you specify) into a single location
-that can easily be served in production.
+That's what ``django.contrib.staticfiles`` is for: it collects 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::
@@ -37,51 +38,56 @@ Using ``django.contrib.staticfiles``
Here's the basic usage in a nutshell:
- 1. Put your media somewhere that staticfiles will find it.
+ 1. Put your static files somewhere that staticfiles will find it.
- Most of the time this place will be in a ``static`` directory within your
- application, but it could also be a specific directory you've put into
- your settings file. See the the documentation for the
+ Most of the time this place will be in a ``static`` directory within
+ your application, but it could also be a specific directory you've put
+ into your settings file. See the the documentation for the
:setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings
- for details on where you can put media.
+ for details on where you can put static files.
2. Add some ``staticfiles``-related settings to your settings file.
- First, you'll need to make sure that ``django.contrib.staticfiles`` is in
- your :setting:`INSTALLED_APPS`.
+ First, you'll need to make sure that ``django.contrib.staticfiles``
+ is in your :setting:`INSTALLED_APPS`.
- Next, you'll need to edit :setting:`STATIC_ROOT` to point to where
- you'd like your static media stored. For example::
+ Next, you'll need to set the :setting:`STATIC_URL` setting, though
+ the default value (of ``'/static/'``) is perfect for local development.
+ See also the :setting:`STATIC_URL` documentation.
- STATIC_ROOT = "/home/jacob/projects/mysite.com/static_media"
+ Then, edit the :setting:`STATIC_ROOT` setting to point to where
+ you'd like your static files collected at (when using the
+ :djadmin:`collectstatic`, see below). For example::
- You may also want to set the :setting:`STATIC_URL` setting at this
- time, though the default value (of ``/static/``) is perfect for local
- development.
+ STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"
- There are a number of other options available that let you control *how*
- media is stored, where ``staticfiles`` searches for files, and how files
- will be served; see :ref:`the staticfiles settings reference
- <staticfiles-settings>` for details.
+ There are a number of other options available that let you control
+ *how* static files are stored, where ``staticfiles`` searches for
+ files, and how files will be served; see :ref:`the staticfiles
+ settings reference <staticfiles-settings>` for details.
3. Run the :djadmin:`collectstatic` management command::
./manage.py collectstatic
This'll churn through your static file storage and move them into the
- directory given by :setting:`STATIC_ROOT`. (This is not necessary
- in local development if you are using :djadmin:`runserver` or adding
- ``staticfiles_urlpatterns`` to your URLconf; see below).
+ directory given by :setting:`STATIC_ROOT`.
- 4. Deploy that media.
+ .. note:: This is **not necessary in local development** if you are
+ using :djadmin:`staticfiles-runserver` or adding
+ ``staticfiles_urlpatterns`` to your URLconf; see below).
+
+ 4. Deploy those files.
If you're using the built-in development server (the
:djadmin:`runserver` management command) and have the :setting:`DEBUG`
setting set to ``True``, your staticfiles will automatically be served
- from :setting:`STATIC_URL` in development.
+ from :setting:`STATIC_URL` in development. You don't need to run
+ :djadmin:`collectstatic` in that case because ``staticfiles``'s
+ runserver command handle the serving of static files.
- If you are using some other server for local development, you can
- quickly serve static media locally by adding::
+ But, in case you are using some other server for local development,
+ you can quickly serve static files locally by adding::
from django.contrib.staticfiles.urls import staticfiles_urlpatterns
urlpatterns += staticfiles_urlpatterns()
@@ -113,11 +119,11 @@ the framework see :doc:`the staticfiles reference </ref/contrib/staticfiles>`.
: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 will probably want 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 media at all.
+ 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.
.. _staticfiles-in-templates:
@@ -129,16 +135,17 @@ You could, of course, simply hardcode the path to you assets in the templates:
.. code-block:: html
- <img src="http://media.example.com/static/myimage.jpg" />
+ <img src="http://static.example.com/static/myimage.jpg" />
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
-media. 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.
+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 media servers only
-requires changing that single value. Much better!
+directly in your templates. This means that a switch of static files servers
+only requires changing that single value. Much better!
``staticfiles`` inludes two built-in ways of getting at this setting in your
templates: a context processor and a template tag.
@@ -206,18 +213,19 @@ value multiple times:
Serving static files in development
===================================
-The static files tools are mostly designed to help with getting static media
-successfully deployed into production. This usually means a separate, dedicated
-media 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.
+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 :djadmin:`runserver`.
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::
+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
@@ -225,11 +233,11 @@ the file, and the last line at the bottom::
urlpatterns += staticfiles_urlpatterns()
-This will inspect your :setting:`STATIC_URL` and
-:setting:`STATIC_ROOT` settings and wire up the view to serve static media
-accordingly. Don't forget to set the :setting:`STATICFILES_DIRS` setting
-appropriately to let ``django.contrib.staticfiles`` know where to look for
-(additional) files.
+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::
@@ -239,8 +247,9 @@ appropriately to let ``django.contrib.staticfiles`` know where to look for
**insecure**. This is only intended for local development, and should
**never be used in production**.
- Additionally, your :setting:`STATIC_URL` setting can't be either empty
- or a full URL such as ``http://static.example.com/``.
+ 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, including an alternate method of enabling this view,
see :ref:`staticfiles-development-view`.
@@ -251,9 +260,9 @@ Serving static files in production
==================================
The basic outline of putting static files into production is simple: run the
-:djadmin:`collectstatic` command when static media changes, then arrange for the
-collected media directory (:setting:`STATIC_ROOT`) to be moved to the media
-server and served.
+: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.
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
@@ -262,30 +271,30 @@ 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
----------------------------------------------------------
-If you want to serve your media from the same server that's already serving your
-app, the basic outline gets modified to look something like:
+If you want to serve your static files from the same server that's already
+serving your site, the basic outline gets modified to look something like:
* Push your code up to the deployment server.
- * On the server, run :djadmin:`collectstatic` to move all the media into
- :setting:`STATIC_ROOT`.
+ * On the server, run :djadmin:`collectstatic` to move all the static files
+ 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-media-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`__.
+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 media deployment options. The syntax
+(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 media to a couple of web servers might look something
-like::
+So, a fabfile to deploy static files to a couple of web servers might look
+something like::
from fabric.api import *
@@ -299,12 +308,12 @@ like::
with cd(env.project_root):
run('./manage.py collectstatic -v0 --noinput')
-Serving static files from a dedicated media server
---------------------------------------------------
+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 media. This server often runs a different type of
-web server -- faster but less full-featured. Some good choices are:
+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_
@@ -318,17 +327,17 @@ web server -- faster but less full-featured. Some good choices are:
.. _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.
+Configuring these servers is out of scope of this document; check each
+server's respective documentation for instructions.
-Since your media server won't be running Django, you'll need to modify the
-deployment strategy to look something like:
+Since your static file server won't be running Django, you'll need to modify
+the deployment strategy to look something like:
- * When your media changes, run :djadmin:`collectstatic` locally.
- * Push your local :setting:`STATIC_ROOT` up to the media server
+ * 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 media that have changed.
+ bits of static files that have changed.
Here's how this might look in a fabfile::
@@ -339,9 +348,9 @@ Here's how this might look in a fabfile::
env.local_static_root = '/tmp/static'
# Where the static files should go remotely
- env.remote_static_root = '/home/www/media.example.com'
+ env.remote_static_root = '/home/www/static.example.com'
- @roles('media')
+ @roles('static')
def deploy_static():
local('./manage.py collectstatic')
project.rysnc_project(
@@ -352,17 +361,17 @@ Here's how this might look in a fabfile::
.. _staticfiles-from-cdn:
-Serving static media from a cloud service or CDN
+Serving static files from a cloud service or CDN
------------------------------------------------
-Another common tactic is to serve media from a cloud storage provider like
-Amazon's S3__ and/or a CDN (content delivery network). This lets you ignore the
-problems of serving media, and can often make for faster-loading webpages
-(especially when using a 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 media to the server
-you'd need to transfer the media to the storage provider or CDN.
+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
@@ -376,9 +385,9 @@ For example, if you've written an S3 storage backend in
STATICFILES_STORAGE = 'myproject.storage.S3Storage'
Once that's done, all you have to do is run :djadmin:`collectstatic` and your
-media would be pushed through your storage package up to S3. If you later needed
-to swich to a different storage provider, it could be as simple as changing your
-:setting:`STATICFILES_STORAGE` setting.
+static files would be pushed through your storage package up to S3. If you
+later needed to swich 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`.
@@ -396,8 +405,8 @@ Upgrading from ``django-staticfiles``
=====================================
``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If
-you're upgrading from `django-staticfiles`_ to ``django.contrib.staticfiles``,
-you'll need to make a few changes:
+you're upgrading from `django-staticfiles`_ < ``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
@@ -410,8 +419,8 @@ you'll need to make a few changes:
``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were
removed.
- * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the new
- :setting:`STATICFILES_FINDERS`.
+ * 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
View
23 docs/ref/contrib/staticfiles.txt
@@ -50,20 +50,29 @@ your additional files directory(ies) e.g.::
"/opt/webfiles/common",
)
+Prefixes (optional)
+"""""""""""""""""""
+
In case you want to refer to files in one of the locations with an additional
namespace, you can **optionally** provide a prefix as ``(prefix, path)``
tuples, e.g.::
STATICFILES_DIRS = (
- "/home/polls.com/polls/static",
+ # ...
("downloads", "/opt/webfiles/stats"),
)
-With this configuration, the :djadmin:`collectstatic` management command would
-for example collect the stats files in a ``'downloads'`` directory. So
-assuming you have :setting:`STATIC_URL` set ``'/static/'``, this would
-allow you to refer to the file ``'/opt/webfiles/stats/polls_20101022.tar.gz'``
-with ``'/static/downloads/polls_20101022.tar.gz'`` in your templates.
+Example:
+
+Assuming you have :setting:`STATIC_URL` set ``'/static/'``, the
+:djadmin:`collectstatic` management command would collect the "stats" files
+in a ``'downloads'`` subdirectory of :setting:`STATIC_ROOT`.
+
+This would allow you to refer to the local file
+``'/opt/webfiles/stats/polls_20101022.tar.gz'`` with
+``'/static/downloads/polls_20101022.tar.gz'`` in your templates, e.g.::
+
+ <a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">
.. setting:: STATICFILES_STORAGE
@@ -183,6 +192,8 @@ collected for a given path.
runserver
---------
+.. django-admin:: staticfiles-runserver
+
Overrides the core :djadmin:`runserver` command if the ``staticfiles`` app
is :setting:`installed<INSTALLED_APPS>` and adds automatic serving of static
files and the following new options.
View
29 docs/ref/settings.txt
@@ -1628,24 +1628,25 @@ STATIC_ROOT
Default: ``''`` (Empty string)
-The absolute path to the directory that contains static content.
+The absolute path to the directory that contains static files.
Example: ``"/home/example.com/static/"``
-When using the :djadmin:`collectstatic` management command of the optional,
-:doc:`staticfiles</ref/contrib/staticfiles>` app this will be used to collect
-static files into and served from :setting:`STATIC_URL`.
+If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled
+(default) this will be used as the directory which the
+:djadmin:`collectstatic` management command collects static files in. See
+the howto on :doc:`managing static files</howto/static-files>` for more
+details about usage.
-In that case this is a **required setting**, unless you've overridden
-:setting:`STATICFILES_STORAGE` and are using a custom storage backend.
+.. warning:: This is not a place to store your static files permanently;
+ you should do that in directories that will be found by
+ :doc:`staticfiles</ref/contrib/staticfiles>`'s
+ :setting:`finders<STATICFILES_FINDERS>`, which by default, are
+ ``'static'`` app sub directories and any directories you include in
+ the :setting:`STATICFILES_DIRS`).
-This is not a place to store your static files permanently under version
-control; you should do that in directories that will be found by your
-:setting:`STATICFILES_FINDERS` (by default, per-app ``static/`` subdirectories,
-and any directories you include in :setting:`STATICFILES_DIRS`). Files from
-those locations will be collected into :setting:`STATIC_ROOT`.
-
-See :doc:`/ref/contrib/staticfiles` and :setting:`STATIC_URL`.
+See :doc:`staticfiles reference</ref/contrib/staticfiles>` and
+:setting:`STATIC_URL`.
.. setting:: STATIC_URL
@@ -1654,7 +1655,7 @@ STATIC_URL
Default: ``None``
-URL that handles the files served from :setting:`STATIC_ROOT`.
+URL to use when referring to static files located in :setting:`STATIC_ROOT`.
Example: ``"/site_media/static/"`` or ``"http://static.example.com/"``
View
2  docs/topics/forms/media.txt
@@ -204,7 +204,7 @@ the appropriate prefix.
As part of the introduction of the
:doc:`staticfiles app </ref/contrib/staticfiles>` two new settings were added
-to refer to "static content" (images, CSS, Javascript, etc.) that are needed
+to refer to "static files" (images, CSS, Javascript, etc.) that are needed
to render a complete web page: :setting:`STATIC_URL` and :setting:`STATIC_ROOT`.
To find the appropriate prefix to use, Django will check if the
Please sign in to comment.
Something went wrong with that request. Please try again.