Riferimento variabili d’ambiente

Questa pagina consolida le variabili d’ambiente attualmente usate dal progetto QuoteNode. Le fonti principali di verità restano i template del repository applicativo (infra/.env.prod.example, infra/.env.dev.example, infra/.env.dev-sid, infra/docker-compose.*.yml).

Come leggere questo riferimento

• Prod indica una variabile da usare nel .env di produzione
• Dev indica sviluppo locale o stack demo
• Compose indica cablaggio lato host Docker Compose, non l’applicazione in sé
• default vuoti significano in genere “imposta esplicitamente se ti serve questa funzionalità”

Variabili di Compose e stack locale

Variabile	Ambito	Scopo	Valore tipico
COMPOSE_PROJECT_NAME	Dev / Compose	Evita collisioni di nomi tra più stack locali.	quotenode-dev, quotenode-dev-sid
POSTGRES_PORT	Dev / Compose	Porta host mappata su PostgreSQL.	5433, 5434
PG_JIT	Dev / Compose	Compilazione JIT di PostgreSQL. Disattivata per impostazione predefinita — raramente utile per questo carico OLTP. Imposta on per attivarla.	off
MAILPIT_PORT	Dev / Compose	Porta host per la UI di Mailpit.	8025, 8026
BACKEND_PORT	Dev / Compose	Porta host per l’API backend.	8091, 8092
FRONTEND_PORT	Dev / Compose	Porta host per il frontend.	5174, 5175
VITE_PUBLIC_API_BASE	Dev / Frontend	URL base dell’API visibile dal browser negli stack locali.	http://localhost:8091, http://localhost:8092
APP_VERSION	Prod / Dev / Compose	Tag dell’immagine Docker selezionato da Compose.	latest, v1.0.0
APP_CHANNEL	Prod / Dev / Compose	Canale di release incluso nei metadati di build e nelle label della UI.	alpha, stable
VITE_RELEASE_CHECK_ENABLED	Prod / Dev / Frontend	Abilita la verifica di disponibilità delle release upstream (solo admin).	true, false
VITE_RELEASE_MANIFEST_URL	Prod / Dev / Frontend	URL del manifest JSON pubblico usato per la verifica delle release.	https://quotenode.dev/releases/latest.json
PROXY_MODE	Prod / Dev / Compose	Sceglie se Caddy gira nello stack (internal) o se si usa un reverse proxy esterno (external).	internal, external
DOMAIN	Prod / Compose	Dominio pubblico usato da Caddy e dagli URL pubblici in modalità proxy interno.	quotenode.example.com
SECURITY_TRUSTED_PROXIES	Prod / Dev / Compose	Di norma vuoto — l’IP del client viene rilevato automaticamente dietro proxy interni (intervalli privati/loopback) e CDN come Cloudflare (tramite CF-Connecting-IP). Le intestazioni di inoltro da un peer diretto (non interno) vengono ignorate. Impostalo solo per un proxy insolito il cui peer di trasporto è un indirizzo pubblico.	vuoto, 203.0.113.5/32

Database e runtime principale

Variabile	Ambito	Scopo	Valore tipico
DB_URL	Prod / Dev	Stringa di connessione JDBC per PostgreSQL.	jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME	Prod / Dev	Utente del database.	quotenode, app
DB_PASSWORD	Prod / Dev	Password del database.	32+ caratteri casuali in prod
DB_NAME	Prod / Dev / Compose	Nome del database usato da app e Compose.	quotenode, app
DB_AUTO_MIGRATE	Prod / Dev	Migrazione automatica della versione maggiore di PostgreSQL all’avvio (usata da stack-up.sh). Disattivata per impostazione predefinita; se true, un volume dati più vecchio viene salvato e migrato prima dell’avvio dello stack.	false
SPRING_PROFILES_ACTIVE	Prod / Dev	Attiva il profilo Spring.	prod, dev
CORS_ALLOWED_ORIGINS	Prod / Dev	Origini browser consentite per l’API. Evita * in produzione.	https://tuodominio.com
LOG_LEVEL	Prod / Dev	Verbosità base dei log applicativi.	ERROR, INFO, DEBUG

