Browse files

Fixed #19897 - Updated static files howto.

Thanks Jan Murre, Reinout van Rees and Wim Feijen,
plus Remco Wendt for reviewing.
  • Loading branch information...
1 parent c32fc79 commit 6c730da1f6d34f5c38fa1d990d368286e016546c @timgraham timgraham committed Mar 7, 2013
@@ -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`
@@ -21,7 +21,8 @@ you quickly accomplish common tasks.
- static-files
+ static-files/index
+ static-files/deployment
.. seealso::
@@ -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 <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
+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 = ['', '']
+ # Where your project code lives on the server
+ env.project_root = '/home/www/myproject'
+ def deploy_static():
+ with cd(env.project_root):
+ run('./ 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:
+.. _Nginx:
+.. _TUX:
+.. _Apache:
+.. _Cherokee:
+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/'
+ @roles('static')
+ def deploy_static():
+ local('./ 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
+```` you could use it with::
+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
+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>`.
Oops, something went wrong.

0 comments on commit 6c730da

Please sign in to comment.