Wiki

Opzioni di deployment

Come distribuire QuoteNode con Docker Compose, Coolify e una topologia adatta alla produzione.

Opzioni di deployment

QuoteNode supporta piu modelli di deployment, tutti basati su container Docker. Scegli l’approccio piu adatto alla tua infrastruttura.

Docker Compose

Il deployment standard usa un singolo docker-compose.yml che avvia tutti i servizi:

docker compose up -d

Topologia di produzione

Internet
  │
  ▼
Caddy (port 80/443, HTTPS automatico)
  ├── /api/*     → Backend (Java 25, port 8080)
  ├── /offer/*   → Backend (pagine pubbliche offerta)
  └── /*         → Frontend (Vue 3, asset statici)

Backend → PostgreSQL (port 5432)
Backend → Gotenberg (port 3000)
backup-worker → PostgreSQL

Servizi

Container	Immagine	Scopo
`frontend`	Vue 3 + Caddy	Serve la SPA e proxy delle richieste API
`backend`	Java 25 / Spring Boot	API REST, logica business, generazione PDF
`postgres`	PostgreSQL 18 Alpine	Database
`gotenberg`	Gotenberg 8	Conversione HTML in PDF
`backup-worker`	Come backend	Backup schedulati di database e file

Volumi persistenti

Volume	Contenuto
`postgres_prod_data`	File del database
`backend_prod_uploads`	Immagini prodotto e loghi
`backend_prod_pdfs`	PDF generati
`backend_prod_backups`	Archivi di backup
`backend_prod_geoip`	Database GeoIP MaxMind opzionale

Deployment Coolify

Coolify e una PaaS self-hostable open source che puo eseguire QuoteNode su un tuo server.

Differenze principali rispetto a Docker Compose standard

Coolify gestisce TLS e routing dominio
le variabili ambiente vengono gestite dalla UI di Coolify
i container vengono monitorati con health check
il deployment puo avvenire da sorgente o da immagini prebuildate

Modalita A - Build da sorgente

Coolify clona il repository e costruisce le immagini ad ogni deploy
deploy piu lenti
nessuna pipeline CI/CD obbligatoria

Modalita B - Immagini prebuildate

GitHub Actions costruisce le immagini e le pubblica su GHCR
Coolify scarica semplicemente l’ultima immagine
deploy piu veloci
modello consigliato per produzione

Configurazione richiesta in Coolify

Resource type: Dockerfile o Docker Image
Internal port: 8080
Health check path: /health
Domain: configurato a livello Coolify
HTTPS: gestito automaticamente da Coolify

Variabili richieste

Le installazioni di produzione richiedono almeno:

DB_USERNAME
DB_PASSWORD
DB_ENCRYPTION_KEY
TIMING_TOKEN_SECRET
PUBLIC_LINK_PASSWORD_SESSION_SECRET
CORS_ALLOWED_ORIGINS

Email opzionale ma consigliata

Per l’invio di offerte e notifiche e consigliato configurare:

SMTP_HOST
SMTP_PORT
SMTP_USERNAME
SMTP_PASSWORD
SMTP_AUTH
SMTP_STARTTLS

Backup opzionale

Per proteggere i dati in produzione conviene configurare anche:

BACKUP_ENABLED
BACKUP_CRON
BACKUP_RCLONE_REMOTE
BACKUP_ARCHIVE_ENCRYPTION_MODE
BACKUP_AGE_RECIPIENT

Opzioni di sicurezza

Tra le variabili utili in ambienti piu rigidi:

FEATURE_2FA_ENABLED
SECURITY_BOT_DETECTION_ENABLED
GEOIP_ENABLED

Feature flags operative

Tra le opzioni piu comuni:

PDF_ENABLED
NOTIFICATIONS_ENABLED
NOTIFICATIONS_EMAIL_ENABLED
LOG_LEVEL

Riferimento variabili ambiente

Per il catalogo completo, inclusi port di sviluppo, variabili Vite, path del backup worker e override operativi, vedi Environment Variables Reference.

Requisiti minimi server

Deployment	RAM	CPU	Disco
Valutazione / uso singolo	2 GB	1 core	10 GB SSD
Team piccolo	4 GB	2 core	20 GB SSD
Team medio	8 GB	4 core	50 GB SSD

Queste stime sono conservative. L’uso reale dipende da dimensione catalogo, volume offerte e frequenza di generazione PDF.

Server dedicato

Un server dedicato o una VM gestita direttamente e spesso la scelta piu lineare quando il team vuole controllo completo su rete, storage, backup e aggiornamenti.

Cloud privato

Un cloud privato o un ambiente virtualizzato puo essere utile quando QuoteNode deve allinearsi a policy infrastrutturali aziendali gia esistenti.

On-premise segmentato

In ambienti on-premise piu segmentati, il vantaggio principale e la vicinanza ai dati interni, a fronte di una maggiore responsabilita operativa.

Aggiornamenti e rollback

Indipendentemente dal modello scelto, conviene prevedere procedure esplicite per aggiornamento, verifica dello stato di salute e rollback, sempre con backup verificati prima dei cambiamenti piu critici.