| 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. |