Rotazione log Docker e diagnostica di supporto

Variabile	Ambito	Scopo	Valore tipico
DOCKER_LOG_MAX_SIZE	Prod / Compose	Dimensione massima di un singolo file di log prima della rotazione.	10m
DOCKER_LOG_MAX_FILE	Prod / Compose	Numero di file di log ruotati da conservare.	5
SUPPORT_LOGS_BUFFER_SIZE	Prod	Dimensione del buffer di anteprima dei log in-app.	4000
SUPPORT_LOGS_PREVIEW_RATE_LIMIT_PER_MINUTE	Prod	Rate limit per le richieste di anteprima log.	30
SUPPORT_LOGS_LOG_LEVEL_DEFAULT_TTL_MINUTES	Prod	Timeout di auto-ripristino per i cambi temporanei di log level.	15
SUPPORT_LOGS_LOG_LEVEL_MAX_TTL_MINUTES	Prod	Finestra massima consentita di escalation temporanea del log level.	30
SUPPORT_LOGS_LOG_LEVEL_ALLOWED_SCOPES	Prod	Scope di pacchetto elevabili temporaneamente per diagnostica.	dev.quotenode,...

Sicurezza di autenticazione e sessione

Variabile	Ambito	Scopo	Valore tipico
DB_ENCRYPTION_KEY	Prod / Dev	Chiave principale di cifratura applicativa per i dati sensibili.	64 caratteri hex in prod
TIMING_TOKEN_SECRET	Prod / Dev	Segreto HMAC per la protezione anti-bot basata su timing-token.	32+ caratteri casuali
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Prod / Dev	Segreto di sessione per i link offerta pubblici protetti da password.	32+ caratteri casuali
AUTH_PASSWORD_MIN_LENGTH	Prod / Dev	Lunghezza minima della password.	12 in prod, 8 in dev
AUTH_PASSWORD_COMPLEXITY_LEVEL	Prod / Dev	Livello di complessità password imposto dalla policy.	2 in prod, 1 in dev
AUTH_SESSION_IDLE_TIMEOUT_MIN	Prod / Dev	Timeout per inattività delle sessioni autenticate.	30, 480
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H	Prod / Dev	Durata massima assoluta della sessione.	12, 24
SECURITY_MAX_FAILED_LOGINS_SOFT	Prod / Dev	Soglia di login falliti per avviso soft.	5, 10
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK	Prod / Dev	Soglia di login falliti per blocco temporaneo.	10, 20
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK	Prod / Dev	Soglia di login falliti per blocco forte.	20, 50
SECURITY_TEMP_LOCK_MINUTES	Prod / Dev	Durata del blocco temporaneo.	30, 5
FEATURE_2FA_ENABLED	Prod / Dev	Interruttore master dei flussi di autenticazione a due fattori.	true, false
SECURITY_REQUIRE_2FA_ROLES	Prod / Dev	Ruoli che devono attivare la 2FA.	ADMIN
SECURITY_BOT_DETECTION_ENABLED	Prod / Dev	Abilita il layer di bot detection.	true, false
SECURITY_BOT_SCORE_WARN_THRESHOLD	Prod / Dev	Soglia di bot score per la sola segnalazione.	30
SECURITY_BOT_SCORE_BLOCK_THRESHOLD	Prod / Dev	Soglia di bot score per il blocco.	70
SECURITY_IP_WHITELIST	Prod / Dev	Whitelist IP imposta dall’operatore (IP/CIDR letterali separati da virgole). Quando è attiva, la whitelist protegge l’intera superficie di amministrazione — accesso, la sfida 2FA e ogni rotta amministrativa autenticata — lasciando raggiungibili solo gli endpoint di salute/infrastruttura e quelli pubblici per i clienti. Quando impostata, prevale sulla whitelist del tenant nell’app ed è di sola lettura nell’interfaccia; una lista dell’operatore viene applicata all’avvio senza rollback automatico, quindi verifica che il tuo indirizzo sia incluso. Vuoto = si applica l’impostazione del tenant (se presente). Risolve i client tramite SECURITY_TRUSTED_PROXIES.	vuoto, 203.0.113.10,198.51.100.0/24
SECURITY_IP_WHITELIST_FORCE_DISABLE	Runtime override	Override di emergenza che disabilita l’applicazione della whitelist IP memorizzata (verificato prima di qualsiasi analisi della lista, quindi ripristina anche da una lista memorizzata non valida — e, poiché la whitelist ora protegge l’accesso, ripristina la possibilità di accedere). Riavvio richiesto; solo ENV, mai dall’interfaccia. Disabilita solo la whitelist IP — non GeoIP, rilevamento bot o rate limiting.	false
SECURITY_IP_WHITELIST_CONFIRMATION_WINDOW_SECONDS	Prod / Dev	Per quanto tempo un’attivazione/restringimento della whitelist nell’app resta in attesa di riconferma prima di tornare automaticamente alla lista precedente (sicurezza anti-blocco). La sessione che modifica conferma automaticamente quando il suo indirizzo attuale è incluso.	120

CRM, file, import e media prodotto

Variabile	Ambito	Scopo	Valore tipico
CRM_DEDUP_NAME_SIMILARITY_THRESHOLD	Prod / Dev	Soglia di similarità pg_trgm per gli avvisi di azienda duplicata.	0.8
CRM_DEDUP_EMAIL_DOMAIN_WARN	Prod / Dev	Avvisa quando i domini email business coincidono con record esistenti.	true
CRM_ATTACHMENT_MAX_SIZE_MB	Prod / Dev	Dimensione massima degli allegati CRM.	25, 10
CRM_ATTACHMENT_ALLOWED_TYPES	Prod / Dev	Estensioni consentite per gli allegati CRM.	pdf,doc,docx,...
CSV_IMPORT_MAX_ROWS	Prod / Dev	Limite di righe per gli import CSV (CRM).	5000
APP_PRODUCT_IMPORT_MAX_ROWS	Prod / Dev	Limite di righe per gli import di prodotti (CSV/XLSX).	50000
STORAGE_PATH	Prod / Dev	Directory radice per i file caricati.	/data/uploads, ./data/uploads
PIM_MEDIA_MAX_SIZE_MB	Prod / Dev	Dimensione massima di una singola immagine prodotto.	3, 5
PIM_MEDIA_MAX_PER_PRODUCT	Prod / Dev	Numero massimo di media per prodotto.	5, 10
PIM_MEDIA_THUMBNAIL_WIDTH	Prod / Dev	Larghezza della miniatura usata nell’elaborazione immagini.	300
PIM_MEDIA_ALLOWED_TYPES	Prod / Dev	Estensioni consentite per i media prodotto.	jpg,jpeg,png,webp,svg
PIM_MEDIA_MAX_MEGAPIXELS	Prod / Dev	Rifiuta immagini le cui dimensioni in pixel superano questi megapixel, verificato dall’header prima di qualsiasi decodifica completa (protezione memoria contro decompression bomb).	40
PIM_MEDIA_OPTIMIZE_ENABLED	Prod / Dev	Ridimensiona e ri-codifica l’originale memorizzato all’upload. Imposta false per mantenere gli originali invariati.	true
PIM_MEDIA_OPTIMIZE_MAX_DIMENSION	Prod / Dev	Limite del lato lungo in pixel per l’originale memorizzato quando l’ottimizzazione è attiva (le offerte usano comunque una miniatura da 300px).	2560
PIM_MEDIA_OPTIMIZE_QUALITY	Prod / Dev	Qualità di ri-codifica JPEG (0.0–1.0) applicata nell’ottimizzazione immagini.	0.85
IMPORT_ZIP_MAX_SIZE_MB	Prod / Dev	Dimensione massima dello ZIP per l’import immagini in batch.	100
IMPORT_ZIP_MAX_IMAGES	Prod / Dev	Numero massimo di immagini dentro un import ZIP.	1000
IMPORT_IMAGE_MAX_SIZE_MB	Prod / Dev	Dimensione massima di una singola immagine dentro i batch ZIP.	5
IMPORT_IMAGE_FUZZY_THRESHOLD	Prod / Dev	Soglia per il matching fuzzy nome-file→prodotto.	0.82
MULTIPART_MAX_FILE_SIZE	Prod / Dev	Tetto globale per qualsiasi singolo file caricato (busta di upload; i limiti per-funzione sopra sono applicati separatamente e più stringenti). Dimensionato per il più grande upload legittimo, un archivio ZIP di immagini.	200MB
MULTIPART_MAX_REQUEST_SIZE	Prod / Dev	Tetto globale per un’intera richiesta multipart, es. upload multi-file.	220MB
MULTIPART_FILE_SIZE_THRESHOLD	Prod / Dev	Gli upload più grandi di questa soglia vengono scritti su file temporaneo invece che in memoria, tenendo i grandi upload fuori dall’heap JVM.	2MB

