7
For an introduction to the use of :mod:`django.contrib.staticfiles`, see
8
:doc:`/howto/static-files/index`.
10
.. _staticfiles-production:
12
Serving static files in production
13
==================================
15
The basic outline of putting static files into production is simple: run the
16
:djadmin:`collectstatic` command when static files change, then arrange for
17
the collected static files directory (:setting:`STATIC_ROOT`) to be moved to
18
the static file server and served. Depending on :setting:`STATICFILES_STORAGE`,
19
files may need to be moved to a new location manually or the :func:`post_process
20
<django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method
21
of the ``Storage`` class might take care of that.
23
Of course, as with all deployment tasks, the devil's in the details. Every
24
production setup will be a bit different, so you'll need to adapt the basic
25
outline to fit your needs. Below are a few common patterns that might help.
27
Serving the site and your static files from the same server
28
-----------------------------------------------------------
30
If you want to serve your static files from the same server that's already
31
serving your site, the process may look something like:
33
* Push your code up to the deployment server.
34
* On the server, run :djadmin:`collectstatic` to copy all the static files
35
into :setting:`STATIC_ROOT`.
36
* Configure your web server to serve the files in :setting:`STATIC_ROOT`
37
under the URL :setting:`STATIC_URL`. For example, here's
38
:ref:`how to do this with Apache and mod_wsgi <serving-files>`.
40
You'll probably want to automate this process, especially if you've got
41
multiple web servers. There's any number of ways to do this automation, but
42
one option that many Django developers enjoy is `Fabric
43
<http://fabfile.org/>`_.
45
Below, and in the following sections, we'll show off a few example fabfiles
46
(i.e. Fabric scripts) that automate these file deployment options. The syntax
47
of a fabfile is fairly straightforward but won't be covered here; consult
48
`Fabric's documentation <http://docs.fabfile.org/>`_, for a complete
49
explanation of the syntax.
51
So, a fabfile to deploy static files to a couple of web servers might look
54
from fabric.api import *
56
# Hosts to deploy onto
57
env.hosts = ['www1.example.com', 'www2.example.com']
59
# Where your project code lives on the server
60
env.project_root = '/home/www/myproject'
63
with cd(env.project_root):
64
run('./manage.py collectstatic -v0 --noinput')
66
Serving static files from a dedicated server
67
--------------------------------------------
69
Most larger Django sites use a separate Web server -- i.e., one that's not also
70
running Django -- for serving static files. This server often runs a different
71
type of web server -- faster but less full-featured. Some common choices are:
77
* A stripped-down version of Apache_
79
.. _lighttpd: http://www.lighttpd.net/
80
.. _Nginx: http://wiki.nginx.org/Main
81
.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
82
.. _Apache: http://httpd.apache.org/
83
.. _Cherokee: http://www.cherokee-project.com/
85
Configuring these servers is out of scope of this document; check each
86
server's respective documentation for instructions.
88
Since your static file server won't be running Django, you'll need to modify
89
the deployment strategy to look something like:
91
* When your static files change, run :djadmin:`collectstatic` locally.
93
* Push your local :setting:`STATIC_ROOT` up to the static file server into the
94
directory that's being served. `rsync <https://rsync.samba.org/>`_ is a
95
common choice for this step since it only needs to transfer the bits of
96
static files that have changed.
98
Here's how this might look in a fabfile::
100
from fabric.api import *
101
from fabric.contrib import project
103
# Where the static files get collected locally. Your STATIC_ROOT setting.
104
env.local_static_root = '/tmp/static'
106
# Where the static files should go remotely
107
env.remote_static_root = '/home/www/static.example.com'
111
local('./manage.py collectstatic')
112
project.rsync_project(
113
remote_dir = env.remote_static_root,
114
local_dir = env.local_static_root,
118
.. _staticfiles-from-cdn:
120
Serving static files from a cloud service or CDN
121
------------------------------------------------
123
Another common tactic is to serve static files from a cloud storage provider
124
like Amazon's S3 and/or a CDN (content delivery network). This lets you
125
ignore the problems of serving static files and can often make for
126
faster-loading webpages (especially when using a CDN).
128
When using these services, the basic workflow would look a bit like the above,
129
except that instead of using ``rsync`` to transfer your static files to the
130
server you'd need to transfer the static files to the storage provider or CDN.
132
There's any number of ways you might do this, but if the provider has an API a
133
:doc:`custom file storage backend </howto/custom-file-storage>` will make the
134
process incredibly simple. If you've written or are using a 3rd party custom
135
storage backend, you can tell :djadmin:`collectstatic` to use it by setting
136
:setting:`STATICFILES_STORAGE` to the storage engine.
138
For example, if you've written an S3 storage backend in
139
``myproject.storage.S3Storage`` you could use it with::
141
STATICFILES_STORAGE = 'myproject.storage.S3Storage'
143
Once that's done, all you have to do is run :djadmin:`collectstatic` and your
144
static files would be pushed through your storage package up to S3. If you
145
later needed to switch to a different storage provider, it could be as simple
146
as changing your :setting:`STATICFILES_STORAGE` setting.
148
For details on how you'd write one of these backends, see
149
:doc:`/howto/custom-file-storage`. There are 3rd party apps available that
150
provide storage backends for many common file storage APIs. A good starting
151
point is the `overview at djangopackages.com
152
<https://www.djangopackages.com/grids/g/storage-backends/>`_.
157
For complete details on all the settings, commands, template tags, and other
158
pieces included in :mod:`django.contrib.staticfiles`, see :doc:`the
159
staticfiles reference </ref/contrib/staticfiles>`.
added
removed
docs/howto/static-files/deployment.txt
