# Documentation Django 5.2.8

# 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.