From 6c730da1f6d34f5c38fa1d990d368286e016546c Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Thu, 7 Mar 2013 14:15:39 -0500 Subject: [PATCH] Fixed #19897 - Updated static files howto. Thanks Jan Murre, Reinout van Rees and Wim Feijen, plus Remco Wendt for reviewing. --- docs/howto/deployment/checklist.txt | 2 +- docs/howto/index.txt | 3 +- docs/howto/static-files/deployment.txt | 159 ++++++++ docs/howto/static-files/index.txt | 527 ++++--------------------- docs/index.txt | 3 +- docs/intro/overview.txt | 2 +- docs/intro/tutorial06.txt | 2 +- docs/ref/contrib/staticfiles.txt | 29 +- docs/ref/django-admin.txt | 7 +- docs/ref/index.txt | 1 + docs/ref/settings.txt | 2 +- docs/ref/templates/builtins.txt | 6 +- docs/ref/urls.txt | 14 + docs/ref/views.txt | 48 +++ docs/releases/1.3-alpha-1.txt | 2 +- docs/releases/1.3-beta-1.txt | 2 +- docs/releases/1.3.txt | 2 +- docs/releases/1.4-alpha-1.txt | 2 +- docs/releases/1.4-beta-1.txt | 2 +- docs/releases/1.4.txt | 2 +- docs/topics/files.txt | 2 +- docs/topics/testing/overview.txt | 2 +- 22 files changed, 340 insertions(+), 481 deletions(-) create mode 100644 docs/howto/static-files/deployment.txt create mode 100644 docs/ref/views.txt diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt index 72c15b7807..b092048870 100644 --- a/docs/howto/deployment/checklist.txt +++ b/docs/howto/deployment/checklist.txt @@ -113,7 +113,7 @@ Static files are automatically served by the development server. In production, you must define a :setting:`STATIC_ROOT` directory where :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` ---------------------------------------------- diff --git a/docs/howto/index.txt b/docs/howto/index.txt index d39222be26..9d5b067a82 100644 --- a/docs/howto/index.txt +++ b/docs/howto/index.txt @@ -21,7 +21,8 @@ you quickly accomplish common tasks. legacy-databases outputting-csv outputting-pdf - static-files + static-files/index + static-files/deployment .. seealso:: diff --git a/docs/howto/static-files/deployment.txt b/docs/howto/static-files/deployment.txt new file mode 100644 index 0000000000..865a5c6b41 --- /dev/null +++ b/docs/howto/static-files/deployment.txt @@ -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 +` 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 `. + +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 +`_. + +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. + +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 `_ 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 ` 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 +`_. + +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 `. diff --git a/docs/howto/static-files/index.txt b/docs/howto/static-files/index.txt index 964b5fab61..2c98566e88 100644 --- a/docs/howto/static-files/index.txt +++ b/docs/howto/static-files/index.txt @@ -1,314 +1,79 @@ -===================== -Managing static files -===================== +=================================== +Managing static files (CSS, images) +=================================== -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 files (images, CSS, -Javascript, etc.) that are needed to render a complete web page. +Websites generally need to serve additional files such as images, JavaScript, +or CSS. In Django, we refer to these files as "static files". Django provides +:mod:`django.contrib.staticfiles` to help you manage them. -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. +This page describes how you can serve these static files. -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. +Configuring static files +======================== -.. note:: - - 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 +1. Make sure that ``django.contrib.staticfiles`` is included in your :setting:`INSTALLED_APPS`. - Your project will probably also have static assets that aren't tied to a - 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. +2. In your settings file, define :setting:`STATIC_URL`, for example:: - Additionally, see the documentation for the :setting:`STATICFILES_FINDERS` - setting for details on how ``staticfiles`` finds your files. + STATIC_URL = '/static/' -2. Make sure that ``django.contrib.staticfiles`` is included in your - :setting:`INSTALLED_APPS`. +3. In your templates, either hardcode the url like + ``/static/my_app/myexample.jpg`` or, preferably, use the + :ttag:`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`, if you are using - :ref:`runserver` or adding - :ref:`staticfiles_urlpatterns` to your - URLconf, you're done with the setup -- your static files will - automatically be served at the default (for - :djadmin:`newly created` 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: + .. _staticfiles-in-templates: .. code-block:: html+django - Hi! + {% load staticfiles %} + My image - See :ref:`staticfiles-in-templates` for more details, **including** an - alternate method using a template tag. +3. Store your static files in a folder called ``static`` in your app. For + 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 - files (in most cases, the default value of ``/static/`` is just fine). - -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 `. - -.. 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 - - 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', + STATICFILES_DIRS = ( + os.path.join(BASE_DIR, "static"), + '/var/www/static/', ) -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 - 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 -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 `, -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`. +Serving files uploaded by a user +================================ -Another option is the :ttag:`get_static_prefix` template tag that is part of -Django's core. +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 +strategies, see :doc:`/howto/static-files/deployment`. -With a template tag -------------------- - -The more powerful tool is the :ttag:`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 %} - 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 %} - - -.. note:: - - There is also a template tag named :ttag:`static` in Django's core set - of :ref:`built in template 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` - 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` 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.*)$', '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:: +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 from django.conf.urls.static import static @@ -319,190 +84,36 @@ development:: .. 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. ``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 -: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. +1. Set the :setting:`STATIC_ROOT` setting to the directory from which you'd + like to serve these files, for example:: -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. + STATIC_ROOT = "/var/www/example.com/static/" -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 -serving your site, the basic outline gets modified to look something like: + ./manage.py collectstatic -* Push your code up to the deployment server. -* On the server, run :djadmin:`collectstatic` to copy 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 `. + This will copy all files from your static folders into the + :setting:`STATIC_ROOT` directory. -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`__, 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 ` 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` 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. +3. Use a webserver of your choice to serve the + files. :doc:`/howto/static-files/deployment` covers some common deployment + strategies for static files. Learn more ========== This document has covered the basics and some common usage patterns. For 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 +reference `. diff --git a/docs/index.txt b/docs/index.txt index 8823888e7b..6473aa3168 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -99,6 +99,7 @@ to know about views via the links below: :doc:`Decorators ` * **Reference:** + :doc:`Built-in Views ` | :doc:`Request/response objects ` | :doc:`TemplateResponse objects ` @@ -191,7 +192,7 @@ testing of Django applications: :doc:`Overview ` | :doc:`WSGI servers ` | :doc:`FastCGI/SCGI/AJP ` | - :doc:`Handling static files ` | + :doc:`Deploying static files ` | :doc:`Tracking code errors by email ` The admin diff --git a/docs/intro/overview.txt b/docs/intro/overview.txt index 2081c960fc..8753817256 100644 --- a/docs/intro/overview.txt +++ b/docs/intro/overview.txt @@ -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. Here's what the "base.html" template, including the use of :doc:`static files -`, might look like: +`, might look like: .. code-block:: html+django diff --git a/docs/intro/tutorial06.txt b/docs/intro/tutorial06.txt index 28e1cabd96..6b3d0f35e2 100644 --- a/docs/intro/tutorial06.txt +++ b/docs/intro/tutorial06.txt @@ -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 with the framework see -:doc:`the static files howto ` and the +:doc:`the static files howto ` and the :doc:`the staticfiles reference `. :doc:`Deploying static files ` discusses how to use static files on a real server. diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index fa740f4e2c..b7de75baf1 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -12,7 +12,8 @@ can easily be served in production. .. seealso:: 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: @@ -326,9 +327,18 @@ files: 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 -.. function:: django.contrib.staticfiles.views.serve(request, path) +.. function:: views.serve(request, path) 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 :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 already defined pattern list. Use it like this:: @@ -368,8 +379,18 @@ already defined pattern list. Use it like this:: 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:: This helper function will only work if :setting:`DEBUG` is ``True`` and your :setting:`STATIC_URL` setting is neither empty nor a full 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**. diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 6277b22a30..c63c118e3d 100644 --- a/docs/ref/django-admin.txt +++ b/docs/ref/django-admin.txt @@ -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 (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 ----- @@ -1289,7 +1290,7 @@ collectstatic ~~~~~~~~~~~~~ This command is only available if the :doc:`static files application -` (``django.contrib.staticfiles``) is installed. +` (``django.contrib.staticfiles``) is installed. Please refer to its :djadmin:`description ` in the :doc:`staticfiles ` documentation. @@ -1298,7 +1299,7 @@ findstatic ~~~~~~~~~~ This command is only available if the :doc:`static files application -` (``django.contrib.staticfiles``) is installed. +` (``django.contrib.staticfiles``) is installed. Please refer to its :djadmin:`description ` in the :doc:`staticfiles ` documentation. diff --git a/docs/ref/index.txt b/docs/ref/index.txt index fc874a97eb..1d71b62f41 100644 --- a/docs/ref/index.txt +++ b/docs/ref/index.txt @@ -25,3 +25,4 @@ API Reference urls utils validators + views diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 2bfbbe0897..8d7ea6adfb 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -2437,7 +2437,7 @@ Example: ``"/var/www/example.com/static/"`` If the :doc:`staticfiles` contrib app is enabled (default) the :djadmin:`collectstatic` management command will collect static files into this directory. See the howto on :doc:`managing static -files` for more details about usage. +files` for more details about usage. .. warning:: diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index 149a557356..0e81df9190 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -2418,8 +2418,10 @@ slightly different call:: The :mod:`staticfiles` contrib app also ships with a :ttag:`static template tag` which uses ``staticfiles'`` :setting:`STATICFILES_STORAGE` to build the URL of the - given path. Use that instead if you have an advanced use case such as - :ref:`using a cloud service to serve static files`:: + given path (rather than simply using :func:`urlparse.urljoin` with the + :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`:: {% load static from staticfiles %} Hi! diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index 59fb97828c..e68edc8254 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -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 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() ----- diff --git a/docs/ref/views.txt b/docs/ref/views.txt new file mode 100644 index 0000000000..3753f83f07 --- /dev/null +++ b/docs/ref/views.txt @@ -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.*)$', '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. diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index 7c9f233921..c71736dc60 100644 --- a/docs/releases/1.3-alpha-1.txt +++ b/docs/releases/1.3-alpha-1.txt @@ -72,7 +72,7 @@ at :setting:`STATIC_URL`. See the :doc:`reference documentation of the app ` for more details or learn how to :doc:`manage static files -`. +`. ``unittest2`` support ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt index 69f8023eb3..aa7800bb94 100644 --- a/docs/releases/1.3-beta-1.txt +++ b/docs/releases/1.3-beta-1.txt @@ -37,7 +37,7 @@ Based on feedback from the community this release adds two new options to the See the :doc:`staticfiles reference documentation ` for more details, or learn :doc:`how to manage static files -`. +`. Translation comments ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index f689a3dffd..9a41f903f8 100644 --- a/docs/releases/1.3.txt +++ b/docs/releases/1.3.txt @@ -115,7 +115,7 @@ at :setting:`STATIC_URL`. See the :doc:`reference documentation of the app ` for more details or learn how to :doc:`manage static files -`. +`. unittest2 support ~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt index 92ec0b6483..cb218ac698 100644 --- a/docs/releases/1.4-alpha-1.txt +++ b/docs/releases/1.4-alpha-1.txt @@ -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` 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 -consult the :doc:`static files howto ` for further +consult the :doc:`static files howto ` for further details. In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt index d3f1bb807d..84b1bf6987 100644 --- a/docs/releases/1.4-beta-1.txt +++ b/docs/releases/1.4-beta-1.txt @@ -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` 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 -consult the :doc:`static files howto ` for further +consult the :doc:`static files howto ` for further details. In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 3025a37098..83a5f54fc7 100644 --- a/docs/releases/1.4.txt +++ b/docs/releases/1.4.txt @@ -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` are configured and your Web server serves those files correctly. The development server continues to serve the admin files just like before. Read -the :doc:`static files howto ` for more details. +the :doc:`static files howto ` for more details. If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. ``http://media.example.com/admin/``), make sure to also set your diff --git a/docs/topics/files.txt b/docs/topics/files.txt index c36094a599..c05f98ef7e 100644 --- a/docs/topics/files.txt +++ b/docs/topics/files.txt @@ -5,7 +5,7 @@ Managing files 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 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 :setting:`MEDIA_URL` settings. The examples below assume that you're using these diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt index 628a161554..259c39618b 100644 --- a/docs/topics/testing/overview.txt +++ b/docs/topics/testing/overview.txt @@ -1102,7 +1102,7 @@ out the `full reference`_ for more details. .. note:: ``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app - ` so you'll need to have your project configured + ` so you'll need to have your project configured accordingly (in particular by setting :setting:`STATIC_URL`). .. note::