| 1 |
============================ |
| 2 |
How to use Django with uWSGI |
| 3 |
============================ |
| 4 |
|
| 5 |
uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application |
| 6 |
container server coded in pure C. |
| 7 |
|
| 8 |
.. _uWSGI: https://uwsgi-docs.readthedocs.io/ |
| 9 |
|
| 10 |
.. seealso:: |
| 11 |
|
| 12 |
The uWSGI docs offer a `tutorial`_ covering Django, nginx, and uWSGI (one |
| 13 |
possible deployment setup of many). The docs below are focused on how to |
| 14 |
integrate Django with uWSGI. |
| 15 |
|
| 16 |
.. _tutorial: https://uwsgi.readthedocs.io/en/latest/tutorials/Django_and_nginx.html |
| 17 |
|
| 18 |
Prerequisite: uWSGI |
| 19 |
=================== |
| 20 |
|
| 21 |
The uWSGI wiki describes several `installation procedures`_. Using pip, the |
| 22 |
Python package manager, you can install any uWSGI version with a single |
| 23 |
command. For example: |
| 24 |
|
| 25 |
.. code-block:: console |
| 26 |
|
| 27 |
# Install current stable version. |
| 28 |
$ python -m pip install uwsgi |
| 29 |
|
| 30 |
# Or install LTS (long term support). |
| 31 |
$ python -m pip install https://projects.unbit.it/downloads/uwsgi-lts.tar.gz |
| 32 |
|
| 33 |
.. _installation procedures: https://uwsgi-docs.readthedocs.io/en/latest/Install.html |
| 34 |
|
| 35 |
uWSGI model |
| 36 |
----------- |
| 37 |
|
| 38 |
uWSGI operates on a client-server model. Your web server (e.g., nginx, Apache) |
| 39 |
communicates with a ``django-uwsgi`` "worker" process to serve dynamic content. |
| 40 |
|
| 41 |
Configuring and starting the uWSGI server for Django |
| 42 |
---------------------------------------------------- |
| 43 |
|
| 44 |
uWSGI supports multiple ways to configure the process. See uWSGI's |
| 45 |
`configuration documentation`_. |
| 46 |
|
| 47 |
.. _configuration documentation: https://uwsgi.readthedocs.io/en/latest/Configuration.html |
| 48 |
|
| 49 |
Here's an example command to start a uWSGI server: |
| 50 |
|
| 51 |
.. code-block:: shell |
| 52 |
|
| 53 |
uwsgi --chdir=/path/to/your/project \ |
| 54 |
--module=mysite.wsgi:application \ |
| 55 |
--env DJANGO_SETTINGS_MODULE=mysite.settings \ |
| 56 |
--master --pidfile=/tmp/project-master.pid \ |
| 57 |
--socket=127.0.0.1:49152 \ # can also be a file |
| 58 |
--processes=5 \ # number of worker processes |
| 59 |
--uid=1000 --gid=2000 \ # if root, uwsgi can drop privileges |
| 60 |
--harakiri=20 \ # respawn processes taking more than 20 seconds |
| 61 |
--max-requests=5000 \ # respawn processes after serving 5000 requests |
| 62 |
--vacuum \ # clear environment on exit |
| 63 |
--home=/path/to/virtual/env \ # optional path to a virtual environment |
| 64 |
--daemonize=/var/log/uwsgi/yourproject.log # background the process |
| 65 |
|
| 66 |
This assumes you have a top-level project package named ``mysite``, and |
| 67 |
within it a module :file:`mysite/wsgi.py` that contains a WSGI ``application`` |
| 68 |
object. This is the layout you'll have if you ran ``django-admin |
| 69 |
startproject mysite`` (using your own project name in place of ``mysite``) with |
| 70 |
a recent version of Django. If this file doesn't exist, you'll need to create |
| 71 |
it. See the :doc:`/howto/deployment/wsgi/index` documentation for the default |
| 72 |
contents you should put in this file and what else you can add to it. |
| 73 |
|
| 74 |
The Django-specific options here are: |
| 75 |
|
| 76 |
* ``chdir``: The path to the directory that needs to be on Python's import |
| 77 |
path -- i.e., the directory containing the ``mysite`` package. |
| 78 |
* ``module``: The WSGI module to use -- probably the ``mysite.wsgi`` module |
| 79 |
that :djadmin:`startproject` creates. |
| 80 |
* ``env``: Should probably contain at least :envvar:`DJANGO_SETTINGS_MODULE`. |
| 81 |
* ``home``: Optional path to your project virtual environment. |
| 82 |
|
| 83 |
Example ini configuration file: |
| 84 |
|
| 85 |
.. code-block:: ini |
| 86 |
|
| 87 |
[uwsgi] |
| 88 |
chdir=/path/to/your/project |
| 89 |
module=mysite.wsgi:application |
| 90 |
master=True |
| 91 |
pidfile=/tmp/project-master.pid |
| 92 |
vacuum=True |
| 93 |
max-requests=5000 |
| 94 |
daemonize=/var/log/uwsgi/yourproject.log |
| 95 |
|
| 96 |
Example ini configuration file usage: |
| 97 |
|
| 98 |
.. code-block:: shell |
| 99 |
|
| 100 |
uwsgi --ini uwsgi.ini |
| 101 |
|
| 102 |
.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads |
| 103 |
|
| 104 |
If you get a ``UnicodeEncodeError`` when uploading files with file names |
| 105 |
that contain non-ASCII characters, make sure uWSGI is configured to accept |
| 106 |
non-ASCII file names by adding this to your ``uwsgi.ini``: |
| 107 |
|
| 108 |
.. code-block:: ini |
| 109 |
|
| 110 |
env = LANG=en_US.UTF-8 |
| 111 |
|
| 112 |
See the :ref:`unicode-files` section of the Unicode reference guide for |
| 113 |
details. |
| 114 |
|
| 115 |
See the uWSGI docs on `managing the uWSGI process`_ for information on |
| 116 |
starting, stopping and reloading the uWSGI workers. |
| 117 |
|
| 118 |
.. _managing the uWSGI process: https://uwsgi-docs.readthedocs.io/en/latest/Management.html |