Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #17073 - focused uwsgi docs to Django integration; thanks Prest…

…on Holmes.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17586 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5a013cebd92e5d935088043398e6c04ff6107879 1 parent ce4cd78
Tim Graham timgraham authored
Showing with 13 additions and 182 deletions.
  1. +13 −182 docs/howto/deployment/wsgi/uwsgi.txt
195 docs/howto/deployment/wsgi/uwsgi.txt
View
@@ -7,12 +7,7 @@ How to use Django with uWSGI
uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
container server coded in pure C.
-It also provides a fast `caching framework`_ but its documentation is not the
-purpose of this document.
-
.. _uWSGI: http://projects.unbit.it/uwsgi/
-.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework
-
Prerequisite: uWSGI
===================
@@ -27,89 +22,27 @@ line. For example::
# or install LTS (long term support)
pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
-.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install
-
-Prerequisite: general concept
-=============================
+.. _installation procedures: http://projects.unbit.it/uwsgi/wiki/Install
uWSGI model
-----------
uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache)
communicates with a django-uwsgi "worker" process to serve dynamic content.
-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:
+See uWSGI's `background documentation`_ for more detail.
-* environment variables
-* command line switches
-* ldap
-* ini files
-* xml files
-* yaml files
+.. _background documentation: http://projects.unbit.it/uwsgi/wiki/Background
-Managing the uWSGI server
--------------------------
+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.
+uWSGI supports multiple ways to configure the process, see uWSGI's
+`configuration documentation`_ and `examples`_
-Starting the server
--------------------
+.. _configuration documentation: http://projects.unbit.it/uwsgi/wiki/Doc
+.. _examples: http://projects.unbit.it/uwsgi/wiki/Example
-Starting an uWSGI server is the role of the system administrator, like
-starting the Web server. It is *not* the role of the Web server to start the
-uWSGI server. This means:
-
-* the uWSGI server can be restarted or reloaded independently from the Web
- server,
-* (except with Cherokee), it is the role of the system administrator to make
- uWSGI start on boot or reboot: either through tools like supervisor or
- daemontools, either directly at init level in a file like /etc/rc.local or
- /etc/conf.d/local
-
-Managing uWSGI
-==============
-
-Starting the server
--------------------
-
-Example command line for a Web server that understands the uWSGI protocol::
+An example command to start a uWSGI server::
uwsgi --chdir=/path/to/your/project
--module='mysite.wsgi:application' \
@@ -156,110 +89,8 @@ Example ini configuration file usage::
uwsgi --ini uwsgi.ini
-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.
-Typical gotchas:
+See the uWSGI docs on `managing the uWSGI process`_ for information on
+starting, stoping, and reloading the uWSGI workers.
-* If the socket is a file, the Web server process should have read, write and
- execute permissions on the socket file. The ``--chmod-socket`` option can do
- it.
-* In some cases, for instance if uWSGI was started without ``--vacuum`` or
- killed with ``SIGKILL``, it won't remove the socket and pidfile when it is
- interrupted. It is safe to remove them manually and to start uWSGI again in
- that case.
-* uWSGI can start the process in the foreground, this will make errors easily
- visible to the system administrator.
+.. _managing the uWSGI process: http://projects.unbit.it/uwsgi/wiki/Management
Please sign in to comment.
Something went wrong with that request. Please try again.