Spedizione, FX e default offerta

Variabile	Ambito	Scopo	Valore tipico
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR	Prod / Dev	Divisore peso volumetrico usato dai calcoli di spedizione.	4000
SHIPPING_OVERRIDE_REQUIRES_REASON	Prod / Dev	Richiede una motivazione quando il costo di spedizione viene forzato manualmente.	true
FX_PROVIDER	Prod / Dev	Fonte dei tassi di cambio.	NBP, MOCK, ECB, CUSTOM
FX_PROVIDER_URL	Prod / Dev	URL custom del provider FX.	vuoto salvo CUSTOM
FX_REFRESH_INTERVAL_MIN	Prod / Dev	Cadenza di refresh automatico dei tassi.	60, 0
FX_DEFAULT_MARGIN_PERCENT	Prod / Dev	Margine percentuale di default applicato sui tassi del provider.	0
FX_DEVIATION_WARN_PERCENT	Prod / Dev	Soglia di avviso per tassi FX modificati manualmente.	3
FX_DEVIATION_BLOCK_PERCENT	Prod / Dev	Soglia di blocco per tassi FX modificati manualmente.	8
OFFER_NUMBER_PREFIX	Prod / Dev	Prefisso usato nella numerazione delle offerte.	OF

Email, link pubblici e notifiche

