Django avec Apache et mod_wsgi

Le déploiement de Django avec Apache et mod_wsgi est une manière éprouvée de mettre Django en production.

mod_wsgi est un module Apache qui peut héberger n’importe quelle application WSGI Python, y compris Django. Django fonctionne avec toute version d’Apache qui prend en charge mod_wsgi.

La documentation officielle de mod_wsgi représente la source ultime pour tout détail sur la manière d’utiliser mod_wsgi. Le point de départ le plus pertinent est la documentation d’installation et de configuration.

Configuration de base

Après avoir installé et activé mod_wsgi, modifiez le fichier httpd.conf du serveur Apache et ajoutez ce qui suit.

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>

Le premier élément de la ligne WSGIScriptAlias est l’URL de base à laquelle vous souhaitez servir votre application (/ indique l’URL racine) ; le second élément est l’emplacement d’un « fichier WSGI » (voir ci-dessous) de votre système, en principe à l’intérieur de votre paquet de projet (mysite dans cet exemple). Cela indique à Apache qu’il doit servir toute requête au-dessous de l’URL donnée en utilisant l’application WSGI définie dans ce fichier.

Si vous installez les dépendances Python de votre projet dans un environnement virtuel, ajoutez le chemin dans WSGIPythonHome. Consultez le guide d’environnement virtuel mod_wsgi pour plus de détails.

La ligne WSGIPythonPath permet d’assurer que le paquet de votre projet soit disponible à l’importation dans le chemin Python ; en d’autres termes, pour que import mysite fonctionne.

L’élément <Directory> garantit qu’Apache a accès à votre fichier wsgi.py.

Ensuite, il faut s’assurer que ce fichier wsgi.py contenant l’application WSGI existe bel et bien. À partir de la version 1.4 de Django, startproject en crée un pour vous ; sinon, vous devrez le créer vous-même. Consultez la documentation générale de WSGI pour connaître le contenu par défaut à placer dans ce fichier ainsi que les éléments optionnels.

Avertissement

Si plusieurs sites Django sont exécutés dans un seul processus mod_wsgi, ils vont tous utiliser les réglages de celui qui est lancé en premier. Cela peut être corrigé en changeant :

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings")

dans wsgi.py, en :

os.environ["DJANGO_SETTINGS_MODULE"] = "{{ project_name }}.settings"

ou en utilisant le mode daemon de mod_wsgi et en prenant soin de faire tourner chaque site dans son propre processus daemon.

Résolution des erreurs UnicodeEncodeError pour les envois de fichiers

Si vous obtenez des erreurs UnicodeEncodeError lors de l’envoi ou de l’écriture de fichiers contenant des caractères non ASCII dans leur titre ou leur contenu, vérifiez que Apache est configuré pour prendre en charge le codage UTF-8 :

export LANG='en_US.UTF-8'
export LC_ALL='en_US.UTF-8'

Cette configuration se trouve habituellement dans /etc/apache2/envvars.

Il est aussi possible, dans le cas où le mode service mod_wsgi est utilisé, d’ajouter les options lang et locale à la directive WSGIDaemonProcess:

WSGIDaemonProcess example.com lang='en_US.UTF-8' locale='en_US.UTF-8'

Consultez la section Fichiers du guide de référence Unicode pour plus de détails.

Utilisation du mode daemon de mod_wsgi

Le « mode daemon » est le mode recommandé pour le fonctionnement de mod_wsgi (sur les plates-formes non Windows). Pour créer le groupe de processus daemon nécessaire et y installer l’instance Django, vous devez ajouter les directives WSGIDaemonProcess et WSGIProcessGroup appropriées. Une autre modification nécessaire à la configuration ci-dessus si vous utilisez le mode daemon est due à ce qu’il n’est pas possible d’utiliser WSGIPythonPath ; vous devez la remplacer par l’option python-path de WSGIDaemonProcess, par exemple :

WSGIDaemonProcess example.com python-home=/path/to/venv python-path=/path/to/mysite.com
WSGIProcessGroup example.com

Si vous voulez que votre projet soit dans un sous-répertoire (https://example.com/mysite dans cet exemple), vous pouvez ajouter WSGIScriptAlias à la configuration ci-dessus:

WSGIScriptAlias /mysite /path/to/mysite.com/mysite/wsgi.py process-group=example.com

Consultez la documentation officielle de mod_wsgi pour plus de détails sur la configuration du mode daemon.

Service de fichiers

Django ne sert pas lui-même des fichiers ; il délègue ce travail au serveur Web de votre choix.

Nous recommandons l’utilisation d’un serveur Web dédié (donc pas celui qui fait aussi tourner Django) pour servir des fichiers statiques. Voici quelques bons choix :

• Nginx
• Une version allégée d”Apache

Si toutefois vous n’avez pas d’autre choix que de servir les fichiers statiques dans le même VirtualHost Apache que Django, vous pouvez configurer Apache pour qu’il réserve certaines URL au service de fichiers statiques, tout en gardant le reste pour l’interface mod_wsgi de Django.

Cet exemple définit Django comme site racine, mais sert robots.txt, favicon.ico et toutes les URL commençant pas /static/ et /media/ comme fichiers statiques. Toutes les autres URL sont servies par mod_wsgi :

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>

Service des fichiers de l’interface d’administration

Lorsque django.contrib.staticfiles figure dans INSTALLED_APPS, le serveur de développement de Django sert automatiquement les fichiers statiques de l’application d’administration (et de toute autre application installée). Mais ce n’est plus le cas dès que vous utilisez une autre configuration de serveur. C’est vous qui êtes responsable de la configuration d’Apache ou de tout autre serveur Web qui vous convient afin de servir les fichiers de l’application d’administration.

Les fichiers statiques de l’administration se trouvent dans la distribution de Django (django/contrib/admin/static/admin).

Nous recommandons chaudement d’utiliser django.contrib.staticfiles pour gérer les fichiers de l’administration (en compagnie d’un serveur Web comme indiqué dans la précédente section ; cela implique l’utilisation de la commande de gestion collectstatic afin de rassembler les fichiers statiques dans STATIC_ROOT, puis de configurer le serveur Web pour servir STATIC_ROOT à l’URL STATIC_URL), mais voici trois autres approches possibles :

1. Créer un lien symbolique vers les fichiers statiques de l’administration dans votre racine de documents (ce qui peut nécessiter l’ajout de +FollowSymLinks dans votre configuration Apache).
2. Utilisez une directive Alias, comme démontré ci-dessus, pour associer l’URL appropriée (probablement STATIC_URL + admin/) à l’emplacement réel des fichiers de l’interface d’administration.
3. Copier les fichiers statiques de l’administration pour les placer dans la racine des documents Apache.

Authentification sur la base de données des utilisateurs de Django depuis Apache

Django met à disposition un gestionnaire pour permettre à Apache d’authentifier les utilisateurs directement avec les moteurs d’authentification de Django. Consultez la documentation d’authentification mod_wsgi.