Riferimento variabili d’ambiente

Questa pagina consolida le variabili d’ambiente attualmente usate dal progetto QuoteNode.

Le fonti principali di verita restano i template del repository applicativo:

• infra/.env.prod.example
• infra/.env.dev.example
• infra/.env.dev-sid
• infra/docker-compose.*.yml

Usa questa pagina come catalogo orientato agli operatori. Per una configurazione minima, consulta la Installation Guide. Per topologia di deployment, consulta Deployment Options.

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
• default vuoti significano in genere “imposta esplicitamente se ti serve”

Compose e stack locale

Variabile	Ambito	Scopo
COMPOSE_PROJECT_NAME	Dev / Compose	Evita collisioni tra piu stack locali
POSTGRES_PORT	Dev / Compose	Porta host per PostgreSQL
MAILPIT_PORT	Dev / Compose	Porta host per UI Mailpit
BACKEND_PORT	Dev / Compose	Porta host per API backend
FRONTEND_PORT	Dev / Compose	Porta host frontend
VITE_PUBLIC_API_BASE	Dev / Frontend	URL API visibile dal browser nello stack locale
APP_VERSION	Prod / Dev / Compose	Tag immagine Docker
PROXY_MODE	Prod / Dev / Compose	Sceglie tra proxy interno ed esterno
DOMAIN	Prod / Compose	Dominio pubblico usato da Caddy

Database e runtime principale

Variabile	Ambito	Scopo
DB_URL	Prod / Dev	Stringa JDBC PostgreSQL
DB_USERNAME	Prod / Dev	Utente database
DB_PASSWORD	Prod / Dev	Password database
DB_NAME	Prod / Dev / Compose	Nome database
SPRING_PROFILES_ACTIVE	Prod / Dev	Profilo Spring attivo
CORS_ALLOWED_ORIGINS	Prod / Dev	Origini browser consentite per l’API
LOG_LEVEL	Prod / Dev	Verbosita base dei log

Sicurezza auth e sessione

Variabile	Ambito	Scopo
DB_ENCRYPTION_KEY	Prod / Dev	Chiave principale di cifratura applicativa
TIMING_TOKEN_SECRET	Prod / Dev	Segreto HMAC per protezione timing-token
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Prod / Dev	Segreto sessione per link pubblici protetti
AUTH_PASSWORD_MIN_LENGTH	Prod / Dev	Lunghezza minima password
AUTH_PASSWORD_COMPLEXITY_LEVEL	Prod / Dev	Livello di complessita password
AUTH_SESSION_IDLE_TIMEOUT_MIN	Prod / Dev	Timeout inattivita sessione
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H	Prod / Dev	Durata massima assoluta sessione
FEATURE_2FA_ENABLED	Prod / Dev	Interruttore master del 2FA
SECURITY_BOT_DETECTION_ENABLED	Prod / Dev	Abilita il layer di bot detection

File, import e media prodotto

Variabile	Ambito	Scopo
CSV_IMPORT_MAX_ROWS	Prod / Dev	Limite righe import CSV
STORAGE_PATH	Prod / Dev	Path root dei file caricati
PIM_MEDIA_MAX_SIZE_MB	Prod / Dev	Dimensione massima di una singola immagine prodotto
PIM_MEDIA_MAX_PER_PRODUCT	Prod / Dev	Numero massimo di media per prodotto
IMPORT_ZIP_MAX_SIZE_MB	Prod / Dev	Dimensione massima dello ZIP di import immagini

Spedizione, FX e default offerta

Variabile	Ambito	Scopo
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR	Prod / Dev	Divisore peso volumetrico
SHIPPING_OVERRIDE_REQUIRES_REASON	Prod / Dev	Richiede motivazione per override spedizione
FX_PROVIDER	Prod / Dev	Fonte del tasso cambio
FX_REFRESH_INTERVAL_MIN	Prod / Dev	Frequenza refresh FX
FX_DEFAULT_MARGIN_PERCENT	Prod / Dev	Margine di default sui cambi
OFFER_NUMBER_PREFIX	Prod / Dev	Prefisso numerazione offerte

Email, link pubblici e notifiche

Variabile	Ambito	Scopo
SMTP_HOST	Prod / Dev	Host SMTP
SMTP_PORT	Prod / Dev	Porta SMTP
SMTP_USERNAME	Prod / Dev	Username SMTP
SMTP_PASSWORD	Prod / Dev	Password SMTP
PUBLIC_LINK_TOKEN_BYTES	Prod / Dev	Entropia token link pubblici
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR	Prod / Dev	Limite orario di apertura link pubblici
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR	Prod / Dev	Limite orario azioni pubbliche
NOTIFICATIONS_ENABLED	Prod / Dev	Abilita subsystem notifiche
NOTIFICATIONS_EMAIL_ENABLED	Prod / Dev	Abilita consegna email delle notifiche

Generazione PDF

