Configurer le serveur applicatif (Gunicorn) — 🔵 Confirmé¶

Gunicorn est le serveur qui exécute l’application Django en production. Il reçoit les requêtes HTTP (directement, ou via Nginx ou la plateforme d’hébergement), les confie à Django et renvoie les réponses.

Il est indispensable en production, où le serveur de développement de Django (runserver) ne doit pas être utilisé. Gunicorn permet notamment :

de servir plusieurs visiteurs en même temps, en répartissant les requêtes entre plusieurs processus ;
de garder le site disponible, en relançant automatiquement un processus qui plante ou ne répond plus.

Il ne rend pas le chargement d’une page plus rapide en soi, mais ses réglages déterminent combien de requêtes le site peut traiter à la fois : ils jouent donc sur la réactivité du site lorsqu’il reçoit beaucoup de visites, et sur la mémoire utilisée par le serveur.

Sites Conformes fournit une configuration prête à l’emploi : la plupart des instances n’ont rien à régler. Cette page explique son fonctionnement et comment l’adapter, notamment lorsque la mémoire du serveur est limitée.

Où se trouve la configuration¶

La configuration se trouve dans le fichier gunicorn.conf.py à la racine du dépôt. Gunicorn le charge automatiquement lorsqu’il est lancé depuis ce dossier, quel que soit le mode de déploiement : Procfile sur Scalingo, entrypoint.sh avec Docker, service systemd ou just run_gunicorn.

Les valeurs de ce fichier peuvent être modifiées par des variables d’environnement GUNICORN_* (voir Réglages), sans toucher au code.

Note

Les options passées en ligne de commande à Gunicorn sont prioritaires sur le fichier gunicorn.conf.py. Par exemple, l’exemple de service systemd de la page Sur un serveur Linux (VPS, dédié ou interne) — 🔵 Confirmé passe --workers 3 : cette valeur remplace alors GUNICORN_WORKERS. Ordre de priorité, du plus faible au plus fort :

gunicorn.conf.py (et donc les variables GUNICORN_* qu’il lit) ;
la variable GUNICORN_CMD_ARGS, si elle est définie ;
les options de la ligne de commande.

Fonctionnement¶

Gunicorn s’organise en deux niveaux :

                 Processus maître
       (surveille, ne traite aucune requête)
             │                       │
         Worker 1                Worker 2         ← processus indépendants,
    (copie de l’application)  (copie de l’application)   chacun sa mémoire
       │       │                 │       │
    thread  thread            thread  thread      ← requêtes traitées
                                                    en même temps

Le processus maître démarre les workers, les surveille et en relance un s’il plante ou ne répond plus.
Les workers sont des processus Python complets, qui contiennent chacun une copie de Django, de Wagtail et du code du site. Ce sont eux qui traitent les requêtes.
Les threads permettent à un worker de traiter plusieurs requêtes en même temps.

Le nombre de requêtes traitées simultanément est donc : nombre de workers × nombre de threads.

Astuce

En Python, un seul thread d’un processus exécute du code à un instant donné. Les threads n’accélèrent donc pas le calcul d’une page : ils sont utiles pendant les attentes (requêtes à la base de données, appels à un service externe), pendant lesquelles un autre thread peut avancer. Ils ne servent que si le site reçoit souvent plusieurs requêtes en même temps.

Chargement anticipé de l’application¶

La configuration active preload_app : le processus maître charge l’application une seule fois, puis crée les workers en se dupliquant. Les workers démarrent ainsi plus vite, ce qui accélère les déploiements et les redémarrages.

Au départ, les workers partagent la mémoire du processus maître. En Python, ce partage diminue au fil du temps, car le simple fait d’utiliser un objet le modifie en mémoire. Il faut donc compter qu’à terme, le processus maître et chaque worker occupent chacun une copie de l’application.

Réglages¶

