Risorse di sistema e ottimizzazione

QuoteNode viene eseguito come un piccolo insieme di container Docker. I file Compose includono limiti di memoria e CPU ottimizzati per una VM da 4 GB di RAM, e ogni limite è sovrascrivibile con una variabile d’ambiente, così da dimensionare lo stack in base alla tua macchina.

Minimo e consigliato

Livello	RAM host	CPU host	Note
Minimo	4 GB	2 core	Profilo predefinito. Comodo per un piccolo team (≈10 utenti / ≈1 000 prodotti).
Consigliato	8 GB	4 core	Margine per import/export simultanei e picchi di generazione PDF.
Sotto carico	8–16 GB	4–8 core	≈100 utenti / ≈20 000 prodotti con operazioni di massa parallele.

Lo stack è leggero a riposo: a riposo l’intero stack usa circa 1,5 GiB di RAM indipendentemente da quanti dati ci sono nel database (non c’è cache delle entità nella JVM — i dati vivono in PostgreSQL). La RAM scala con la concorrenza delle operazioni di massa (import/export/PDF), non con il numero di utenti o record.

Come funzionano i limiti dei container

mem_limit è un tetto rigido, non una prenotazione. Un container usa solo ciò che tocca davvero, fino al limite; un container che supera il limite viene terminato per OOM. Un limite più alto non costa memoria — alza solo il confine di sicurezza.

Il profilo predefinito somma circa 3 520 MiB di tetti, che stanno su un host da 4 GB lasciando ~575 MiB al sistema operativo. Poiché l’uso reale a riposo è molto inferiore (~1,5 GiB), i tetti sono margine per i picchi di carico, non il consumo previsto.

cpus è anch’esso un tetto, ma la CPU è gratuita a riposo — un tetto CPU generoso non costa nulla a riposo e permette a un servizio di usare i core quando servono. Un valore cpus superiore al numero di core dell’host significa semplicemente «usare tutti i core disponibili», quindi i valori predefiniti sono sicuri su una VM da 1–2 core.

Limiti predefiniti per servizio (profilo 4 GB)

Servizio	Memoria	CPU	Ruolo
backend	1536m	4.0	Server API/web (l’heap JVM si dimensiona automaticamente al 70 % di questo)
postgres	512m	4.0	Database
backup-worker	832m	2.0	Backup pianificati (pg_dump)
gotenberg	448m	2.0	Rendering PDF con Chromium
frontend	96m	2.0	Caddy che serve la build statica
caddy	96m	2.0	Ingress TLS/reverse-proxy — aumenta CADDY_MEM_LIMIT con traffico TLS intenso

Regolare la RAM

Ogni limite è una variabile d’ambiente opzionale. Impostala nel tuo .env.prod per sovrascrivere il valore predefinito:

# Esempio: una macchina da 8 GB con più carico simultaneo
BACKEND_MEM_LIMIT=3g
POSTGRES_MEM_LIMIT=1g
GOTENBERG_MEM_LIMIT=768m

L’heap Java del backend si dimensiona automaticamente al 70 % di BACKEND_MEM_LIMIT (tramite MaxRAMPercentage), quindi alzare il limite alza l’heap automaticamente — nessun flag JVM da modificare. Lo stesso vale proporzionalmente per il backup-worker (che usa il 45 %).

Variabili disponibili: 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

Lascia generosi i valori CPU predefiniti. L’unico punto in cui la CPU conta davvero è l’avvio a freddo: il backend e il worker basati su JVM avviano un grande contesto applicativo, operazione CPU-bound. Su un singolo core un avvio a freddo può richiedere minuti; con 2+ core è ben sotto il minuto. Il periodo di tolleranza dell’healthcheck del worker tiene già conto degli avvii lenti, così una macchina limitata si riprende da sola, senza loop di riavvii.

Evitare problemi di memoria insufficiente

• Non ridurre WORKER_MEM_LIMIT sotto ~768m. Un backup (pg_dump + tar + gzip + la JVM) raggiunge un picco di circa 607 MiB; con meno margine può essere terminato a metà backup.
• Su una VM da 2 GB il profilo predefinito è troppo grande — abbassa i limiti (es. BACKEND_MEM_LIMIT=768m, POSTGRES_MEM_LIMIT=384m) in modo che la somma resti sotto la RAM fisica. L’heap del backend segue il limite automaticamente.
• Tieni d’occhio l’host, non solo i container. Se l’host esegue altri carichi, conta anche la loro memoria — Docker impone solo tetti per container, non l’uso totale dell’host.
• Un container che si riavvia ripetutamente con codice di uscita 137 indica un kill per OOM; aumenta il *_MEM_LIMIT di quel servizio.