mirror of
https://github.com/django/django.git
synced 2024-12-30 13:05:45 +00:00
b784768eef
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.
Backport of 534ac48297 from main.
119 lines
4.3 KiB
Plaintext
119 lines
4.3 KiB
Plaintext
============================
|
|
How to use Django with uWSGI
|
|
============================
|
|
|
|
uWSGI_ is a fast, self-healing and developer/sysadmin-friendly application
|
|
container server coded in pure C.
|
|
|
|
.. _uWSGI: https://uwsgi-docs.readthedocs.io/
|
|
|
|
.. seealso::
|
|
|
|
The uWSGI docs offer a `tutorial`_ covering Django, nginx, and uWSGI (one
|
|
possible deployment setup of many). The docs below are focused on how to
|
|
integrate Django with uWSGI.
|
|
|
|
.. _tutorial: https://uwsgi.readthedocs.io/en/latest/tutorials/Django_and_nginx.html
|
|
|
|
Prerequisite: uWSGI
|
|
===================
|
|
|
|
The uWSGI wiki describes several `installation procedures`_. Using pip, the
|
|
Python package manager, you can install any uWSGI version with a single
|
|
command. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
# Install current stable version.
|
|
$ python -m pip install uwsgi
|
|
|
|
# Or install LTS (long term support).
|
|
$ python -m pip install https://projects.unbit.it/downloads/uwsgi-lts.tar.gz
|
|
|
|
.. _installation procedures: https://uwsgi-docs.readthedocs.io/en/latest/Install.html
|
|
|
|
uWSGI model
|
|
-----------
|
|
|
|
uWSGI operates on a client-server model. Your web server (e.g., nginx, Apache)
|
|
communicates with a ``django-uwsgi`` "worker" process to serve dynamic content.
|
|
|
|
Configuring and starting the uWSGI server for Django
|
|
----------------------------------------------------
|
|
|
|
uWSGI supports multiple ways to configure the process. See uWSGI's
|
|
`configuration documentation`_.
|
|
|
|
.. _configuration documentation: https://uwsgi.readthedocs.io/en/latest/Configuration.html
|
|
|
|
Here's an example command to start a uWSGI server:
|
|
|
|
.. code-block:: shell
|
|
|
|
uwsgi --chdir=/path/to/your/project \
|
|
--module=mysite.wsgi:application \
|
|
--env DJANGO_SETTINGS_MODULE=mysite.settings \
|
|
--master --pidfile=/tmp/project-master.pid \
|
|
--socket=127.0.0.1:49152 \ # can also be a file
|
|
--processes=5 \ # number of worker processes
|
|
--uid=1000 --gid=2000 \ # if root, uwsgi can drop privileges
|
|
--harakiri=20 \ # respawn processes taking more than 20 seconds
|
|
--max-requests=5000 \ # respawn processes after serving 5000 requests
|
|
--vacuum \ # clear environment on exit
|
|
--home=/path/to/virtual/env \ # optional path to a virtual environment
|
|
--daemonize=/var/log/uwsgi/yourproject.log # background the process
|
|
|
|
This assumes you have a top-level project package named ``mysite``, and
|
|
within it a module :file:`mysite/wsgi.py` that contains a WSGI ``application``
|
|
object. This is the layout you'll have if you ran ``django-admin
|
|
startproject mysite`` (using your own project name in place of ``mysite``) with
|
|
a recent version of Django. If this file doesn't exist, you'll need to create
|
|
it. See the :doc:`/howto/deployment/wsgi/index` documentation for the default
|
|
contents you should put in this file and what else you can add to it.
|
|
|
|
The Django-specific options here are:
|
|
|
|
* ``chdir``: The path to the directory that needs to be on Python's import
|
|
path -- i.e., the directory containing the ``mysite`` package.
|
|
* ``module``: The WSGI module to use -- probably the ``mysite.wsgi`` module
|
|
that :djadmin:`startproject` creates.
|
|
* ``env``: Should probably contain at least :envvar:`DJANGO_SETTINGS_MODULE`.
|
|
* ``home``: Optional path to your project virtual environment.
|
|
|
|
Example ini configuration file:
|
|
|
|
.. code-block:: ini
|
|
|
|
[uwsgi]
|
|
chdir=/path/to/your/project
|
|
module=mysite.wsgi:application
|
|
master=True
|
|
pidfile=/tmp/project-master.pid
|
|
vacuum=True
|
|
max-requests=5000
|
|
daemonize=/var/log/uwsgi/yourproject.log
|
|
|
|
Example ini configuration file usage:
|
|
|
|
.. code-block:: shell
|
|
|
|
uwsgi --ini uwsgi.ini
|
|
|
|
.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads
|
|
|
|
If you get a ``UnicodeEncodeError`` when uploading files with file names
|
|
that contain non-ASCII characters, make sure uWSGI is configured to accept
|
|
non-ASCII file names by adding this to your ``uwsgi.ini``:
|
|
|
|
.. code-block:: ini
|
|
|
|
env = LANG=en_US.UTF-8
|
|
|
|
See the :ref:`unicode-files` section of the Unicode reference guide for
|
|
details.
|
|
|
|
See the uWSGI docs on `managing the uWSGI process`_ for information on
|
|
starting, stopping and reloading the uWSGI workers.
|
|
|
|
.. _managing the uWSGI process: https://uwsgi-docs.readthedocs.io/en/latest/Management.html
|