Debian Codegraph @

docs/howto/static-files/deployment.txt

raw
1 ==========================
2 How to deploy static files
3 ==========================
4
5 .. seealso::
6
7 For an introduction to the use of :mod:`django.contrib.staticfiles`, see
8 :doc:`/howto/static-files/index`.
9
10 .. _staticfiles-production:
11
12 Serving static files in production
13 ==================================
14
15 The basic outline of putting static files into production consists of two
16 steps: run the :djadmin:`collectstatic` command when static files change, then
17 arrange for the collected static files directory (:setting:`STATIC_ROOT`) to be
18 moved to the static file server and served. Depending on the ``staticfiles``
19 :setting:`STORAGES` alias, files may need to be moved to a new location
20 manually or the :func:`post_process
21 <django.contrib.staticfiles.storage.StaticFilesStorage.post_process>` method of
22 the ``Storage`` class might take care of that.
23
24 As with all deployment tasks, the devil's in the details. Every production
25 setup will be a bit different, so you'll need to adapt the basic outline to fit
26 your needs. Below are a few common patterns that might help.
27
28 Serving the site and your static files from the same server
29 -----------------------------------------------------------
30
31 If you want to serve your static files from the same server that's already
32 serving your site, the process may look something like:
33
34 * Push your code up to the deployment server.
35 * On the server, run :djadmin:`collectstatic` to copy all the static files
36 into :setting:`STATIC_ROOT`.
37 * Configure your web server to serve the files in :setting:`STATIC_ROOT`
38 under the URL :setting:`STATIC_URL`. For example, here's
39 :ref:`how to do this with Apache and mod_wsgi <serving-files>`.
40
41 You'll probably want to automate this process, especially if you've got
42 multiple web servers.
43
44 Serving static files from a dedicated server
45 --------------------------------------------
46
47 Most larger Django sites use a separate web server -- i.e., one that's not also
48 running Django -- for serving static files. This server often runs a different
49 type of web server -- faster but less full-featured. Some common choices are:
50
51 * Nginx_
52 * A stripped-down version of Apache_
53
54 .. _Nginx: https://nginx.org/en/
55 .. _Apache: https://httpd.apache.org/
56
57 Configuring these servers is out of scope of this document; check each
58 server's respective documentation for instructions.
59
60 Since your static file server won't be running Django, you'll need to modify
61 the deployment strategy to look something like:
62
63 * When your static files change, run :djadmin:`collectstatic` locally.
64
65 * Push your local :setting:`STATIC_ROOT` up to the static file server into the
66 directory that's being served. `rsync <https://rsync.samba.org/>`_ is a
67 common choice for this step since it only needs to transfer the bits of
68 static files that have changed.
69
70 .. _staticfiles-from-cdn:
71
72 Serving static files from a cloud service or CDN
73 ------------------------------------------------
74
75 Another common tactic is to serve static files from a cloud storage provider
76 like Amazon's S3 and/or a CDN (content delivery network). This lets you
77 ignore the problems of serving static files and can often make for
78 faster-loading web pages (especially when using a CDN).
79
80 When using these services, the basic workflow would look a bit like the above,
81 except that instead of using ``rsync`` to transfer your static files to the
82 server you'd need to transfer the static files to the storage provider or CDN.
83
84 There's any number of ways you might do this, but if the provider has an API,
85 you can use a :doc:`custom file storage backend </howto/custom-file-storage>`
86 to integrate the CDN with your Django project. If you've written or are using a
87 3rd party custom storage backend, you can tell :djadmin:`collectstatic` to use
88 it by setting ``staticfiles`` in :setting:`STORAGES`.
89
90 For example, if you've written an S3 storage backend in
91 ``myproject.storage.S3Storage`` you could use it with::
92
93 STORAGES = {
94 # ...
95 "staticfiles": {"BACKEND": "myproject.storage.S3Storage"}
96 }
97
98 Once that's done, all you have to do is run :djadmin:`collectstatic` and your
99 static files would be pushed through your storage package up to S3. If you
100 later needed to switch to a different storage provider, you may only have to
101 change ``staticfiles`` in the :setting:`STORAGES` setting.
102
103 For details on how you'd write one of these backends, see
104 :doc:`/howto/custom-file-storage`. There are 3rd party apps available that
105 provide storage backends for many common file storage APIs. A good starting
106 point is the `overview at djangopackages.org
107 <https://djangopackages.org/grids/g/storage-backends/>`_.
108
109 Learn more
110 ==========
111
112 For complete details on all the settings, commands, template tags, and other
113 pieces included in :mod:`django.contrib.staticfiles`, see :doc:`the
114 staticfiles reference </ref/contrib/staticfiles>`.