| 1 |
======================= |
| 2 |
How to deploy with WSGI |
| 3 |
======================= |
| 4 |
|
| 5 |
Django's primary deployment platform is WSGI_, the Python standard for web |
| 6 |
servers and applications. |
| 7 |
|
| 8 |
.. _WSGI: https://wsgi.readthedocs.io/en/latest/ |
| 9 |
|
| 10 |
Django's :djadmin:`startproject` management command sets up a minimal default |
| 11 |
WSGI configuration for you, which you can tweak as needed for your project, |
| 12 |
and direct any WSGI-compliant application server to use. |
| 13 |
|
| 14 |
Django includes getting-started documentation for the following WSGI servers: |
| 15 |
|
| 16 |
.. toctree:: |
| 17 |
:maxdepth: 1 |
| 18 |
|
| 19 |
gunicorn |
| 20 |
uwsgi |
| 21 |
modwsgi |
| 22 |
apache-auth |
| 23 |
|
| 24 |
The ``application`` object |
| 25 |
========================== |
| 26 |
|
| 27 |
The key concept of deploying with WSGI is the ``application`` callable which |
| 28 |
the application server uses to communicate with your code. It's commonly |
| 29 |
provided as an object named ``application`` in a Python module accessible to |
| 30 |
the server. |
| 31 |
|
| 32 |
The :djadmin:`startproject` command creates a file |
| 33 |
:file:`<project_name>/wsgi.py` that contains such an ``application`` callable. |
| 34 |
|
| 35 |
It's used both by Django's development server and in production WSGI |
| 36 |
deployments. |
| 37 |
|
| 38 |
WSGI servers obtain the path to the ``application`` callable from their |
| 39 |
configuration. Django's built-in server, namely the :djadmin:`runserver` |
| 40 |
command, reads it from the :setting:`WSGI_APPLICATION` setting. By default, it's |
| 41 |
set to ``<project_name>.wsgi.application``, which points to the ``application`` |
| 42 |
callable in :file:`<project_name>/wsgi.py`. |
| 43 |
|
| 44 |
Configuring the settings module |
| 45 |
=============================== |
| 46 |
|
| 47 |
When the WSGI server loads your application, Django needs to import the |
| 48 |
settings module — that's where your entire application is defined. |
| 49 |
|
| 50 |
Django uses the :envvar:`DJANGO_SETTINGS_MODULE` environment variable to |
| 51 |
locate the appropriate settings module. It must contain the dotted path to the |
| 52 |
settings module. You can use a different value for development and production; |
| 53 |
it all depends on how you organize your settings. |
| 54 |
|
| 55 |
If this variable isn't set, the default :file:`wsgi.py` sets it to |
| 56 |
``mysite.settings``, where ``mysite`` is the name of your project. That's how |
| 57 |
:djadmin:`runserver` discovers the default settings file by default. |
| 58 |
|
| 59 |
.. note:: |
| 60 |
|
| 61 |
Since environment variables are process-wide, this doesn't work when you |
| 62 |
run multiple Django sites in the same process. This happens with mod_wsgi. |
| 63 |
|
| 64 |
To avoid this problem, use mod_wsgi's daemon mode with each site in its |
| 65 |
own daemon process, or override the value from the environment by |
| 66 |
enforcing ``os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"`` in |
| 67 |
your :file:`wsgi.py`. |
| 68 |
|
| 69 |
|
| 70 |
Applying WSGI middleware |
| 71 |
======================== |
| 72 |
|
| 73 |
To apply :pep:`WSGI middleware |
| 74 |
<3333#middleware-components-that-play-both-sides>` you can wrap the application |
| 75 |
object. For instance you could add these lines at the bottom of |
| 76 |
:file:`wsgi.py`:: |
| 77 |
|
| 78 |
from helloworld.wsgi import HelloWorldApplication |
| 79 |
|
| 80 |
application = HelloWorldApplication(application) |
| 81 |
|
| 82 |
You could also replace the Django WSGI application with a custom WSGI |
| 83 |
application that later delegates to the Django WSGI application, if you want |
| 84 |
to combine a Django application with a WSGI application of another framework. |