django/docs/howto/deployment/wsgi/index.txt

84 lines
3.1 KiB
Plaintext

=======================
How to deploy with WSGI
=======================
Django's primary deployment platform is WSGI_, the Python standard for web
servers and applications.
.. _WSGI: https://wsgi.readthedocs.io/en/latest/
Django's :djadmin:`startproject` management command sets up a simple default
WSGI configuration for you, which you can tweak as needed for your project,
and direct any WSGI-compliant application server to use.
Django includes getting-started documentation for the following WSGI servers:
.. toctree::
:maxdepth: 1
modwsgi
apache-auth
gunicorn
uwsgi
The ``application`` object
==========================
The key concept of deploying with WSGI is the ``application`` callable which
the application server uses to communicate with your code. It's commonly
provided as an object named ``application`` in a Python module accessible to
the server.
The :djadmin:`startproject` command creates a file
:file:`<project_name>/wsgi.py` that contains such an ``application`` callable.
It's used both by Django's development server and in production WSGI
deployments.
WSGI servers obtain the path to the ``application`` callable from their
configuration. Django's built-in server, namely the :djadmin:`runserver`
command, reads it from the :setting:`WSGI_APPLICATION` setting. By default, it's
set to ``<project_name>.wsgi.application``, which points to the ``application``
callable in :file:`<project_name>/wsgi.py`.
Configuring the settings module
===============================
When the WSGI server loads your application, Django needs to import the
settings module — that's where your entire application is defined.
Django uses the :envvar:`DJANGO_SETTINGS_MODULE` environment variable to
locate the appropriate settings module. It must contain the dotted path to the
settings module. You can use a different value for development and production;
it all depends on how you organize your settings.
If this variable isn't set, the default :file:`wsgi.py` sets it to
``mysite.settings``, where ``mysite`` is the name of your project. That's how
:djadmin:`runserver` discovers the default settings file by default.
.. note::
Since environment variables are process-wide, this doesn't work when you
run multiple Django sites in the same process. This happens with mod_wsgi.
To avoid this problem, use mod_wsgi's daemon mode with each site in its
own daemon process, or override the value from the environment by
enforcing ``os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"`` in
your :file:`wsgi.py`.
Applying WSGI middleware
========================
To apply `WSGI middleware`_ you can simply wrap the application object. For
instance you could add these lines at the bottom of :file:`wsgi.py`::
from helloworld.wsgi import HelloWorldApplication
application = HelloWorldApplication(application)
You could also replace the Django WSGI application with a custom WSGI
application that later delegates to the Django WSGI application, if you want
to combine a Django application with a WSGI application of another framework.
.. _`WSGI middleware`: https://www.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides