Debian Codegraph @

docs/howto/deployment/checklist.txt

raw
1 ====================
2 Deployment checklist
3 ====================
4
5 The internet is a hostile environment. Before deploying your Django project,
6 you should take some time to review your settings, with security, performance,
7 and operations in mind.
8
9 Django includes many :doc:`security features </topics/security>`. Some are
10 built-in and always enabled. Others are optional because they aren't always
11 appropriate, or because they're inconvenient for development. For example,
12 forcing HTTPS may not be suitable for all websites, and it's impractical for
13 local development.
14
15 Performance optimizations are another category of trade-offs with convenience.
16 For instance, caching is useful in production, less so for local development.
17 Error reporting needs are also widely different.
18
19 The following checklist includes settings that:
20
21 - must be set properly for Django to provide the expected level of security;
22 - are expected to be different in each environment;
23 - enable optional security features;
24 - enable performance optimizations;
25 - provide error reporting.
26
27 Many of these settings are sensitive and should be treated as confidential. If
28 you're releasing the source code for your project, a common practice is to
29 publish suitable settings for development, and to use a private settings
30 module for production.
31
32 Run ``manage.py check --deploy``
33 ================================
34
35 Some of the checks described below can be automated using the :option:`check
36 --deploy` option. Be sure to run it against your production settings file as
37 described in the option's documentation.
38
39 Switch away from ``manage.py runserver``
40 ========================================
41
42 The :djadmin:`runserver` command is not designed for a production setting. Be
43 sure to switch to a production-ready WSGI or ASGI server. For a few common
44 options, see :doc:`WSGI servers </howto/deployment/wsgi/index>` or
45 :doc:`ASGI servers </howto/deployment/asgi/index>`.
46
47 Critical settings
48 =================
49
50 :setting:`SECRET_KEY`
51 ---------------------
52
53 **The secret key must be a large random value and it must be kept secret.**
54
55 Make sure that the key used in production isn't used anywhere else and avoid
56 committing it to source control. This reduces the number of vectors from which
57 an attacker may acquire the key.
58
59 Instead of hardcoding the secret key in your settings module, consider loading
60 it from an environment variable::
61
62 import os
63
64 SECRET_KEY = os.environ["SECRET_KEY"]
65
66 or from a file::
67
68 with open("/etc/secret_key.txt") as f:
69 SECRET_KEY = f.read().strip()
70
71 If rotating secret keys, you may use :setting:`SECRET_KEY_FALLBACKS`::
72
73 import os
74
75 SECRET_KEY = os.environ["CURRENT_SECRET_KEY"]
76 SECRET_KEY_FALLBACKS = [
77 os.environ["OLD_SECRET_KEY"],
78 ]
79
80 Ensure that old secret keys are removed from ``SECRET_KEY_FALLBACKS`` in a
81 timely manner.
82
83 :setting:`DEBUG`
84 ----------------
85
86 **You must never enable debug in production.**
87
88 You're certainly developing your project with :setting:`DEBUG = True <DEBUG>`,
89 since this enables handy features like full tracebacks in your browser.
90
91 For a production environment, though, this is a really bad idea, because it
92 leaks lots of information about your project: excerpts of your source code,
93 local variables, settings, libraries used, etc.
94
95 Environment-specific settings
96 =============================
97
98 :setting:`ALLOWED_HOSTS`
99 ------------------------
100
101 When :setting:`DEBUG = False <DEBUG>`, Django doesn't work at all without a
102 suitable value for :setting:`ALLOWED_HOSTS`.
103
104 This setting is required to protect your site against some CSRF attacks. If
105 you use a wildcard, you must perform your own validation of the ``Host`` HTTP
106 header, or otherwise ensure that you aren't vulnerable to this category of
107 attacks.
108
109 You should also configure the web server that sits in front of Django to
110 validate the host. It should respond with a static error page or ignore
111 requests for incorrect hosts instead of forwarding the request to Django. This
112 way you'll avoid spurious errors in your Django logs (or emails if you have
113 error reporting configured that way). For example, on nginx you might set up a
114 default server to return "444 No Response" on an unrecognized host:
115
116 .. code-block:: nginx
117
118 server {
119 listen 80 default_server;
120 return 444;
121 }
122
123 :setting:`CACHES`
124 -----------------
125
126 If you're using a cache, connection parameters may be different in development
127 and in production. Django defaults to per-process :ref:`local-memory caching
128 <local-memory-caching>` which may not be desirable.
129
130 Cache servers often have weak authentication. Make sure they only accept
131 connections from your application servers.
132
133 :setting:`DATABASES`
134 --------------------
135
136 Database connection parameters are probably different in development and in
137 production.
138
139 Database passwords are very sensitive. You should protect them exactly like
140 :setting:`SECRET_KEY`.
141
142 For maximum security, make sure database servers only accept connections from
143 your application servers.
144
145 If you haven't set up backups for your database, do it right now!
146
147 :setting:`EMAIL_BACKEND` and related settings
148 ---------------------------------------------
149
150 If your site sends emails, these values need to be set correctly.
151
152 By default, Django sends email from webmaster@localhost and root@localhost.
153 However, some mail providers reject email from these addresses. To use
154 different sender addresses, modify the :setting:`DEFAULT_FROM_EMAIL` and
155 :setting:`SERVER_EMAIL` settings.
156
157 :setting:`STATIC_ROOT` and :setting:`STATIC_URL`
158 ------------------------------------------------
159
160 Static files are automatically served by the development server. In
161 production, you must define a :setting:`STATIC_ROOT` directory where
162 :djadmin:`collectstatic` will copy them.
163
164 See :doc:`/howto/static-files/index` for more information.
165
166 :setting:`MEDIA_ROOT` and :setting:`MEDIA_URL`
167 ----------------------------------------------
168
169 Media files are uploaded by your users. They're untrusted! Make sure your web
170 server never attempts to interpret them. For instance, if a user uploads a
171 ``.php`` file, the web server shouldn't execute it.
172
173 Now is a good time to check your backup strategy for these files.
174
175 HTTPS
176 =====
177
178 Any website which allows users to log in should enforce site-wide HTTPS to
179 avoid transmitting access tokens in clear. In Django, access tokens include
180 the login/password, the session cookie, and password reset tokens. (You can't
181 do much to protect password reset tokens if you're sending them by email.)
182
183 Protecting sensitive areas such as the user account or the admin isn't
184 sufficient, because the same session cookie is used for HTTP and HTTPS. Your
185 web server must redirect all HTTP traffic to HTTPS, and only transmit HTTPS
186 requests to Django.
187
188 Once you've set up HTTPS, enable the following settings.
189
190 :setting:`CSRF_COOKIE_SECURE`
191 -----------------------------
192
193 Set this to ``True`` to avoid transmitting the CSRF cookie over HTTP
194 accidentally.
195
196 :setting:`SESSION_COOKIE_SECURE`
197 --------------------------------
198
199 Set this to ``True`` to avoid transmitting the session cookie over HTTP
200 accidentally.
201
202 Performance optimizations
203 =========================
204
205 Setting :setting:`DEBUG = False <DEBUG>` disables several features that are
206 only useful in development. In addition, you can tune the following settings.
207
208 Sessions
209 --------
210
211 Consider using :ref:`cached sessions <cached-sessions-backend>` to improve
212 performance.
213
214 If using database-backed sessions, regularly :ref:`clear old sessions
215 <clearing-the-session-store>` to avoid storing unnecessary data.
216
217 :setting:`CONN_MAX_AGE`
218 -----------------------
219
220 Enabling :ref:`persistent database connections
221 <persistent-database-connections>` can result in a nice speed-up when
222 connecting to the database accounts for a significant part of the request
223 processing time.
224
225 This helps a lot on virtualized hosts with limited network performance.
226
227 :setting:`TEMPLATES`
228 --------------------
229
230 Enabling the cached template loader often improves performance drastically, as
231 it avoids compiling each template every time it needs to be rendered. When
232 :setting:`DEBUG = False <DEBUG>`, the cached template loader is enabled
233 automatically. See :class:`django.template.loaders.cached.Loader` for more
234 information.
235
236 Error reporting
237 ===============
238
239 By the time you push your code to production, it's hopefully robust, but you
240 can't rule out unexpected errors. Thankfully, Django can capture errors and
241 notify you accordingly.
242
243 :setting:`LOGGING`
244 ------------------
245
246 Review your logging configuration before putting your website in production,
247 and check that it works as expected as soon as you have received some traffic.
248
249 See :doc:`/topics/logging` for details on logging.
250
251 :setting:`ADMINS` and :setting:`MANAGERS`
252 -----------------------------------------
253
254 :setting:`ADMINS` will be notified of 500 errors by email.
255
256 :setting:`MANAGERS` will be notified of 404 errors.
257 :setting:`IGNORABLE_404_URLS` can help filter out spurious reports.
258
259 See :doc:`/howto/error-reporting` for details on error reporting by email.
260
261 .. admonition:: Error reporting by email doesn't scale very well
262
263 Consider using an error monitoring system such as Sentry_ before your
264 inbox is flooded by reports. Sentry can also aggregate logs.
265
266 .. _Sentry: https://docs.sentry.io/
267
268 Customize the default error views
269 ---------------------------------
270
271 Django includes default views and templates for several HTTP error codes. You
272 may want to override the default templates by creating the following templates
273 in your root template directory: ``404.html``, ``500.html``, ``403.html``, and
274 ``400.html``. The :ref:`default error views <error-views>` that use these
275 templates should suffice for 99% of web applications, but you can
276 :ref:`customize them <customizing-error-views>` as well.