From 912b5d2a6bc78067d6a7e130f10514c51bd1a58f Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Sun, 17 Mar 2013 18:21:05 +0100 Subject: [PATCH] Fixed #19697 -- Added a deployment checklist. --- .../project_template/project_name/settings.py | 5 +- docs/howto/deployment/checklist.txt | 200 ++++++++++++++++++ docs/howto/deployment/index.txt | 1 + docs/releases/1.6.txt | 3 + 4 files changed, 205 insertions(+), 4 deletions(-) create mode 100644 docs/howto/deployment/checklist.txt diff --git a/django/conf/project_template/project_name/settings.py b/django/conf/project_template/project_name/settings.py index d46f327922..972065467f 100644 --- a/django/conf/project_template/project_name/settings.py +++ b/django/conf/project_template/project_name/settings.py @@ -14,10 +14,9 @@ BASE_DIR = os.path.dirname(os.path.dirname(__file__)) # Quick-start development settings - unsuitable for production +# See https://docs.djangoproject.com/en/{{ docs_version }}/howto/deployment/checklist/ # SECURITY WARNING: keep the secret key used in production secret! -# Hardcoded values can leak through source control. Consider loading -# the secret key from an environment variable or a file instead. SECRET_KEY = '{{ secret_key }}' # SECURITY WARNING: don't run with debug turned on in production! @@ -25,8 +24,6 @@ DEBUG = True TEMPLATE_DEBUG = True -# Hosts/domain names that are valid for this site; required if DEBUG is False -# See https://docs.djangoproject.com/en/{{ docs_version }}/ref/settings/#allowed-hosts ALLOWED_HOSTS = [] diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt new file mode 100644 index 0000000000..53b257ae20 --- /dev/null +++ b/docs/howto/deployment/checklist.txt @@ -0,0 +1,200 @@ +==================== +Deployment checklist +==================== + +The Internet is a hostile environment. Before deploying your Django project, +you should take some time to review your settings, with security, performance, +and operations in mind. + +Django includes many :doc:`security features `. Some are +built-in and always enabled. Others are optional because they aren't always +appropriate, or because they're inconvenient for development. For example, +forcing HTTPS may not be suitable for all websites, and it's impractical for +local development. + +Performance optimizations are another category of trade-offs with convenience. +For instance, caching is useful in production, less so for local development. +Error reporting needs are also widely different. + +The following checklist includes settings that: + +- must be set properly for Django to provide the expected level of security; +- are expected to be different in each environment; +- enable optional security features; +- enable performance optimizations; +- provide error reporting. + +Many of these settings are sensitive and should be treated as confidential. If +you're releasing the source code for your project, a common practice is to +publish suitable settings for development, and to use a private settings +module for production. + +Critical settings +================= + +:setting:`SECRET_KEY` +--------------------- + +**The secret key must be a large random value and it must be kept secret.** + +Make sure that the key used in production isn't used anywhere else and avoid +committing it to source control. This reduces the number of vectors from which +an attacker may acquire the key. + +Instead of hardcoding the secret key in your settings module, consider loading +it from an environment variable:: + + import os + SECRET_KEY = os.environ['SECRET_KEY'] + +or from a file:: + + with open('/etc/secret_key.txt') as f: + SECRET_KEY = f.read().strip() + +:setting:`DEBUG` +---------------- + +**You must never enable debug in production.** + +You're certainly developing your project with :setting:`DEBUG = True `, +since this enables handy features like full tracebacks in your browser. + +For a production environment, though, this is a really bad idea, because it +leaks lots of information about your project: excerpts of your source code, +local variables, settings, libraries used, etc. + +Environment-specific settings +============================= + +:setting:`ALLOWED_HOSTS` +------------------------ + +When :setting:`DEBUG = False `, Django doesn't work at all without a +suitable value for :setting:`ALLOWED_HOSTS`. + +This setting is required to protect your site against some CSRF attacks. If +you use a wildcard, you must perform your own validation of the ``Host`` HTTP +header, or otherwise ensure that you aren't vulnerable to this category of +attacks. + +:setting:`CACHES` +----------------- + +If you're using a cache, connection parameters may be different in development +and in production. + +Cache servers often have weak authentication. Make sure they only accept +connections from your application servers. + +:setting:`DATABASES` +-------------------- + +Database connection parameters are probably different in development and in +production. + +For maximum security, make sure database servers only accept connections from +your application servers. + +If you haven't set up backups for your database, do it right now! + +:setting:`EMAIL_BACKEND` and related settings +--------------------------------------------- + +If your site sends emails, these values need to be set correctly. + +:setting:`STATIC_ROOT` and :setting:`STATIC_URL` +------------------------------------------------ + +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. + +:setting:`MEDIA_ROOT` and :setting:`MEDIA_URL` +---------------------------------------------- + +Media files are uploaded by your users. They're untrusted! Make sure your web +server never attempt to interpret them. For instance, if a user uploads a +``.php`` file , the web server shouldn't execute it. + +Now is a good time to check your backup strategy for these files. + +HTTPS +===== + +Any website which allows users to log in should enforce site-wide HTTPS to +avoid transmitting access tokens in clear. In Django, access tokens include +the login/password, the session cookie, and password reset tokens. (You can't +do much to protect password reset tokens if you're sending them by email.) + +Protecting sensitive areas such as the user account or the admin isn't +sufficient, because the same session cookie is used for HTTP and HTTPS. + +Once you've set up HTTPS, enable the following settings. + +:setting:`CSRF_COOKIE_SECURE` +----------------------------- + +Set this to ``True`` to avoid transmitting the CSRF cookie over HTTP +accidentally. + +:setting:`SESSION_COOKIE_SECURE` +-------------------------------- + +Set this to ``True`` to avoid transmitting the session cookie over HTTP +accidentally. + +Performance optimizations +========================= + +Setting :setting:`DEBUG = False ` disables several features that are +only useful in development. In addition, you can tune the following settings. + +:setting:`TEMPLATE_LOADERS` +--------------------------- + +Enabling the cached template loader often improves performance drastically, as +it avoids compiling each template every time it needs to be rendered. See the +:ref:`template loaders docs ` for more information. + +Error reporting +=============== + +By the time you push your code to production, it's hopefully robust, but you +can't rule out unexpected errors. Thankfully, Django can capture errors and +notify you accordingly. + +:setting:`LOGGING` +------------------ + +Review your logging configuration before putting your website in production, +and check that it works as expected as soon as you have received some traffic. + +See :doc:`/topics/logging` for details on logging. + +:setting:`ADMINS` and :setting:`MANAGERS` +----------------------------------------- + +:setting:`ADMINS` will be notified of 500 errors by email. + +:setting:`MANAGERS` will be notified of 404 errors. +:setting:`IGNORABLE_404_URLS` can help filter out spurious reports. + +See :doc:`/howto/error-reporting` for details on error reporting by email. + +.. admonition: Error reporting by email doesn't scale very well + + Consider using an error monitoring system such as Sentry_ before your + inbox is flooded by reports. Sentry can also aggregate logs. + + .. _Sentry: http://sentry.readthedocs.org/en/latest/ + +Miscellaneous +============= + +:setting:`ALLOWED_INCLUDE_ROOTS` +-------------------------------- + +This setting is required if you're using the :ttag:`ssi` template tag. diff --git a/docs/howto/deployment/index.txt b/docs/howto/deployment/index.txt index 8e27a031d5..ed4bcf3d4a 100644 --- a/docs/howto/deployment/index.txt +++ b/docs/howto/deployment/index.txt @@ -11,6 +11,7 @@ ways to easily deploy Django: wsgi/index fastcgi + checklist If you're new to deploying Django and/or Python, we'd recommend you try :doc:`mod_wsgi ` first. In most cases it'll be diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index abb4dff811..2ab44c0744 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -154,6 +154,9 @@ Minor features ``UPDATE`` - if not updated - ``INSERT`` instead of ``SELECT`` - if not found ``INSERT`` else ``UPDATE`` in case the model's primary key is set. +* The documentation contains a :doc:`deployment checklist + `. + Backwards incompatible changes in 1.6 =====================================