Ressources système & réglages

QuoteNode s’exécute comme un petit ensemble de conteneurs Docker. Les fichiers Compose sont livrés avec des limites de mémoire réglées pour une VM de 4 Go de RAM, sans plafond CPU par défaut, et chaque limite peut être remplacée par une variable d’environnement, ce qui vous permet de dimensionner la pile selon votre machine.

Minimum et recommandé

Niveau	RAM hôte	CPU hôte	Notes
Minimum	4 Go	2 cœurs	Profil par défaut. Confortable pour une petite équipe (≈10 utilisateurs / ≈1 000 produits).
Recommandé	8 Go	4 cœurs	Marge pour les imports/exports simultanés et les pics de génération PDF.
Chargé	8–16 Go	4–8 cœurs	≈100 utilisateurs / ≈20 000 produits avec des opérations en masse parallèles.

La pile est sobre au repos : à l’arrêt, l’ensemble de la pile utilise environ 1,5 Gio de RAM quelle que soit la quantité de données en base (il n’y a pas de cache d’entités dans la JVM — les données vivent dans PostgreSQL). La RAM évolue avec la concurrence des opérations en masse (import/export/PDF), pas avec le nombre d’utilisateurs ou d’enregistrements.

Fonctionnement des limites de conteneurs

mem_limit est un plafond strict, pas une réservation. Un conteneur n’utilise que ce qu’il touche réellement, jusqu’à la limite ; un conteneur qui dépasse sa limite est tué par OOM. Une limite plus élevée ne coûte pas de mémoire — elle ne fait que relever la frontière de sécurité.

Le profil par défaut totalise environ 3 520 Mio de plafonds, ce qui tient sur un hôte de 4 Go en laissant ~575 Mio pour le système d’exploitation. Comme l’usage réel au repos est bien inférieur (~1,5 Gio), les plafonds sont une marge pour les pics de charge, pas la consommation attendue.

cpus est aussi un plafond, mais le CPU est gratuit au repos : aucun plafond CPU n’est donc défini par défaut, chaque service peut utiliser tous les cœurs de l’hôte et le CPU inactif ne coûte rien. Si vous définissez un plafond *_CPUS, ne dépassez pas le nombre de cœurs de l’hôte : Docker refuse de démarrer un conteneur dont le cpus dépasse les cœurs disponibles.

Limites par défaut par service (profil 4 Go)

Service	Mémoire	CPU	Rôle
backend	1536m	tous les cœurs	Serveur API/web (le heap JVM se dimensionne automatiquement à 70 % de cette valeur)
postgres	512m	tous les cœurs	Base de données
backup-worker	832m	tous les cœurs	Sauvegardes planifiées (pg_dump)
gotenberg	448m	tous les cœurs	Rendu PDF par Chromium
frontend	96m	tous les cœurs	Caddy servant le build statique
caddy	96m	tous les cœurs	Ingress TLS/reverse-proxy — augmentez CADDY_MEM_LIMIT en cas de fort trafic TLS

Ajuster la RAM

Chaque limite est une variable d’environnement optionnelle. Définissez-la là où votre installation conserve ses réglages :

• Paquet de version (serveur, LAN, laptop ou dossier sur un NAS) : le fichier .env à côté de docker-compose.yml ; exécutez ensuite docker compose up -d, qui recrée les conteneurs modifiés.
• Portainer : les variables d’environnement de la stack (stack.env) ; mettez ensuite la stack à jour.
• Coolify : son fichier Compose ne définit aucune limite par service, ces variables n’y ont donc aucun effet.

# Example: an 8 GB machine with more concurrent load
BACKEND_MEM_LIMIT=3g
POSTGRES_MEM_LIMIT=1g
GOTENBERG_MEM_LIMIT=768m

Le heap Java du backend se dimensionne automatiquement à 70 % de BACKEND_MEM_LIMIT (via MaxRAMPercentage), donc augmenter la limite augmente le heap automatiquement — aucun flag JVM à modifier. Il en va de même proportionnellement pour le backup-worker (qui utilise 45 %).

Variables disponibles : BACKEND_MEM_LIMIT, BACKEND_CPUS, POSTGRES_MEM_LIMIT, POSTGRES_CPUS, WORKER_MEM_LIMIT, WORKER_CPUS, GOTENBERG_MEM_LIMIT, GOTENBERG_CPUS, FRONTEND_MEM_LIMIT, FRONTEND_CPUS, CADDY_MEM_LIMIT, CADDY_CPUS.

CPU

Ne plafonnez le CPU que si une autre charge de l’hôte doit être protégée. Le seul moment où le CPU compte vraiment est le démarrage à froid : le backend et le worker basés sur la JVM démarrent un grand contexte applicatif, ce qui est limité par le CPU. Sur un seul cœur, un démarrage à froid peut prendre des minutes ; avec 2 cœurs ou plus, il est bien en dessous d’une minute. Le délai de grâce du healthcheck du worker tient déjà compte des démarrages lents, donc une machine contrainte se rétablit d’elle-même, sans boucle de redémarrage.

Éviter les problèmes de mémoire insuffisante

• Ne réduisez pas WORKER_MEM_LIMIT en dessous de ~768m. Une sauvegarde (pg_dump + tar + gzip + la JVM) atteint un pic d’environ 607 Mio ; avec moins de marge, elle peut être tuée en pleine sauvegarde.
• Sur une VM de 2 Go, le profil par défaut est trop grand — abaissez les limites (par ex. BACKEND_MEM_LIMIT=768m, POSTGRES_MEM_LIMIT=384m) pour que la somme reste sous la RAM physique. Le heap du backend suit la limite automatiquement.
• Surveillez l’hôte, pas seulement les conteneurs. Si l’hôte exécute d’autres charges, comptez aussi leur mémoire — Docker n’impose que des plafonds par conteneur, pas l’usage total de l’hôte.
• Un conteneur qui redémarre en boucle avec le code de sortie 137 indique un kill OOM ; augmentez le *_MEM_LIMIT de ce service.