Gunicorn : Définition et Guide Complet

Qu'est-ce que Gunicorn ?

Gunicorn, abréviation de « Green Unicorn », est un serveur d'application WSGI (Web Server Gateway Interface) pour Python. Créé en 2010 et inspiré du serveur Unicorn de Ruby, il fait le lien entre le serveur web (Nginx) et votre application Python (Django, Flask, FastAPI). Son rôle est de recevoir les requêtes HTTP transmises par le reverse proxy, de les faire traiter par votre code Python, et de renvoyer les réponses.

WSGI est la spécification standard qui définit comment un serveur web communique avec une application Python. Quand vous développez avec Django, le serveur de développement intégré (manage.py runserver) est parfait pour le développement local, mais il n'est absolument pas conçu pour la production : il est mono-thread, ne gère pas la concurrence, et n'offre aucune des garanties de fiabilité nécessaires. Gunicorn remplace ce serveur de développement en production.

L'architecture pré-fork de Gunicorn signifie qu'un processus master crée à l'avance plusieurs processus workers, chacun capable de traiter une requête indépendamment. Ce modèle offre un excellent compromis entre performance et simplicité. Contrairement aux serveurs asynchrones plus complexes, Gunicorn est extrêmement simple à configurer et à maintenir tout en offrant des performances largement suffisantes pour la majorité des applications web.

Pourquoi Gunicorn est important

Gunicorn est le maillon indispensable entre votre infrastructure web (Nginx, Linux) et votre code applicatif (Django). Son importance tient à plusieurs facteurs critiques pour la production.

• Fiabilité en production : Gunicorn est battle-tested depuis plus de 14 ans. Il gère correctement les signaux UNIX, le redémarrage graceful des workers, et la supervision des processus enfants. Si un worker plante à cause d'un bug applicatif, le master le redémarre automatiquement sans impact sur les autres requêtes.
• Gestion de la concurrence : grâce à ses workers multiples, Gunicorn peut traiter plusieurs requêtes simultanément. Le nombre de workers est configurable et s'ajuste en fonction des ressources du serveur (règle empirique : 2 * nombre de CPU + 1).
• Simplicité de configuration : Gunicorn se lance avec une seule commande et quelques paramètres. Cette simplicité réduit les risques d'erreur de configuration et facilite le debugging.
• Compatibilité universelle : tout framework Python implémentant WSGI fonctionne avec Gunicorn : Django, Flask, Pyramid, Falcon. C'est un choix qui ne vous enferme dans aucun framework.
• Intégration naturelle avec Nginx : Gunicorn et Nginx forment un tandem éprouvé. Nginx gère ce qu'il fait de mieux (fichiers statiques, SSL, compression) tandis que Gunicorn se concentre sur l'exécution du code Python.

Comment ça fonctionne

Au démarrage, le processus master de Gunicorn charge la configuration, se lie à un socket (Unix ou TCP), puis crée le nombre de workers configuré via fork(). Chaque worker est un processus indépendant qui hérite du socket du master et entre dans une boucle d'écoute des requêtes.

Lorsqu'une requête HTTP arrive (transmise par Nginx), un worker disponible la prend en charge. Il traduit la requête HTTP brute en un dictionnaire WSGI environ — un ensemble standardisé de variables décrivant la requête — puis appelle le callable WSGI de votre application Django. Django traite la requête à travers ses middlewares, ses vues et ses templates, puis renvoie un objet response. Gunicorn traduit cette response en HTTP et la renvoie à Nginx.

Le processus master surveille en permanence l'état des workers. Si un worker dépasse le timeout configuré (par défaut 30 secondes), le master le tue et en crée un nouveau. Si un worker crash, il est automatiquement remplacé. Ce mécanisme de supervision assure la résilience du système : même en cas de bug applicatif provoquant un crash, seule une requête est impactée et le service reste disponible.

Gunicorn propose plusieurs types de workers. Les workers « sync » (par défaut) traitent une requête à la fois de manière synchrone — c'est le choix le plus simple et le plus adapté aux applications Django classiques. Les workers « gthread » ajoutent du multi-threading pour gérer davantage de connexions par worker. Les workers « gevent » ou « eventlet » utilisent des green threads pour une gestion asynchrone des I/O, utile pour les applications avec beaucoup d'attentes réseau.

Exemple concret

Chez Kern-IT, Gunicorn est au cœur de notre stack de déploiement Django. Pour ce site Wagtail, notre configuration Gunicorn type utilise des workers sync avec un timeout de 30 secondes, un bind sur un socket Unix pour la communication avec Nginx, et un nombre de workers adapté aux ressources du serveur.

Notre processus de déploiement via Fabric illustre parfaitement l'intégration de Gunicorn dans la chaîne. Lors d'un déploiement, Fabric se connecte au serveur Linux en SSH, met à jour le code via git pull, installe les dépendances dans l'environnement pyenv, exécute les migrations Django, puis redémarre Gunicorn via Supervisor avec un signal graceful (SIGHUP). Ce signal indique à Gunicorn de terminer les requêtes en cours avant de recharger les workers avec le nouveau code, assurant un déploiement sans interruption de service.

Mise en œuvre

1. Installer Gunicorn : ajouter gunicorn aux dépendances du projet (pip install gunicorn) et vérifier que votre application Django expose bien un callable WSGI (dans wsgi.py).
2. Configurer le nombre de workers : appliquer la formule 2 * CPU + 1 comme point de départ. Pour un serveur 2 cœurs, 5 workers. Ajuster ensuite selon les métriques de charge réelles.
3. Choisir le bind : utiliser un socket Unix (--bind unix:/run/gunicorn.sock) plutôt qu'un port TCP pour la communication avec Nginx sur le même serveur, c'est plus performant et plus sécurisé.
4. Configurer le timeout : 30 secondes par défaut est un bon point de départ. Augmenter si votre application a des vues légitimement longues (génération de PDF, exports).
5. Superviser avec Supervisor : créer un fichier de configuration Supervisor pour que Gunicorn redémarre automatiquement en cas de crash ou de redémarrage du serveur.
6. Configurer les logs : diriger les logs d'accès et d'erreur vers des fichiers dédiés pour faciliter le debugging et le monitoring.

Technologies et outils associés

• Nginx : reverse proxy qui travaille en tandem avec Gunicorn pour servir les applications Django.
• Django : framework web Python le plus populaire, dont Gunicorn est le serveur d'application de référence.
• Supervisor : gestionnaire de processus pour maintenir Gunicorn en fonctionnement permanent.
• Fabric : outil de déploiement SSH qui automatise le redémarrage graceful de Gunicorn.
• uWSGI : alternative à Gunicorn, plus riche en fonctionnalités mais plus complexe à configurer.
• Uvicorn : serveur ASGI pour les applications Python asynchrones (FastAPI, Django Channels).

Conclusion

Gunicorn est le serveur d'application WSGI de référence pour le déploiement d'applications Django en production. Sa simplicité de configuration, sa fiabilité éprouvée et son intégration naturelle avec Nginx en font un choix évident pour la majorité des projets web Python. Chez Kern-IT, le tandem Nginx/Gunicorn est le standard de déploiement pour toutes nos applications Django et Wagtail. Cette combinaison, orchestrée par Supervisor et déployée via Fabric sur des serveurs Linux, constitue une stack de production éprouvée, performante et facile à maintenir.