How do you serve a Django app's static files with WhiteNoise when it runs in a single container with no separate web server?

## The gap WhiteNoise fills Django's `staticfiles` app finds and collects assets, but it deliberately does not serve them in production. The development server's static handler only runs when `DEBUG` is `True` (or with `runserver --insecure`), and Django's docs treat that path as unsuitable for production. The classic answer is a separate web server in front of Django that serves `STATIC_ROOT` directly. When the deployment is **one container running only the application server**, there is no such server, and that is the scenario **WhiteNoise** is designed for: the Django process serves its own collected assets, with sensible caching and compression. ## The setup, step by step 1. **Install the package** (`pip install whitenoise`, or `whitenoise[brotli]` to also produce Brotli files). 2. **Set `STATIC_ROOT`**, the directory `collectstatic` writes into, for example `BASE_DIR / 'staticfiles'`. 3. **Add the middleware** directly after `SecurityMiddleware` in `MIDDLEWARE`. 4. **Choose the storage backend** under the `staticfiles` alias of `STORAGES`: `whitenoise.storage.CompressedManifestStaticFilesStorage` adds content-hashed names and pre-compressed copies. 5. **Run `collectstatic --noinput` during the image build**, so `STATIC_ROOT` is populated inside the image. 6. **Reference assets with `{% static %}`**, never with hand-written `/static/...` paths, so templates pick up the hashed names. ```python STATIC_URL = 'static/' STATIC_ROOT = BASE_DIR / 'staticfiles' STORAGES = { 'default': {'BACKEND': 'django.core.files.storage.FileSystemStorage'}, 'staticfiles': { 'BACKEND': 'whitenoise.storage.CompressedManifestStaticFilesStorage', }, } ``` ## Why the build order matters In production WhiteNoise reads `STATIC_ROOT` **once**, in the middleware's constructor, and serves from that in-memory index. Two consequences follow: - If `collectstatic` runs in a start-up script after the server has already booted, the processes that booted first serve 404s for every asset until restarted. - If `STATIC_ROOT` is a volume mounted at run time and populated later, the same thing happens. Baking the collected files into the image avoids both, and it also means every replica of the container carries identical assets. ## Development parity By default `runserver` handles static files itself when `DEBUG` is on, so WhiteNoise's headers and compression never appear locally. Adding `whitenoise.runserver_nostatic` **above** `django.contrib.staticfiles` in `INSTALLED_APPS` changes `runserver`'s default to the equivalent of `--nostatic`, and WhiteNoise serves files in development too. In `DEBUG` mode WhiteNoise also defaults `WHITENOISE_USE_FINDERS` and `WHITENOISE_AUTOREFRESH` to `True`, so it finds files in app directories and picks up edits without `collectstatic`. ## What WhiteNoise is not for | Concern | Guidance | |---|---| | User uploads (`MEDIA_ROOT`) | Not suitable: files added after start-up are unseen, and serving uploads from the app's own domain is a security risk | | Remote storage backends | WhiteNoise only serves files stored on the local filesystem in `STATIC_ROOT` | | Very high asset traffic | Put a CDN in front; WhiteNoise's cache headers let it cache hashed files for a long time | ## Common mistakes - Forgetting `STATIC_ROOT`, so `collectstatic` has nowhere to write. - Configuring the storage through `STATICFILES_STORAGE` from an old guide; that setting was removed in Django 5.1. - Leaving a `node_modules` tree inside `STATIC_ROOT`, which slows start-up because every file is indexed.