Documentation – Until April 29, 2021, get PyCharm at 30% off. All money goes to the DSF!

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.

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.

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.

Basic configuration¶

Once you’ve got mod_wsgi installed and activated, edit your Apache server’s httpd.conf file and add the following.

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 virtual environment , 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 piece ensures that Apache can access your wsgi.py file.

Next we’ll need to ensure this wsgi.py with a WSGI application object exists. As of Django version 1.4, startproject will have created one for you; otherwise, you’ll need to create it. See the WSGI overview documentation for the default contents you should put in this file, and what else you can add to it.

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:

or by using mod_wsgi daemon mode and ensuring that each site runs in its own daemon process.

Fixing UnicodeEncodeError for file uploads

If you get a UnicodeEncodeError when uploading files with file names that contain non-ASCII characters, make sure Apache is configured to accept non-ASCII file names:

A common location to put this configuration is /etc/apache2/envvars .

See the Files section of the Unicode reference guide for details.

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:

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:

See the official mod_wsgi documentation for details on setting up daemon mode.

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:

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:

Serving the admin files¶

When django.contrib.staticfiles is in 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 ( django/contrib/admin/static/admin ) of the Django distribution.

We strongly recommend using django.contrib.staticfiles to handle the admin files (along with a Web server as outlined in the previous section; this means using the collectstatic management command to collect the static files in STATIC_ROOT , and then configuring your Web server to serve STATIC_ROOT at 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 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 mod_wsgi authentication documentation .

Документация Django 1.5.2

Развертывание Django с Apache и mod_wsgi это испытанный способ установки на “боевой” веб-сервер.

mod_wsgi является модулем веб-сервера Apache, который может взаимодействовать с любым приложением Python, в том числе Django. Django работает с любой версией Apache, поддерживающей mod_wsgi .

Официальная документация mod_wsgi просто фантастический документ; это ваш путеводитель по mod_wsgi. Возможно, вы захотите начать с документации по установке и конфигурированию.

Базовая конфигурация¶

После того как вы установите и активируете mod_wsgi отредактируйте файл httpd.conf веб-сервера Apache, изменив его следующим образом. Если вы используете Apache версии ниже чем 2.4, замените Require all granted` на Allow from all .

Значение WSGIScriptAlias указывает местоположение ваших приложений, ( / обозначает корневую директорию), вторым значением указывается расположение файла “WSGI” – см.ниже – в вашей системе, как правило, в корне проекта. (в примере это mysite ). Эти настройки позволят Apache обрабатывать любой запрос из директории, указанной как базовая с помощью WSGI-приложения, хранящегося в ней.

WSGIPythonPath гарантрует, что ваш проект доступен для импорта; иначе говоря, что команда import mysite сработает.

Значение просто предоставляет Apache доступ к файлу wsgi.py .

Далее следует удостовериться, что файл wsgi.py существует. Начиная с версии Django 1.4 команда startproject создаёт его; в противном случае вы можете создать этот файл самостоятельно. См. Развёртывание с WSGI, чтобы узнать изначальное содержимое файла и то, какие настройки вы можете добавить.

Если несколько сайтов на Django запащены в одном процессе mod_wsgi, они все будут использовать настройки сайта, который первый загрузился. Это можно исправить поправив « wsgi.py«(смотрите комментарий в файле), или используя mod_wsgi daemon mode при котором каждый сайт запущен в отдельном фоновом процессе.

Использование virtualenv¶

Если вы установили зависимости проекта с помощью virtualenv вам следует добавить путь к директории site-packages , находящейся в вашем виртуальном окружении. Для этого добавьте дополнительный путь к WSGIPythonPath , разделив его двоеточием:

Убедитесь в том, что путь к виртуальному окружению указан верно и замените python2.X на используемую вами версию Python (например, python2.7 ).

Использование mod_wsgi в режиме демона¶

“Режим демона” рекомендуемый режим для запуска mod_wsgi (но не на ОС Windows). Для создания требуемой группы процесса-демона и передачи управления Django вы должны добавить директивы WSGIDaemonProcess и WSGIProcessGroup . Еще одно важное дополнение: при использовании данной конфигурации в режиме демона вы не сможете работать с WSGIPythonPath ; вместо этого укажите сопцию python-path , чтобы использовать возможности WSGIDaemonProcess , к примеру:

Обратитесь к официальной документации mod_wsgi , чтобы узнать подробнее о настройке в режиме демона.

Обслуживание файлов¶

Django не должен обрабатывать файлы самостоятельно; эта задача передаётся любому выбранному вами веб-серверу.

Мы рекомендуем использовать отдельный веб-сервер – то есть тот, что идёт не в поставке с самим Django – для обслуживания медиа-файлов. Вот несколько неплохих вариантов:

Однако, если у вас нет возможности обслуживать медиа-файлы на том же виртуальном хосте ( VirtualHost ) что и Django, вы можете настроить Apache на обработку некоторых URL-запросов как статических и медиа-файлов, используя интерфейс mod_wsgi.

Это пример настройки Django в корне сайта, где явно указаны пути к robots.txt , favicon.ico , различным CSS-файлам, а также директориям /static/ и /media/ для их обработки как статических файлов. Все прочие URL-адреса будут обработаны при помощи mod_wsgi:

Обслуживание административных файлов¶

Заметьте, что сервер разработки Django автоматически обрабатывает административные приложения (и любые другие установленные приложения ), но это не годится для случая с другим сервером разработки. Вы сами несете ответственность за настройку Apache или любого другого сервера при использовании его для обслуживания административных файлов.

Административные файлы находятся по пути ( django/contrib/admin/static/admin ) в директории, где установлен Django.

Мы настоятельно рекомендуем использовать django.contrib.staticfiles для работы со статикой административного раздела (так же, как и в случае с веб-сервером, как это описано выше); это означает использование команды collectstatic для сбора статики в STATIC_ROOT , и настройку веб-сервера для обслуживания STATIC_ROOT в STATIC_URL ), но есть и несколько иных подходов:

Создание символьной ссылки на статические файлы, которые должны содержаться в корневом каталоге (для этого может потребоваться добавление +FollowSymLinks в конфигурации Apache).

Использование директивы Alias , как было показано выше, для создания псевдонима соответсвующего URL-адреса (вероятно это будет STATIC_URL + admin/ ), указывающего на фактическое расположение файлов.

Копирование директории с административной статикой в корень Apache.

Идентификация пользовательской базы данных с Apache¶

Django предоставляет возможность идентификации пользовательей средствами Apache см. mod_wsgi authentication documentation.

Если вы столкнулись с ошибкой UnicodeEncodeError ¶

Если вы воспользовались настройками стандартной интернационализации Django (см. Интернационализация и локализация) и позволили пользователям загружать файлы, то должны убедиться, что среда для запуска Apache настроена для обработки не ASCII символов.Если это не так, будет возбуждено исключение UnicodeEncodeError при вызове функций, подобных os.path() с именами файлов, содержащими отличные от ASCII символы.

Чтобы избежать проблем, среда, в которой запущен Apache, должна содержать параметры, аналогичные следующим:

Обратитесь к документации вашей операционной системы, чтобы подобрать соответствующий синтаксис и настроить расположение конфигурационных файлов; /etc/apache2/envvars является общей для Unix-like систем. После внесения соответствующих изменений перезапустите Apache.

Документация Django 1.9

Развертывание Django с Apache и mod_wsgi это испытанный способ установки на “боевой” веб-сервер.

mod_wsgi является модулем веб-сервера Apache, который может взаимодействовать с любым приложением Python, в том числе Django. Django работает с любой версией Apache, поддерживающей mod_wsgi .

Официальная документация mod_wsgi просто фантастический документ; это ваш путеводитель по mod_wsgi. Возможно, вы захотите начать с документации по установке и конфигурированию.

Базовая конфигурация¶

После того как вы установите и активируете mod_wsgi отредактируйте файл httpd.conf веб-сервера Apache, изменив его следующим образом. Если вы используете Apache версии ниже чем 2.4, замените Require all granted` на Allow from all и добавьте выше Order deny,allow .

Значение WSGIScriptAlias указывает местоположение ваших приложений, ( / обозначает корневую директорию), вторым значением указывается расположение файла “WSGI” – см.ниже – в вашей системе, как правило, в корне проекта. (в примере это mysite ). Эти настройки позволят Apache обрабатывать любой запрос из директории, указанной как базовая с помощью WSGI-приложения, хранящегося в ней.

WSGIPythonPath гарантирует, что ваш проект доступен для импорта; иначе говоря, что команда import mysite сработает.

Значение просто предоставляет Apache доступ к файлу wsgi.py .

Далее следует удостовериться, что файл wsgi.py существует. Начиная с версии Django 1.4 команда startproject создаёт его; в противном случае вы можете создать этот файл самостоятельно. См. Развёртывание с WSGI, чтобы узнать изначальное содержимое файла и то, какие настройки вы можете добавить.

Если несколько сайтов на Django запущены в одном процессе mod_wsgi, они все будут использовать настройки сайта, который первый загрузился. Это можно исправить, поменяв:

или используя mod_wsgi daemon mode при котором каждый сайт запущен в отдельном фоновом процессе.

Исправляем UnicodeEncodeError при загрузке файлов

Если вы получили UnicodeEncodeError при загрузке файлов, названия которых содержат не ASCII символы, убедитесь, что Apache настроен для загрузки таких файлов:

Настройки обычно находятся в /etc/apache2/envvars .

Подробности смотрите в разделе Файлы .

Использование virtualenv¶

Если вы установили зависимости проекта с помощью virtualenv, вам следует добавить в пути Python путь к директории site-packages , находящейся в вашем виртуальном окружении. Для этого добавьте дополнительный путь к WSGIPythonPath , разделив его двоеточием, если вы используете UNIX-системы, или точкой с запятой, если вы используете Windows. Если путь содержит пробелы, вся строка для WSGIPythonPath должна быть экранирована:

Убедитесь в том, что путь к виртуальному окружению указан верно и замените python3.X на используемую вами версию Python (например, python3.4 ).

Использование mod_wsgi в режиме демона¶

“Режим демона” рекомендуемый режим для запуска mod_wsgi (но не на ОС Windows). Для создания требуемой группы процесса-демона и передачи управления Django вы должны добавить директивы WSGIDaemonProcess и WSGIProcessGroup . Еще одно важное дополнение: при использовании данной конфигурации в режиме демона вы не сможете работать с WSGIPythonPath ; вместо этого укажите опцию python-path , чтобы использовать возможности WSGIDaemonProcess , к примеру:

Чтобы проект был доступен через подкаталог ( https://example.com/mysite в этом примере), вы можете указать в настройках WSGIScriptAlias :

Обратитесь к официальной документации mod_wsgi , чтобы узнать подробнее о настройке в режиме демона.

Обслуживание файлов¶

Django не должен обрабатывать файлы самостоятельно; эта задача передаётся любому выбранному вами веб-серверу.

Мы рекомендуем использовать отдельный веб-сервер – то есть тот, что идёт не в поставке с самим Django – для обслуживания медиа-файлов. Вот несколько неплохих вариантов:

Однако, если у вас нет возможности обслуживать медиа-файлы на том же виртуальном хосте ( VirtualHost ) что и Django, вы можете настроить Apache на обработку некоторых URL-запросов как статических и медиа-файлов, используя интерфейс mod_wsgi.

Это пример настройки Django в корне сайта, где явно указаны пути к robots.txt , favicon.ico , различным CSS-файлам, а также директориям /static/ и /media/ для их обработки как статических файлов. Все прочие URL-адреса будут обработаны при помощи mod_wsgi:

Если вы используете Apache старее чем 2.4, замените Require all granted на Allow from all и добавьте выше Order deny,allow .

Обслуживание административных файлов¶

Если добавить приложение django.contrib.staticfiles в INSTALLED_APPS , сервер разработки Django автоматически обрабатывает административные приложения (и любые другие установленные приложения ), но это не годится для случая с другим сервером разработки. Вы сами несете ответственность за настройку Apache или любого другого сервера при использовании его для обслуживания административных файлов.

Административные файлы находятся по пути ( django/contrib/admin/static/admin ) в директории, где установлен Django.

Мы настоятельно рекомендуем использовать django.contrib.staticfiles для работы со статикой административного раздела (так же, как и в случае с веб-сервером, как это описано выше); это означает использование команды collectstatic для сбора статики в STATIC_ROOT , и настройку веб-сервера для обслуживания STATIC_ROOT в STATIC_URL ), но есть и несколько иных подходов:

Создание символьной ссылки на статические файлы, которые должны содержаться в корневом каталоге (для этого может потребоваться добавление +FollowSymLinks в конфигурации Apache).

Использование директивы Alias , как было показано выше, для создания псевдонима соответствующего URL-адреса (вероятно это будет STATIC_URL + admin/ ), указывающего на фактическое расположение файлов.

Копирование директории с административной статикой в корень Apache.

Идентификация пользовательской базы данных с Apache¶

Django предоставляет возможность идентификации пользователей средствами Apache см. mod_wsgi authentication documentation.