===================== Managing static files ===================== .. currentmodule:: django.contrib.staticfiles .. 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, 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. 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. .. 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`` ==================================== Here's the basic usage in a nutshell: 1. Put your media 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 :setting:`STATICFILES_DIRS` and :setting:`STATICFILES_FINDERS` settings for details on where you can put media. 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`. Next, you'll need to edit :setting:`STATICFILES_ROOT` to point to where you'd like your static media stored. For example:: STATICFILES_ROOT = "/home/jacob/projects/mysite.com/static_media" You may also want to set the :setting:`STATICFILES_URL` setting at this time, though the default value (of ``/static/``) is perfect for local development. 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 ` 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:`STATICFILES_ROOT`. 4. Deploy that media. If you're using the built-in development server, you can quickly serve static media locally by adding:: from django.contrib.staticfiles.urls import staticfiles_urlpatterns urlpatterns += staticfiles_urlpatterns() to the bottom of your URLconf. See :ref:`staticfiles-development` for details. When it comes time to deploy to production, :ref:`staticfiles-production` covers some common deployment strategies for static files. However you choose to deploy those files, you'll probably need to refer to them in your templates. The easiest method is to use the included context processor which will allow template code like: .. code-block:: html+django 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. A far better way is to use the value of the :setting:`STATICFILES_URL` setting directly in your templates. This means that a switch of media 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. With a context processor ------------------------ The included context processor is the easy way. Simply make sure ``'django.contrib.staticfiles.context_processors.staticfiles'`` 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.contrib.auth.context_processors.auth', 'django.contrib.messages.context_processors.messages', 'django.contrib.staticfiles.context_processors.staticfiles', ) Once that's done, you can refer to :setting:`STATICFILES_URL` in your templates: .. code-block:: html+django There's also a second form you can use to avoid extra processing if you need the value multiple times: .. code-block:: html+django {% load staticfiles %} {% get_staticfiles_prefix as STATIC_PREFIX %} .. _staticfiles-development: 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 media locally in development. To enable this view, 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:`STATICFILES_URL` and :setting:`STATICFILES_ROOT` settings and wire up the view to serve static media accordingly. Remember to run :djadmin:`collectstatic` when your media changes; the view only serves static files that have been collected. .. 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**. For a few more details, including an alternate method of enabling this view, see :ref:`staticfiles-development-view`. .. _staticfiles-production: Serving static files in production ================================== The basic outline of putting static files into production a simple: un the :djadmin:`collectstatic` command when static media changes, then arrange for the collected media directory (:setting:`STATICFILES_ROOT`) to be moved to the media 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 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: * Push your code up to the deployment server. * On the server, run :djadmin:`collectmedia` to move all the media into :setting:`STATICFILES_ROOT`. * Point your web server at :setting:`STATICFILES_ROOT`. For example, here's of :ref:`how to do this under 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`__. __ 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 of a fabfile is fairly streightforward 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:: 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') Serving static files from a dedicated media 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: * 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 media 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:`STATICFILES_ROOT` up to the media 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. 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/media.example.com' @roles('media') def deploy_static(): local('./manage.py collectstatic') project.rysnc_project( remote_dir = env.remote_static_root, local_dir = env.local_static_root, delete = True ) .. _staticfiles-from-cdn: Serving static media 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). 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. 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 = 'storages.backends.s3.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. 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.welldev.org/django-storages/wiki/S3Storage 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: * 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 ``STATIC_URL`` and ``STATIC_ROOT`` were renamed to :setting:`STATICFILES_URL` and :setting:`STATICFILES_ROOT`. * 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`` 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 statcfiles reference `.