  * ini files
  * xml files
  * yaml files
  
  Managing the uWSGI server
  -------------------------
  
  The system administrator controls the worker process pool by sending signals
  to the master process. For example, the unix kill command sends such signals.
  uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
  text file containing just a process id.
 
</s> remove The system administrator controls the worker process pool by sending signals
to the master process. For example, the unix kill command sends such signals.
uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
text file containing just a process id.
 </s> add uWSGI supports multiple ways to configure the process, see uWSGI's
`configuration documentation`_ and `examples`_ </s> remove Starting the server
-------------------
 </s> add .. _configuration documentation: http://projects.unbit.it/uwsgi/wiki/Doc
.. _examples: http://projects.unbit.it/uwsgi/wiki/Example </s> remove * environment variables
* command line switches
* ldap
* ini files
* xml files
* yaml files
 </s> add .. _background documentation: http://projects.unbit.it/uwsgi/wiki/Background </s> remove The Web server can communicate with the uWSGI process either:

* directly by the uWSGI protocol through a socket created by uWSGI,
* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI.

In the first case: the Web server can do uWSGI protocol (often with a
module). It can then use either a Unix domain socket (a "named pipe" on Win32
systems), or it can use a TCP socket. What you choose is a matterr of
preference. Usually, a TCP socket is easier because connecting to a port
doesn't require special permissions.

In the second case, the Web server doesn't need to speak the uWSGI protocol. It
just needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI.
The procedure is the same as proxying to any HTTP server. Note that the Web
server is a "reverse proxy" in this case.

Configuring the uWSGI server
----------------------------

In any case, when you set up your Web server, you'll just need to point its
uwsgi or proxy module to the host/port or socket you specified when starting
the uWSGI server.

.. admonition:: Choosing the socket

    The easiest is to set the socket to a high level (>49152) local port like
    127.0.0.1:49152. If the socket is a file, the system administrator must
    ensure that the Web server process has read, write and execute privileges
    on that file.

uWSGI is highly configurable and thus there are many ways to start the
process. For example, uwsgi version 0.9.6.8 provides a hundred switches.  This
guide demonstrates the most important of them, but is not a substitute the
official manual and online documentation.

uWSGI supports configuration through:
 </s> add See uWSGI's `background documentation`_ for more detail. </s> remove Read more `uWSGI configuration examples
<http://projects.unbit.it/uwsgi/wiki/Example>`_.

.. admonition:: Massive application hosting

    `uWSGI emperor <http://projects.unbit.it/uwsgi/wiki/Emperor>`_ is a special
    uWSGI process that can manage many master processes at once.

Reloading the daemon
--------------------

As mentioned above, the uWSGI master process is one of the core components of
the uWSGI stack. The signal to brutally reload all the workers and the master
process is SIGTERM. Example command to brutally reload the uWSGI processes::

    kill -TERM `cat /tmp/project-master.pid`

Patching the daemon
-------------------

One of the great advantages of uWSGI is its ability to gradually restart each
worker without losing any requests.

For example, uWSGI can be signaled that worker should reload the code after
handling their current request (if any) from bash::

    # using kill to send the signal
    kill -HUP `cat /tmp/project-master.pid`

    # if uwsgi was started with --touch-reload=/tmp/somefile
    touch /tmp/somefile

Or from Python::

    uwsgi.reload()

Stopping the daemon
-------------------

If you have the process running in the foreground, it's easy enough to stop it:
Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when
you're dealing with background processes, you'll need to resort to the Unix
``kill`` command.

The ``kill`` is used to send a signal to the uWSGI master process. The
`uWSGI signals are documented online
<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. Example command to
completely stop the uWSGI stack::

    kill -INT `cat /tmp/project-master.pid`

HTTP server configuration
=========================

Nginx setup
-----------

Nginx provides the `uwsgi module <http://wiki.nginx.org/HttpUwsgiModule>`_ by
default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as
simple as setting it up to proxy requests::

    location / {
        uwsgi_pass 127.0.0.1:49152;
        # in case of a socket file:
        # uwsgi_pass unix:/tmp/yourproject.sock;
    }

Note that default uwsgi parameters should be included somewhere in your Nginx
configuration. For example::

    http {
        include       uwsgi_params;
        # [...] normal nginx configuration here
    }

Cherokee setup
--------------

Cherokee setup is documented in the `official Cherokee uWSGI documentation
<http://www.cherokee-project.com/doc/cookbook_uwsgi.html>`_.

Lighttpd setup
--------------

`Lighttpd uwsgi module <http://projects.unbit.it/uwsgi/wiki/RunOnLighttpd>`_ is
still experimental.

Troubleshooting
===============

As usual, the first thing to do is to check the logs. This implies:

* the web server log, which will indicate if it couldn't connect to the uWSGI
  process,
* the uWSGI log, which will indicate if an exception was thrown.
 </s> add 
Configuring and starting the uWSGI server for Django
----------------------------------------------------
  * ini files
  * xml files
  * yaml files
  
Configuring and starting the uWSGI server for Django
----------------------------------------------------
Configuring and starting the uWSGI server for Django
----------------------------------------------------
  
  The system administrator controls the worker process pool by sending signals
  to the master process. For example, the unix kill command sends such signals.
  uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
  text file containing just a process id.
keep keep keep keep replace replace keep keep keep keep keep
 Fixed #17073 - focused uwsgi docs to Django integration; thanks Preston Holmes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17586 bcc190cf-cafb-0310-a4f2-bffc1f526a37 
docs/howto/deployment/wsgi/uwsgi.txt