Variable	Rôle	Défaut	Effet sur la mémoire
`GUNICORN_WORKERS`	Nombre de workers. À défaut, `WEB_CONCURRENCY` est utilisé (définie automatiquement par Scalingo).	`2`	Fort : chaque worker ajoute une copie complète de l’application.
`GUNICORN_THREADS`	Nombre de threads par worker, c’est-à-dire de requêtes qu’un worker traite en même temps.	`1`	Fort sous charge : chaque requête en cours occupe de la mémoire pendant la génération de la page.
`GUNICORN_TIMEOUT`	Délai (en secondes) au-delà duquel un worker qui ne répond plus est redémarré.	`120`	Aucun.
`GUNICORN_MAX_REQUESTS`	Nombre de requêtes traitées par un worker avant qu’il soit redémarré.	`10000`	Bénéfique : remet régulièrement la mémoire du worker à zéro.
`GUNICORN_MAX_REQUESTS_JITTER`	Aléa ajouté à `GUNICORN_MAX_REQUESTS`, pour que les workers ne redémarrent pas tous en même temps.	`2500`	Aucun.

Deux réglages sont fixés dans le code et ne dépendent d’aucune variable :

worker_class = "gthread" : workers capables d’utiliser des threads ;
preload_app = True : chargement anticipé de l’application (voir ci-dessus).

Mémoire et taille du serveur¶

La mémoire utilisée par Gunicorn dépend surtout du nombre de workers et du nombre de requêtes traitées en même temps :

mémoire ≈ processus maître
        + workers × (application + requêtes simultanées par worker × mémoire par requête)

La mémoire nécessaire varie selon la taille du site et le contenu des pages. À titre d’exemple, sur une instance de production hébergée sur un conteneur Scalingo de 1 Go, avec 2 workers :

Threads par worker	Requêtes simultanées	Mémoire constatée
4	8	environ 800 Mo, plus du swap : la limite était atteinte
2	4	environ 300 à 520 Mo selon le trafic, avec par moments un peu de swap
1	2	environ 450 Mo, sans swap

Avec 2 threads, la mémoire dépasse déjà par moments 512 Mo : ce réglage convient à un conteneur de 1 Go, mais pas à un conteneur de 512 Mo. C’est pourquoi la valeur par défaut de GUNICORN_THREADS est 1 : elle convient aussi aux petits conteneurs (512 Mo et moins).

Recommandations¶

Gardez les valeurs par défaut tant que le site fonctionne correctement.
Si la mémoire approche de la limite ou si le serveur utilise du swap, réduisez d’abord le nombre de workers, par exemple GUNICORN_WORKERS=1 sur un petit conteneur.
Si le site est lent sous forte affluence et que la mémoire le permet, augmentez progressivement GUNICORN_THREADS ou GUNICORN_WORKERS, puis surveillez la mémoire pendant quelques heures de trafic normal.
Après chaque changement, comparez la mémoire juste après le redémarrage et après une à deux heures de trafic : les threads n’occupent de mémoire que lorsque plusieurs requêtes arrivent en même temps.

Modifier un réglage¶

Sur Scalingo¶

Définissez la variable, puis redémarrez l’application : la modification d’une variable n’est prise en compte qu’au démarrage suivant.

Depuis le tableau de bord Scalingo, ajoutez ou modifiez la variable dans l’onglet « Environnement » de votre application (voir Sur Scalingo (ou PaaS) — 🟢 Débutant), puis redémarrez l’application depuis le tableau de bord.

En ligne de commande, l’équivalent est :

scalingo --app mon-site env-set GUNICORN_THREADS=1
scalingo --app mon-site restart

Pour revenir à la valeur par défaut :

scalingo --app mon-site env-unset GUNICORN_THREADS
scalingo --app mon-site restart

La mémoire de l’application se suit dans le tableau de bord, onglet « Metrics », graphique « Memory – web » (mémoire, swap et limite du conteneur).

Sur un serveur Linux ou avec Docker¶

Ajoutez la variable au fichier .env de l’instance :

GUNICORN_THREADS=1

Puis redémarrez l’application, par exemple sudo systemctl restart sites-conformes avec le service décrit dans Sur un serveur Linux (VPS, dédié ou interne) — 🔵 Confirmé.

Vérifiez aussi que la commande qui lance Gunicorn ne passe pas la même option en ligne de commande, qui serait prioritaire (voir Où se trouve la configuration).

Voir aussi¶

Référence des variables d’environnement, section « Serveur applicatif (Gunicorn) » ;
la documentation de Gunicorn pour la liste complète des réglages ;
la taille des conteneurs Scalingo.