<commit_before>Using WhiteNoise with Django
============================

.. note:: To use WhiteNoise with a non-Django application see the
   :doc:`generic WSGI documentation <base>`.

This guide walks you through setting up a Django project with WhiteNoise.
In most cases it shouldn't take more than a couple of lines of configuration.

I mention Heroku in a few place as that was the initial use case which prompted me
to create WhiteNoise, but there's nothing Heroku-specific about WhiteNoise and the
instructions below should apply whatever your hosting platform.

1. Make sure *staticfiles* is configured correctly
----------------------------------------------------

If you're familiar with Django you'll know what to do. If you're just getting started
with a new Django project then you'll need add the following to the bottom of your
``settings.py`` file:

.. code-block:: python

   STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

As part of deploying your application you'll need to run ``./manage.py collectstatic`` to
put all your static files into ``STATIC_ROOT``. (If you're running on Heroku then
this is done automatically for you.)

In Django 1.9 and older, make sure you're using the static_ template tag to
refer to your static files. For example:

.. code-block:: html

   {% load static from staticfiles %}
   <img src="{% static "images/hi.jpg" %}" alt="Hi!" />

In Django 1.10 and later, you can use ``{% load static %}`` instead.

.. _static: https://docs.djangoproject.com/en/1.9/ref/contrib/staticfiles/#std:templatetag-staticfiles-static


.. _django-middleware:

2. Enable WhiteNoise
--------------------

Edit your ``settings.py`` file and add WhiteNoise to the ``MIDDLEWARE_CLASSES``
list, above all other middleware apart from Django's `SecurityMiddleware
<https://docs.djangoproject.com/en/stable/ref/middleware/#module-django.middleware.security>`_:

.. code-block:: python

   MIDDLEWARE_CLASSES = [
     # 'django.middleware.security.SecurityMiddleware',
     'whitenoise.middleware.WhiteNoiseMiddleware',
     # ...
   ]

That's it -- WhiteNoise will now serve your static files. However, to get the
best performance you should proceed to step 3 below and enable compression and
caching.


3. Add compression and caching support
--------------------------------------

WhiteNoise comes with a storage backend which automatically takes care of
compressing your files and creating unique names for each version so they can
safely be cached forever. To use it, just add this to your ``settings.py``:

.. code-block:: python

   STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

If you need to compress files outside of the static files storage system you can
use the supplied :ref:`command line utility <cli-utility>`

.. note:: If you are having problems after switching to the WhiteNoise storage
   backend please see the :ref:`troubleshooting guide <storage-troubleshoot>`.

.. _brotli-compression:

Brotli compression
++++++++++++++++++<commit_msg>Clarify wording about SecurityMiddleware<commit_after>Using WhiteNoise with Django
============================

.. note:: To use WhiteNoise with a non-Django application see the
   :doc:`generic WSGI documentation <base>`.

This guide walks you through setting up a Django project with WhiteNoise.
In most cases it shouldn't take more than a couple of lines of configuration.

I mention Heroku in a few place as that was the initial use case which prompted me
to create WhiteNoise, but there's nothing Heroku-specific about WhiteNoise and the
instructions below should apply whatever your hosting platform.

1. Make sure *staticfiles* is configured correctly
----------------------------------------------------

If you're familiar with Django you'll know what to do. If you're just getting started
with a new Django project then you'll need add the following to the bottom of your
``settings.py`` file:

.. code-block:: python

   STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

As part of deploying your application you'll need to run ``./manage.py collectstatic`` to
put all your static files into ``STATIC_ROOT``. (If you're running on Heroku then
this is done automatically for you.)

In Django 1.9 and older, make sure you're using the static_ template tag to
refer to your static files. For example:

.. code-block:: html

   {% load static from staticfiles %}
   <img src="{% static "images/hi.jpg" %}" alt="Hi!" />

In Django 1.10 and later, you can use ``{% load static %}`` instead.

.. _static: https://docs.djangoproject.com/en/1.9/ref/contrib/staticfiles/#std:templatetag-staticfiles-static


.. _django-middleware:

2. Enable WhiteNoise
--------------------

Edit your ``settings.py`` file and add WhiteNoise to the ``MIDDLEWARE_CLASSES``
list. The WhiteNoise middleware should be placed directly after the Django `SecurityMiddleware
<https://docs.djangoproject.com/en/stable/ref/middleware/#module-django.middleware.security>`_ and before all other middleware:

.. code-block:: python

   MIDDLEWARE_CLASSES = [
     'django.middleware.security.SecurityMiddleware',
     'whitenoise.middleware.WhiteNoiseMiddleware',
     # ...
   ]

That's it -- WhiteNoise will now serve your static files. However, to get the
best performance you should proceed to step 3 below and enable compression and
caching.


3. Add compression and caching support
--------------------------------------

WhiteNoise comes with a storage backend which automatically takes care of
compressing your files and creating unique names for each version so they can
safely be cached forever. To use it, just add this to your ``settings.py``:

.. code-block:: python

   STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

If you need to compress files outside of the static files storage system you can
use the supplied :ref:`command line utility <cli-utility>`

.. note:: If you are having problems after switching to the WhiteNoise storage
   backend please see the :ref:`troubleshooting guide <storage-troubleshoot>`.

.. _brotli-compression:

Brotli compression
++++++++++++++++++
{'fraction_non_alphanumeric': 0.1273469387755102, 'fraction_numerical': 0.0035918367346938775, 'mean_word_length': 3.6763358778625954, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1948280', 'n_tokens_mistral': 1708, 'n_tokens_neox': 1611, 'n_words': 709}