Serveur unifié ASGI avec Uvicorn

Dokos supporte désormais un mode de déploiement unifié utilisant ASGI (Asynchronous Server Gateway Interface) via Uvicorn, permettant d'exécuter le serveur web, les workers temps réel (Socket.IO) et les tâches en arrière-plan (RQ) dans un seul processus. Ce mode est particulièrement adapté aux petits sites ou aux environnements d'essai où l'optimisation de la mémoire est cruciale.

Avantages du mode unifié

• Réduction de la consommation mémoire : Un seul processus au lieu de plusieurs (Gunicorn + workers RQ + serveur Socket.IO).
• Simplification du déploiement : Moins de composants à configurer et surveiller.
• Performances optimisées : Préchargement des modules et importations paresseuses pour accélérer le démarrage.
• Rechargement automatique en développement : Le drapeau --dev permet de recharger le serveur à chaque modification de code Python.

Prérequis

• Dokos v16 ou supérieur
• Python 3.10+
• Uvicorn installé (pip install uvicorn)

Configuration de base

1. Activer le mode unifié

Pour démarrer Dokos en mode unifié, utilisez la commande suivante :

bench --site [votre_site] serve --unified

Cette commande lance un serveur Uvicorn qui gère :

• Le serveur web (WSGI)
• Le serveur temps réel (Socket.IO)
• Les workers RQ (tâches en arrière-plan)

2. Paramètres avancés

Exemple avec paramètres personnalisés :

bench --site [votre_site] serve --unified --web-threads 8 --job-threads 4 --dev

3. Configuration des variables d'environnement

Pour activer le service des assets statiques via ASGI, ajoutez cette variable dans votre fichier sites/common_site_config.json :

{
  "FRAPPE_SERVE_ASSETS": 1
}

Optimisations de performance

Importations paresseuses

Pour réduire l'empreinte mémoire, Dokos utilise désormais des importations paresseuses pour les modules non critiques. Voici les principaux modules concernés :

• PDF : pypdf, cssutils
• Excel : openpyxl, pandas
• Images : Pillow
• API Google : google-api-python-client
• Tests : werkzeug.test, unittest.mock
• Profiling : rq, profiler

Ces modules ne sont chargés qu'au moment de leur première utilisation, ce qui accélère le démarrage du serveur.

Préchargement des modules

Les modules critiques sont préchargés pour éviter les latences lors de la première requête. Vous pouvez configurer les modules à précharger dans sites/common_site_config.json :

{
  "preload_modules": [
    "frappe.core.doctype.user.user",
    "frappe.desk.doctype.notification.notification"
  ]
}

Cache client

Le cache client est désormais limité par taille en octets plutôt que par nombre d'entrées, évitant ainsi une consommation mémoire excessive.

Configuration du serveur temps réel

Authentification Socket.IO

Le secret d'authentification pour Socket.IO (socketio_auth_secret) est automatiquement généré s'il n'est pas présent dans Redis. Aucune configuration manuelle n'est nécessaire.

Désactivation de l'ancien backend

Le backend "python-embedded" pour Socket.IO a été supprimé. Toutes les connexions utilisent désormais le nouveau backend basé sur asyncio.

Exemple de déploiement pour un site d'essai

1. Installer Uvicorn :

   pip install uvicorn
   

2. Configurer le site :

   bench --site essai.dokos.local config set-common-config -c FRAPPE_SERVE_ASSETS 1
   

3. Démarrer le serveur :

   bench --site essai.dokos.local serve --unified --web-threads 4 --job-threads 2 --dev
   

4. Vérifier le fonctionnement :
   • Accédez à https://essai.dokos.local
   • Ouvrez la console du navigateur et vérifiez que les connexions Socket.IO sont établies (ws://essai.dokos.local/socket.io/)

Migration depuis Gunicorn

Si vous utilisiez précédemment Gunicorn, voici les étapes pour migrer vers le mode unifié :

1. Arrêter les services existants :

   bench stop
   

2. Désactiver Gunicorn (si utilisé comme serveur par défaut) :

   bench config set-common-config -c use_gunicorn 0
   

3. Mettre à jour la configuration Nginx/Apache :
   • Redirigez le trafic vers le port utilisé par Uvicorn (par défaut : 8000)
   • Exemple pour Nginx :

     location / {
         proxy_pass http://127.0.0.1:8000;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
     }
     

4. Redémarrer les services :

   bench start
   

Dépannage

Problème : Le serveur ne démarre pas

• Vérifiez les logs :

  tail -f sites/[votre_site]/logs/web.log
  

• Erreur Uvicorn introuvable : Installez Uvicorn (pip install uvicorn)
• Port déjà utilisé : Changez le port avec --port 8001

Problème : Les connexions Socket.IO échouent

• Vérifiez Redis : Assurez-vous que Redis est démarré et accessible
• Vérifiez le secret d'authentification :

  redis-cli get socketio_auth_secret
  

• Désactivez temporairement le cache : Ajoutez --no-cache à la commande de démarrage

Problème : Les tâches RQ ne s'exécutent pas

• Vérifiez les threads RQ : Augmentez --job-threads (ex: --job-threads 4)
• Vérifiez les logs RQ :

  tail -f sites/[votre_site]/logs/worker.log
  

Bonnes pratiques

1. Pour les sites de production :
   • Utilisez le mode unifié uniquement pour les petits sites ou les environnements d'essai.
   • Pour les sites à fort trafic, conservez une architecture séparée (Gunicorn + workers RQ dédiés).
2. Pour le développement :
   • Activez toujours --dev pour un rechargement automatique.
   • Limitez le nombre de threads (--web-threads 2 --job-threads 1) pour réduire la consommation mémoire.
3. Surveillance :
   • Utilisez htop ou glances pour surveiller la consommation mémoire.
   • Configurez des alertes pour les pics de mémoire (> 80% d'utilisation).

      
flowchart TD
    A[Démarrage du serveur] --> B[Chargement des modules critiques]
    B --> C[Préchargement des modules configurés]
    C --> D[Démarrage Uvicorn]
    D --> E[Serveur web ASGI]
    D --> F[Serveur Socket.IO]
    D --> G[Workers RQ]
    E --> H[Requêtes HTTP]
    F --> I[Connexions temps réel]
    G --> J[Tâches en arrière-plan]

    

Références

• Documentation officielle Uvicorn
• Guide ASGI
• Optimisation des performances avec Dokos