Variabile	Ambito	Scopo	Valore tipico
SMTP_HOST	Prod / Dev	Hostname SMTP per invio offerte e notifiche.	hostname del provider, localhost
SMTP_PORT	Prod / Dev	Porta SMTP.	587, 1025, 1026
SMTP_USERNAME	Prod / Dev	Username di autenticazione SMTP.	account del provider
SMTP_PASSWORD	Prod / Dev	Password di autenticazione SMTP.	segreto del provider
SMTP_AUTH	Prod / Dev	Abilita l’autenticazione SMTP.	true, false
SMTP_STARTTLS	Prod / Dev	Abilita la negoziazione STARTTLS.	true, false
PUBLIC_LINK_TOKEN_BYTES	Prod / Dev	Entropia usata per i token dei link pubblici generati.	32
PUBLIC_LINK_DEFAULT_EXPIRY_DAYS	Prod / Dev	Finestra di validità di default per i link pubblici.	0 per nessuna scadenza
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR	Prod / Dev	Limite orario per l’apertura degli endpoint offerta pubblici.	60, 999
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR	Prod / Dev	Limite orario per azioni pubbliche come accetta/rifiuta.	5, 999
TRACKING_IP_ANONYMIZE	Prod / Dev	Abilita l’anonimizzazione IP per i dati di tracking.	false
TRACKING_IP_ANONYMIZE_AFTER_DAYS	Prod / Dev	Periodo di anonimizzazione differita per gli IP di tracking.	0
TRACKING_RETENTION_DAYS	Prod / Dev	Finestra di retention dei dati di tracking dei link pubblici.	365
CLIENT_CONFIRM_EMAIL_ENABLED	Prod / Dev	Invia un’email di conferma al cliente dopo l’accettazione.	false
NOTIFICATIONS_ENABLED	Prod / Dev	Abilita il sottosistema notifiche.	true
NOTIFICATIONS_EMAIL_ENABLED	Prod / Dev	Abilita la consegna email delle notifiche.	true, false
NOTIFICATIONS_PUBLIC_PREFERENCES_URL	Prod	URL pubblico per la gestione delle preferenze di notifica.	https://tuodominio.com/notifications/preferences
NOTIFICATIONS_PREFERENCE_TOKEN_TTL_DAYS	Prod	Validità del token per i link di preferenze notifica.	30
NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS	Prod / Dev	Pianificazione promemoria prima della scadenza delle offerte.	7,2
NOTIFICATIONS_LICENSE_EXPIRY_WARN_DAYS	Prod / Dev	Pianificazione promemoria prima della scadenza delle licenze.	30,14,7,1
REMINDERS_JOB_INTERVAL_MINUTES	Prod / Dev	Cadenza di polling dei job di promemoria.	5

Generazione PDF

Variabile	Ambito	Scopo	Valore tipico
PDF_ENABLED	Prod / Dev	Abilita i flussi di generazione PDF.	true, false
PDF_GOTENBERG_URL	Prod / Dev	URL interna del servizio Gotenberg.	http://gotenberg:3000
PDF_SYNC_TIMEOUT_MS	Prod / Dev	Timeout per le richieste PDF sincrone.	10000, 5000
PDF_SYNC_MAX_ITEMS	Prod / Dev	Numero massimo di righe offerta ancora gestite in modo sincrono.	50
PDF_STORAGE_PATH	Prod / Dev	Percorso filesystem dove vengono salvati i PDF generati.	/data/pdfs, ./data/pdfs
PDF_RETENTION_DAYS	Prod / Dev	Periodo di retention dei PDF generati.	365
PDF_RETRY_BACKOFF_SECONDS	Prod / Dev	Pianificazione dei retry per i job PDF asincroni.	30,120,600
PDF_WORKER_CONCURRENCY	Prod / Dev	Concorrenza dei worker per l’elaborazione PDF.	2
PDF_WORKER_POLL_INTERVAL_MS	Prod / Dev	Intervallo di polling per i job PDF.	2000

Licensing, report e manutenzione

Variabile	Ambito	Scopo	Valore tipico
LICENSE_SKIP_SIGNATURE_CHECK	Prod / Dev	Salta la validazione della firma della licenza. Non abilitare mai in produzione.	false, true
LICENSE_EXPIRY_CHECK_INTERVAL_H	Prod / Dev	Cadenza di ricarica per i controlli di scadenza licenza.	24
REPORTS_DEFAULT_PERIOD_DAYS	Prod / Dev	Intervallo di date di default dei report.	30
REPORTS_EXPORT_MAX_ROWS	Prod / Dev	Limite di righe per le esportazioni report.	10000

Backup, GeoIP e operazioni privacy

