Ticket #16057: 16057.patch

File 16057.patch, 12.3 KB (added by aaugustin, 4 years ago)
  • docs/index.txt

     
    155155    * **Deployment:**
    156156      :doc:`Overview <howto/deployment/index>` |
    157157      :doc:`Apache/mod_wsgi <howto/deployment/modwsgi>` |
    158       :doc:`Apache/mod_python <howto/deployment/modpython>` |
     158      :doc:`uWSGI <howto/deployment/uwsgi>` |
     159      :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` |
    159160      :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` |
    160161      :doc:`Apache authentication <howto/apache-auth>` |
    161162      :doc:`Handling static files <howto/static-files>` |
  • docs/howto/deployment/index.txt

     
    1010   :maxdepth: 1
    1111
    1212   modwsgi
     13   uwsgi
    1314   fastcgi
    1415   mod_python (deprecated) <modpython>
    1516
    1617If you're new to deploying Django and/or Python, we'd recommend you try
    17 :doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be the easiest,
    18 fastest, and most stable deployment choice.
     18:doc:`mod_wsgi </howto/deployment/modwsgi>` first. In most cases it'll be
     19the easiest, fastest, and most stable deployment choice.
    1920
    2021.. seealso::
    2122
    22     * `Chapter 12 of The Django Book`_ discusses deployment and especially
    23       scaling in more detail.
     23    * `Chapter 12 of the Django Book`_ discusses deployment and especially
     24      scaling in more detail. However, it hasn't been updated since mod_python
     25      was deprecated.
    2426
    2527.. _chapter 12 of the django book: http://djangobook.com/en/2.0/chapter12/
  • docs/howto/deployment/uwsgi.txt

     
     1============================
     2How to use Django with uWSGI
     3============================
     4
     5.. highlight:: bash
     6
     7uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
     8container server coded in pure C.
     9
     10It also provides a fast `caching framework`_ but its documentation is not the
     11purpose of this document.
     12
     13.. _uWSGI: http://projects.unbit.it/uwsgi/
     14.. _caching framework: http://projects.unbit.it/uwsgi/wiki/CachingFramework
     15
     16
     17Prerequisite: uWSGI
     18===================
     19
     20The wiki describes several `installation procedures`_. Using pip, the python
     21package manager, installing any uWSGI version can be done with one command
     22line. For example::
     23
     24    # install current stable version
     25    pip install uwsgi
     26
     27    # or install LTS (long term support)
     28    pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
     29
     30.. _installation procedures: http://projects0.unbit.it/uwsgi/wiki/Install
     31
     32Prerequisite: general concept
     33=============================
     34
     35uWSGI model
     36-----------
     37
     38uWSGI operates on a client-server model. Your Web server (ie. nginx, Apache)
     39communicates with a django-uwsgi "worker" process to serve dynamic contents.
     40The Web server can communicate with the uWSGI process either:
     41
     42* directly by the uWSGI protocol through a socket created by uWSGI,
     43* or by proxying HTTP requests to the minimalist HTTP server built in uWSGI.
     44
     45In the first case: the Web server can do uWSGI protocol (often with a
     46module). It can then use either a Unix domain socket (a "named pipe" on Win32
     47systems), or it can use a TCP socket. What you choose is a matterr of
     48preference. Usually, a TCP socket is easier because connecting to a port
     49doesn't require special permissions.
     50
     51In the second case, the Web server doesn't need to do uWSGI protocol. It just
     52needs to be able to proxy HTTP requests to the HTTP server built-in uWSGI.
     53The procedure is the same than proxying any HTTP server. Note that the Web
     54server is a "reverse proxy" in this case.
     55
     56Configuring the uWSGI server
     57----------------------------
     58
     59In any case, when you set up your Web server, you'll just need to point its
     60uwsgi or proxy module to the host/port or socket you specified when starting
     61the uWSGI server.
     62
     63.. admonition:: Choosing the socket
     64
     65    The easiest is to set the socket to a high level (>49152) local port like
     66    127.0.0.1:49152. If the socket is a file, the system administrator must
     67    ensure that the Web server process has read, write and execute privileges
     68    on that file.
     69
     70uWSGI is highly configurable and thus there are many ways to start the
     71process. For example, uwsgi version 0.9.6.8 provides a hundred switches.
     72This guide demonstrates the most important of them, but does not intent to
     73substitute the official manual and online documentation.
     74
     75uWSGI supports configuration through:
     76
     77* environment variables
     78* command line switches
     79* ldap
     80* ini files
     81* xml files
     82* yaml files
     83
     84Managing the uWSGI server
     85-------------------------
     86
     87The system administrator controls the worker process pool by sending signals
     88to the master process. For example, the unix kill command sends such signals.
     89uWSGI can write the master process id to a "pidfile". A "pidfile" is a plain
     90text file containing just a process id.
     91
     92Starting the server
     93-------------------
     94
     95Starting an uWSGI server is the role of the system administrator, like
     96starting the Web server. It is *not* the role of the Web server to start the
     97uWSGI server. This means:
     98
     99* the uWSGI server can be restarted or reloaded independently from the Web
     100  server,
     101* (except with Cheerokee), it is the role of the system administrator to make
     102  uWSGI to start on boot or reboot: either through tools like supervisor or
     103  daemontools, either directly at init level in a file like /etc/rc.local or
     104  /etc/conf.d/local
     105
     106Managing uWSGI
     107==============
     108
     109Starting the server
     110-------------------
     111
     112Example command line for a Web server that understand the uWSGI protocol::
     113
     114    uwsgi --chdir=/path/to/your/project
     115        --module='django.core.handlers.wsgi:WSGIHandler()' \
     116        --env DJANGO_SETTINGS_MODULE=settings \
     117        --master --pidfile=/tmp/project-master.pid \
     118        --socket=127.0.0.1:49152 \      # can also be a file
     119        --processes=5 \                 # number of worker processes
     120        --uid=1000 --gid=2000 \         # if root, uwsgi can drop privileges
     121        --harakiri=20 \                 # respawn processes taking more than 20 seconds
     122        --limit-as=128 \                # limit the project to 128 Megabytes
     123        --max-requests=5000 \           # respawn processes after serving 5000 requests
     124        --vacuum \                      # clear environment on exit
     125        --home=/path/to/virtual/env \   # optionnal path to a virtualenv
     126        --daemonize=/var/log/uwsgi/yourproject.log      # background the process
     127
     128Django specific options are:
     129
     130* ``chdir``: should be the path to your project
     131* ``module``: uwsgi module to use
     132* ``pythonpath``: optional path to your project virtualenv
     133* ``env``: should contain at least ``DJANGO_SETTINGS_MODULE``
     134
     135Example ini configuration file::
     136
     137    [uwsgi]
     138    chdir=/path/to/your/project
     139    master=True
     140    pidfile=/tmp/project-master.pid
     141    vacuum=True
     142    max-requests=5000
     143    deamonize=/var/log/uwsgi/yourproject.log
     144
     145Example ini configuration file usage::
     146
     147    uwsgi --ini uwsgi.ini
     148
     149Read more `uWSGI configuration examples
     150<http://projects.unbit.it/uwsgi/wiki/Example>`_.
     151
     152.. admonition:: Massive application hosting
     153
     154    `uWSGI emperor <http://projects.unbit.it/uwsgi/wiki/Emperor>`_ is a special
     155    uWSGI process that can manage many master processes at once.
     156
     157Reloading the daemon
     158--------------------
     159
     160As mentioned above, the uWSGI master process is one of the core component of
     161the uWSGI stack. The signal to brutally reload all the workers and the master
     162process is SIGTERM. Example command to brutally reload the uWSGI processes::
     163
     164    kill -TERM `cat /tmp/project-master.pid`
     165
     166Patching the daemon
     167-------------------
     168
     169One of the great advantages of uWSGI is its ability to gradually restart each
     170worker without loosing any request.
     171
     172For example, uWSGI can be signaled that worker should reload the code after
     173handling their current request (if any) from bash::
     174
     175    # using kill to send the signal
     176    kill -HUP `cat /tmp/project-master.pid`
     177
     178    # if uwsgi was started with --touch-reload=/tmp/somefile
     179    touch /tmp/somefile
     180
     181Or from Python::
     182
     183    uwsgi.reload()
     184
     185Stopping the daemon
     186-------------------
     187
     188If you have the process running in the foreground, it's easy enough to stop it:
     189Simply hitting ``Ctrl-C`` will stop and quit the uWSGI server. However, when
     190you're dealing with background processes, you'll need to resort to the Unix
     191``kill`` command.
     192
     193The ``kill`` is used to send a signal to the uWSGI master process. The
     194`uWSGI signals are documented online
     195<http://projects.unbit.it/uwsgi/wiki/uWSGISignals>`_. Example command to
     196completely stop the uWSGI stack::
     197
     198    kill -INT `cat /tmp/project-master.pid`
     199
     200HTTP server configuration
     201=========================
     202
     203Nginx setup
     204-----------
     205
     206Nginx provides the `uwsgi module <http://wiki.nginx.org/HttpUwsgiModule>`_ by
     207default since nginx 0.8.40. Configuring Nginx to use an uWSGI server is as
     208simple as setting it up to proxy requests::
     209
     210    location / {
     211        uwsgi_pass 127.0.0.1:49152;
     212        # in case of a socket file:
     213        # uwsgi_pass unix:/tmp/yourproject.sock;
     214    }
     215
     216Note that default uwsgi parameters should be included somewhere in your Nginx
     217configuration. For example::
     218
     219    http {
     220        include       uwsgi_params;
     221        # [...] normal nginx configuration here
     222    }
     223
     224Cherokee setup
     225--------------
     226
     227Cherokee setup is documented in the `official Cherokee uWSGI documentation
     228<http://www.cherokee-project.com/doc/cookbook_uwsgi.html>`_.
     229
     230Lighttpd setup
     231--------------
     232
     233`Lighttpd uwsgi module <http://projects.unbit.it/uwsgi/wiki/RunOnLighttpd>`_ is
     234still experimental.
     235
     236Troubleshooting
     237===============
     238
     239As usual, the first things to do is to check the logs. This implies:
     240
     241* the web server log, which will indicate if it couldn't connect to the uWSGI
     242  process,
     243* the uWSGI log, which will indicate if an exception was thrown.
     244
     245Typical gotchas:
     246
     247* If the socket is a file, the Web server process should have read, write and
     248  execute permissions on the socket file. The ``--chmod-socket`` option can do
     249  it.
     250* In some cases, for instance if uWSGI was started without ``--vacuum`` or
     251  killed with ``SIGKILL``, it won't remove the socket and pidfile when it is
     252  interrupted. It is safe to remove them manually and to start uWSGI again in
     253  that case.
     254* uWSGI can start the process on the foreground, this will make errors easily
     255  visible to the system administrator.
  • docs/topics/install.txt

     
    2828=============================
    2929
    3030If you just want to experiment with Django, skip ahead to the next
    31 section; Django includes a lightweight Web server you can use for
     31section; Django includes a lightweight web server you can use for
    3232testing, so you won't need to set up Apache until you're ready to
    3333deploy Django in production.
    3434
    35 If you want to use Django on a production site, use Apache with
     35If you want to use Django on a production site, use `Apache`_ with
    3636`mod_wsgi`_. mod_wsgi can operate in one of two modes: an embedded
    3737mode and a daemon mode. In embedded mode, mod_wsgi is similar to
    3838mod_perl -- it embeds Python within Apache and loads Python code into
     
    5353installed.
    5454
    5555If you can't use mod_wsgi for some reason, fear not: Django supports
    56 many other deployment options. Another option is :doc:`FastCGI
     56many other deployment options. One is :doc:`uWSGI </howto/deployment/fastcgi>`;
     57it works very well with `nginx`_. Another is :doc:`FastCGI
    5758</howto/deployment/fastcgi>`, perfect for using Django with servers
    5859other than Apache. Additionally, Django follows the WSGI_ spec, which
    5960allows it to run on a variety of server platforms. See the
     
    6162instructions for each platform.
    6263
    6364.. _Apache: http://httpd.apache.org/
     65.. _nginx: http://nginx.net/
    6466.. _mod_wsgi: http://code.google.com/p/modwsgi/
    6567.. _WSGI: http://www.python.org/dev/peps/pep-0333/
    6668.. _server-arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements
Back to Top