=======================
How to deploy with WSGI
=======================

Django's primary deployment platform is WSGI_, the Python standard for web
servers and applications.

.. _WSGI: http://www.wsgi.org

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 webserver to use. Django includes getting-started
documentation for the following WSGI servers:

.. toctree::
   :maxdepth: 1

   modwsgi
   gunicorn
   uwsgi

The ``application`` object
--------------------------

One key concept of deploying with WSGI is to specify a central ``application``
callable object which the webserver uses to communicate with your code. This is
commonly specified as an object named ``application`` in a Python module
accessible to the server.

.. versionchanged:: 1.4

The :djadmin:`startproject` command creates a :file:`projectname/wsgi.py` that
contains such an application callable.

.. note::

   Upgrading from a previous release of Django and don't have a :file:`wsgi.py`
   file in your project? You can simply add one to your project's top-level
   Python package (probably next to :file:`settings.py` and :file:`urls.py`)
   with the contents below. If you want :djadmin:`runserver` to also make use
   of this WSGI file, you can also add ``WSGI_APPLICATION =
   "mysite.wsgi.application"`` in your settings (replacing ``mysite`` with the
   name of your project).

Initially this file contains::

    import os

    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "mysite.settings")

    # This application object is used by the development server
    # as well as any WSGI server configured to use this file.
    from django.core.handlers.wsgi import get_wsgi_application
    application = get_wsgi_application()

The ``os.environ.setdefault`` line just sets the default settings module to
use, if you haven't explicitly set the :envvar:`DJANGO_SETTINGS_MODULE`
environment variable. You'll need to edit this line to replace ``mysite`` with
the name of your project package, so the path to your settings module is
correct.

To apply `WSGI middleware`_ you can simply wrap the application object
in the same file::

    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`: http://www.python.org/dev/peps/pep-3333/#middleware-components-that-play-both-sides