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 et de CPU réglées pour une VM de 4 Go de RAM, 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 — un plafond CPU généreux ne coûte rien à l’arrêt et laisse un service utiliser des cœurs quand il en a besoin. Une valeur cpus supérieure au nombre de cœurs de l’hôte signifie simplement « utiliser tous les cœurs disponibles », donc les valeurs par défaut sont sûres sur une VM de 1–2 cœurs.

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

Service	Mémoire	CPU	Rôle
backend	1536m	4.0	Serveur API/web (le heap JVM se dimensionne automatiquement à 70 % de cette valeur)
postgres	512m	4.0	Base de données
backup-worker	832m	2.0	Sauvegardes planifiées (pg_dump)
gotenberg	448m	2.0	Rendu PDF par Chromium
frontend	96m	2.0	Caddy servant le build statique
caddy	96m	2.0	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 dans votre .env.prod pour remplacer la valeur par défaut :

# Exemple : une machine de 8 Go avec plus de charge simultanée
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

Laissez les valeurs CPU par défaut généreuses. 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.