Debian Codegraph @

docs/howto/deployment/wsgi/uwsgi.txt

raw
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