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.
231 lines
8.5 KiB
Plaintext
231 lines
8.5 KiB
Plaintext
==============================================
|
|
How to use Django with Apache and ``mod_wsgi``
|
|
==============================================
|
|
|
|
Deploying Django with Apache_ and `mod_wsgi`_ is a tried and tested way to get
|
|
Django into production.
|
|
|
|
.. _Apache: https://httpd.apache.org/
|
|
.. _mod_wsgi: https://modwsgi.readthedocs.io/en/develop/
|
|
|
|
mod_wsgi is an Apache module which can host any Python WSGI_ application,
|
|
including Django. Django will work with any version of Apache which supports
|
|
mod_wsgi.
|
|
|
|
.. _WSGI: https://wsgi.readthedocs.io/en/latest/
|
|
|
|
The `official mod_wsgi documentation`_ is your source for all the details about
|
|
how to use mod_wsgi. You'll probably want to start with the `installation and
|
|
configuration documentation`_.
|
|
|
|
.. _official mod_wsgi documentation: https://modwsgi.readthedocs.io/
|
|
.. _installation and configuration documentation: https://modwsgi.readthedocs.io/en/develop/installation.html
|
|
|
|
Basic configuration
|
|
===================
|
|
|
|
Once you've got mod_wsgi installed and activated, edit your Apache server's
|
|
`httpd.conf`_ file and add the following.
|
|
|
|
.. _httpd.conf: https://cwiki.apache.org/confluence/display/httpd/DistrosDefaultLayout
|
|
|
|
.. code-block:: apache
|
|
|
|
WSGIScriptAlias / /path/to/mysite.com/mysite/wsgi.py
|
|
WSGIPythonHome /path/to/venv
|
|
WSGIPythonPath /path/to/mysite.com
|
|
|
|
<Directory /path/to/mysite.com/mysite>
|
|
<Files wsgi.py>
|
|
Require all granted
|
|
</Files>
|
|
</Directory>
|
|
|
|
The first bit in the ``WSGIScriptAlias`` line is the base URL path you want to
|
|
serve your application at (``/`` indicates the root url), and the second is the
|
|
location of a "WSGI file" -- see below -- on your system, usually inside of
|
|
your project package (``mysite`` in this example). This tells Apache to serve
|
|
any request below the given URL using the WSGI application defined in that
|
|
file.
|
|
|
|
If you install your project's Python dependencies inside a :mod:`virtual
|
|
environment <venv>`, add the path using ``WSGIPythonHome``. See the `mod_wsgi
|
|
virtual environment guide`_ for more details.
|
|
|
|
The ``WSGIPythonPath`` line ensures that your project package is available for
|
|
import on the Python path; in other words, that ``import mysite`` works.
|
|
|
|
The ``<Directory>`` piece ensures that Apache can access your :file:`wsgi.py`
|
|
file.
|
|
|
|
Next we'll need to ensure this :file:`wsgi.py` with a WSGI application object
|
|
exists. As of Django version 1.4, :djadmin:`startproject` will have created one
|
|
for you; otherwise, you'll need to create it. See the :doc:`WSGI overview
|
|
documentation</howto/deployment/wsgi/index>` for the default contents you
|
|
should put in this file, and what else you can add to it.
|
|
|
|
.. _mod_wsgi virtual environment guide: https://modwsgi.readthedocs.io/en/develop/user-guides/virtual-environments.html
|
|
|
|
.. warning::
|
|
|
|
If multiple Django sites are run in a single mod_wsgi process, all of them
|
|
will use the settings of whichever one happens to run first. This can be
|
|
solved by changing::
|
|
|
|
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")
|
|
|
|
in ``wsgi.py``, to::
|
|
|
|
os.environ["DJANGO_SETTINGS_MODULE"] = "{{ project_name }}.settings"
|
|
|
|
or by :ref:`using mod_wsgi daemon mode<daemon-mode>` and ensuring that each
|
|
site runs in its own daemon process.
|
|
|
|
.. admonition:: Fixing ``UnicodeEncodeError`` for file uploads
|
|
|
|
If you get a ``UnicodeEncodeError`` when uploading or writing files with
|
|
file names or content that contains non-ASCII characters, make sure Apache
|
|
is configured to support UTF-8 encoding:
|
|
|
|
.. code-block:: shell
|
|
|
|
export LANG='en_US.UTF-8'
|
|
export LC_ALL='en_US.UTF-8'
|
|
|
|
A common location to put this configuration is ``/etc/apache2/envvars``.
|
|
|
|
Alternatively, if you are :ref:`using mod_wsgi daemon mode<daemon-mode>`
|
|
you can add ``lang`` and ``locale`` options to the ``WSGIDaemonProcess``
|
|
directive:
|
|
|
|
.. code-block:: text
|
|
|
|
WSGIDaemonProcess example.com lang='en_US.UTF-8' locale='en_US.UTF-8'
|
|
|
|
See the :ref:`unicode-files` section of the Unicode reference guide for
|
|
details.
|
|
|
|
.. _daemon-mode:
|
|
|
|
Using ``mod_wsgi`` daemon mode
|
|
==============================
|
|
|
|
"Daemon mode" is the recommended mode for running mod_wsgi (on non-Windows
|
|
platforms). To create the required daemon process group and delegate the
|
|
Django instance to run in it, you will need to add appropriate
|
|
``WSGIDaemonProcess`` and ``WSGIProcessGroup`` directives. A further change
|
|
required to the above configuration if you use daemon mode is that you can't
|
|
use ``WSGIPythonPath``; instead you should use the ``python-path`` option to
|
|
``WSGIDaemonProcess``, for example:
|
|
|
|
.. code-block:: apache
|
|
|
|
WSGIDaemonProcess example.com python-home=/path/to/venv python-path=/path/to/mysite.com
|
|
WSGIProcessGroup example.com
|
|
|
|
If you want to serve your project in a subdirectory
|
|
(``https://example.com/mysite`` in this example), you can add ``WSGIScriptAlias``
|
|
to the configuration above:
|
|
|
|
.. code-block:: apache
|
|
|
|
WSGIScriptAlias /mysite /path/to/mysite.com/mysite/wsgi.py process-group=example.com
|
|
|
|
See the official mod_wsgi documentation for `details on setting up daemon
|
|
mode`_.
|
|
|
|
.. _details on setting up daemon mode: https://modwsgi.readthedocs.io/en/develop/user-guides/quick-configuration-guide.html#delegation-to-daemon-process
|
|
|
|
.. _serving-files:
|
|
|
|
Serving files
|
|
=============
|
|
|
|
Django doesn't serve files itself; it leaves that job to whichever web
|
|
server you choose.
|
|
|
|
We recommend using a separate web server -- i.e., one that's not also running
|
|
Django -- for serving media. Here are some good choices:
|
|
|
|
* Nginx_
|
|
* A stripped-down version of Apache_
|
|
|
|
If, however, you have no option but to serve media files on the same Apache
|
|
``VirtualHost`` as Django, you can set up Apache to serve some URLs as
|
|
static media, and others using the mod_wsgi interface to Django.
|
|
|
|
This example sets up Django at the site root, but serves ``robots.txt``,
|
|
``favicon.ico``, and anything in the ``/static/`` and ``/media/`` URL space as
|
|
a static file. All other URLs will be served using mod_wsgi:
|
|
|
|
.. code-block:: apache
|
|
|
|
Alias /robots.txt /path/to/mysite.com/static/robots.txt
|
|
Alias /favicon.ico /path/to/mysite.com/static/favicon.ico
|
|
|
|
Alias /media/ /path/to/mysite.com/media/
|
|
Alias /static/ /path/to/mysite.com/static/
|
|
|
|
<Directory /path/to/mysite.com/static>
|
|
Require all granted
|
|
</Directory>
|
|
|
|
<Directory /path/to/mysite.com/media>
|
|
Require all granted
|
|
</Directory>
|
|
|
|
WSGIScriptAlias / /path/to/mysite.com/mysite/wsgi.py
|
|
|
|
<Directory /path/to/mysite.com/mysite>
|
|
<Files wsgi.py>
|
|
Require all granted
|
|
</Files>
|
|
</Directory>
|
|
|
|
.. _Nginx: https://nginx.org/en/
|
|
.. _Apache: https://httpd.apache.org/
|
|
|
|
.. More details on configuring a mod_wsgi site to serve static files can be found
|
|
.. in the mod_wsgi documentation on `hosting static files`_.
|
|
|
|
.. _hosting static files: https://modwsgi.readthedocs.io/en/develop/user-guides/configuration-guidelines.html#hosting-of-static-files
|
|
|
|
.. _serving-the-admin-files:
|
|
|
|
Serving the admin files
|
|
=======================
|
|
|
|
When :mod:`django.contrib.staticfiles` is in :setting:`INSTALLED_APPS`, the
|
|
Django development server automatically serves the static files of the
|
|
admin app (and any other installed apps). This is however not the case when you
|
|
use any other server arrangement. You're responsible for setting up Apache, or
|
|
whichever web server you're using, to serve the admin files.
|
|
|
|
The admin files live in (:source:`django/contrib/admin/static/admin`) of the
|
|
Django distribution.
|
|
|
|
We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle the
|
|
admin files (along with a web server as outlined in the previous section; this
|
|
means using the :djadmin:`collectstatic` management command to collect the
|
|
static files in :setting:`STATIC_ROOT`, and then configuring your web server to
|
|
serve :setting:`STATIC_ROOT` at :setting:`STATIC_URL`), but here are three
|
|
other approaches:
|
|
|
|
1. Create a symbolic link to the admin static files from within your
|
|
document root (this may require ``+FollowSymLinks`` in your Apache
|
|
configuration).
|
|
|
|
2. Use an ``Alias`` directive, as demonstrated above, to alias the appropriate
|
|
URL (probably :setting:`STATIC_URL` + ``admin/``) to the actual location of
|
|
the admin files.
|
|
|
|
3. Copy the admin static files so that they live within your Apache
|
|
document root.
|
|
|
|
Authenticating against Django's user database from Apache
|
|
=========================================================
|
|
|
|
Django provides a handler to allow Apache to authenticate users directly
|
|
against Django's authentication backends. See the :doc:`mod_wsgi authentication
|
|
documentation </howto/deployment/wsgi/apache-auth>`.
|