Variabile	Ambito	Scopo
PDF_ENABLED	Prod / Dev	Abilita generazione PDF
PDF_GOTENBERG_URL	Prod / Dev	URL interna del servizio Gotenberg
PDF_SYNC_TIMEOUT_MS	Prod / Dev	Timeout richieste PDF sincrone
PDF_SYNC_MAX_ITEMS	Prod / Dev	Numero massimo di righe gestite in sync
PDF_STORAGE_PATH	Prod / Dev	Path filesystem per i PDF generati
PDF_RETENTION_DAYS	Prod / Dev	Giorni di retention dei PDF

Backup, GeoIP e privacy

Variabile	Ambito	Scopo
BACKUP_ENABLED	Prod / Dev	Abilita backup schedulati
BACKUP_CRON	Prod / Dev	Espressione cron backup
BACKUP_RETENTION_DAILY	Prod / Dev	Numero di backup giornalieri da mantenere
BACKUP_LOCAL_DIR	Runtime / Compose	Directory locale per script backup
BACKUP_GPG_RECIPIENT	Prod / Dev	Destinatario GPG per cifratura backup
BACKUP_RCLONE_REMOTE	Prod / Dev	Destinazione rclone offsite
GEOIP_ENABLED	Prod / Dev	Abilita controlli GeoIP
GEOIP_DB_PATH	Prod / Dev	Percorso database MaxMind
GDPR_ANONYMIZE_AUTO_AFTER_DAYS	Prod / Dev	Orizzonte anonimizzazione automatica

Guida pratica

• parti dal template produzione per deploy reali
• tratta DB_ENCRYPTION_KEY, TIMING_TOKEN_SECRET, PUBLIC_LINK_PASSWORD_SESSION_SECRET e le credenziali SMTP come segreti da backup sicuro
• evita di portare variabili solo-Compose dentro il .env di produzione se non servono
• per la configurazione minima, la Installation Guide rimane intenzionalmente piu corta di questa pagina

Rotazione log e diagnostica

Tra le variabili operative piu utili rientrano anche quelle legate a rotazione log Docker e support diagnostics, come DOCKER_LOG_MAX_SIZE, DOCKER_LOG_MAX_FILE e le opzioni SUPPORT_LOGS_* per la diagnostica applicativa.

Licensing, report e manutenzione

Per aspetti di licenza e reporting conviene tenere presenti anche:

• LICENSE_SKIP_SIGNATURE_CHECK
• LICENSE_EXPIRY_CHECK_INTERVAL_H
• REPORTS_DEFAULT_PERIOD_DAYS
• REPORTS_EXPORT_MAX_ROWS

Note su GeoIP e privacy

Quando vengono usati controlli GeoIP o processi di anonimizzazione, e utile rivedere con attenzione GEOIP_ENABLED, GEOIP_DB_PATH, SECURITY_GEOIP_ALLOWED_COUNTRIES e GDPR_ANONYMIZE_AUTO_AFTER_DAYS.

Variabili backup e retention

Tra le variabili piu sensibili sul piano operativo rientrano anche:

• BACKUP_ENABLED
• BACKUP_CRON
• BACKUP_RETENTION_DAILY
• BACKUP_RETENTION_WEEKLY
• BACKUP_RETENTION_MONTHLY
• BACKUP_LOCAL_DIR
• BACKUP_RCLONE_REMOTE
• BACKUP_GPG_RECIPIENT

Variabili PDF e performance

Per il comportamento dei documenti e il carico del sistema contano anche:

• PDF_ENABLED
• PDF_GOTENBERG_URL
• PDF_SYNC_TIMEOUT_MS
• PDF_SYNC_MAX_ITEMS
• PDF_WORKER_CONCURRENCY
• PDF_WORKER_POLL_INTERVAL_MS

Variabili pubbliche e notifiche

Le superfici rivolte al cliente dipendono anche da:

• PUBLIC_LINK_TOKEN_BYTES
• PUBLIC_RATE_LIMIT_OPEN_PER_HOUR
• PUBLIC_RATE_LIMIT_ACTION_PER_HOUR
• TRACKING_RETENTION_DAYS
• NOTIFICATIONS_ENABLED
• NOTIFICATIONS_EMAIL_ENABLED
• NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS

Separazione tra configurazione e wiring

Una buona pratica consiste nel distinguere chiaramente tra variabili che governano il comportamento applicativo, variabili usate solo per il wiring Docker Compose e override temporanei impiegati in test o supporto.

Variabili che richiedono backup sicuro

Alcune variabili non sono semplici parametri di configurazione, ma veri asset critici di continuita operativa:

• DB_ENCRYPTION_KEY
• TIMING_TOKEN_SECRET
• PUBLIC_LINK_PASSWORD_SESSION_SECRET
• credenziali SMTP
• eventuali token di integrazione esterna

La perdita di questi valori puo compromettere restore, invio email, accesso sicuro e leggibilita dei dati cifrati.

Variabili che cambiano raramente

Molte variabili vengono definite una volta e dovrebbero cambiare solo in occasione di eventi specifici, come cambio dominio, rotazione chiavi, modifica policy di sicurezza o revisione dell’architettura di deployment.

Variabili che richiedono verifica post-deploy

Dopo una modifica ambientale, conviene verificare almeno:

• login e sessione
• invio email
• generazione PDF
• link pubblici
• backup schedulati
• health check del backend