Variabile	Ambito	Scopo	Valore tipico
BACKUP_ENABLED	Prod / Dev	Abilita i backup schedulati.	true, false
BACKUP_CRON	Prod / Dev	Pianificazione cron per i backup automatici.	0 0 2 * * *
BACKUP_RETENTION_DAILY	Prod / Dev	Numero di backup giornalieri da conservare.	7
BACKUP_RETENTION_WEEKLY	Prod / Dev	Numero di backup settimanali da conservare.	4
BACKUP_RETENTION_MONTHLY	Prod / Dev	Numero di backup mensili da conservare.	12
BACKUP_LOCAL_DIR	Runtime / Compose	Directory locale usata dagli script di backup e dai container backup-worker.	/app/data/backups
BACKUP_ARCHIVE_ENCRYPTION_MODE	Prod / Dev	Modello di cifratura archivio: AGE_RECIPIENT (consigliato) o NONE.	AGE_RECIPIENT
BACKUP_AGE_RECIPIENT	Prod / Dev	Recipient age pubblico (age1...) per gli archivi cifrati.	age1...
BACKUP_DATABASE_PAYLOAD_MODE	Prod / Dev	Payload database: APP_ENCRYPTED (default) o PII_DECRYPTED.	APP_ENCRYPTED
JOBS_MODE	Prod / Dev / Compose	Quali job pianificati esegue lo scheduler nella JVM: all (web + backup in un solo container), web (solo web — da abbinare a un worker backup-only), backup-only (worker di backup dedicato).	all
BACKUP_RUNTIME_PROFILE	Prod / Dev	Etichetta del profilo runtime registrata nei log/manifesti di backup: WORKER, WEB_MAINTENANCE, ONE_SHOT, OFFLINE_MAINTENANCE. Abbina WEB_MAINTENANCE a JOBS_MODE=all (senza worker separato); abbina WORKER a JOBS_MODE=web + un worker backup-only.	WORKER
BACKUP_VERIFY_MODE	Prod / Dev	Verifica post-backup: off, archive, sandbox.	off
BACKUP_ALLOW_UNENCRYPTED_LOCAL_BACKUP	Prod / Dev	Consente esplicitamente un backup locale non cifrato.	false
BACKUP_RCLONE_REMOTE	Prod / Dev	Destinazione rclone per i backup offsite.	s3:bucket/path
BACKUP_OFFLINE_NOTICE_SECONDS	Prod	Periodo di grazia prima che la manutenzione offline fermi i servizi.	300
BACKUP_MAINTENANCE_PAGE_ENABLED	Prod	Serve una pagina di manutenzione statica durante il backup offline.	false
BACKUP_DOWNLOAD_GRANT_TTL_SECONDS	Prod / Dev	TTL per le autorizzazioni di download backup monouso.	120
GEOIP_ENABLED	Prod / Dev	Solo interruttore dell’applicazione per Paese (anche interruttore di emergenza). Il database si carica e aggiorna in modo indipendente — vedi GEOIP_AUTO_UPDATE.	false
GEOIP_DB_PATH	Prod / Dev	Percorso del database GeoIP (scaricato automaticamente all’avvio; DB-IP senza chiave per impostazione predefinita, MaxMind tramite MAXMIND_*).	/app/data/geoip/...
SECURITY_GEOIP_ALLOWED_COUNTRIES	Prod / Dev	Allowlist di paesi ISO per i controlli GeoIP.	vuoto o PL,DE,CZ
MAXMIND_ACCOUNT_ID	Prod	Account MaxMind per i download GeoLite.	ID account
MAXMIND_LICENSE_KEY	Prod	Chiave di licenza MaxMind.	segreto
GEOIP_EDITION_ID	Prod	Identificatore dell’edizione MaxMind.	GeoLite2-Country
GDPR_ANONYMIZE_AUTO_AFTER_DAYS	Prod / Dev	Orizzonte di anonimizzazione automatica per i workflow privacy.	0

Guida pratica

• parti dal template di produzione per gli ambienti reali e dal template di sviluppo per gli stack locali
• tratta DB_ENCRYPTION_KEY, TIMING_TOKEN_SECRET, PUBLIC_LINK_PASSWORD_SESSION_SECRET e le credenziali SMTP come segreti con backup sicuro
• evita di portare porte di Compose e variabili frontend nel .env di produzione senza necessità
• per il setup minimo, consulta la Installation Guide
• per topologia e modalità di deploy, consulta Deployment Options