Installazione

QuoteNode gira come insieme di container Docker. Non devi installare Java, Node.js o PostgreSQL sulla macchina host: a tutto pensa Docker.

Prerequisiti

• Docker Engine 24.0 o superiore (install Docker)
• Docker Compose v2, incluso nelle versioni moderne di Docker Desktop e Docker Engine
• Una macchina con almeno 2 GB di RAM e 10 GB di spazio libero

Per verificare l’ambiente:

docker --version        # Dovrebbe mostrare 24.0+
docker compose version  # Dovrebbe mostrare v2.x

Avvio rapido (5 minuti)

Questo mette QuoteNode in esecuzione sulla tua macchina locale per valutazione. Non e una configurazione da produzione; per quella, leggi la sezione successiva.

Passo 1 - Crea una directory di progetto

mkdir quotenode && cd quotenode

Passo 2 - Crea il file di configurazione

Crea un file chiamato .env con le impostazioni minime richieste:

# Database
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME=quotenode
DB_PASSWORD=change-me-to-something-random-32-chars
DB_NAME=quotenode

# ============================================================
# SECURITY SECRETS - LEGGI PRIMA DI CONTINUARE
# Questi valori sono UNICI per la tua installazione.
# Se perdi questo file, NON potrai rigenerare gli stessi segreti.
# SALVA QUESTO FILE e conserva una copia sicura.
# ============================================================
DB_ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
TIMING_TOKEN_SECRET=change-me-timing-secret-min-32-chars
PUBLIC_LINK_PASSWORD_SESSION_SECRET=change-me-session-secret-min-32

# Domain (for CORS and Caddy)
CORS_ALLOWED_ORIGINS=http://localhost
DOMAIN=localhost

# Logging
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

Salva subito il file .env. I segreti sopra sono unici per questa installazione. Se perdi il file, non potrai rigenerare gli stessi valori. Senza il DB_ENCRYPTION_KEY originale, i dati cifrati come codici MFA, password SMTP e chiavi API diventano permanentemente illeggibili. Copia il file in un luogo sicuro; in produzione, valuta anche una copia cartacea custodita in cassaforte.

Passo 3 - Crea il file Docker Compose

Crea un file chiamato docker-compose.yml:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    restart: unless-stopped

  gotenberg:
    image: gotenberg/gotenberg:8
    environment:
      LOG_LEVEL: info
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    image: ghcr.io/lesisty7/quotenode/quotenode-api:latest
    depends_on:
      postgres: { condition: service_healthy }
      gotenberg: { condition: service_healthy }
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      PDF_ENABLED: "true"
      PDF_GOTENBERG_URL: http://gotenberg:3000
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    restart: unless-stopped

  frontend:
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend:latest
    depends_on:
      backend: { condition: service_healthy }
    ports:
      - "80:80"
      - "443:443"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    restart: unless-stopped

volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:

Passo 4 - Avvia QuoteNode

docker compose up -d

Docker scarichera le immagini e avviera tutti i servizi. Puoi seguire l’avvio con:

docker compose logs -f backend

Aspetta di vedere una riga simile a Started QuoteNodeApplication: significa che il backend e pronto.

Passo 5 - Apri QuoteNode

Apri http://localhost nel browser.

Credenziali di default:

Campo	Valore
Email	[email protected]
Password	Admin123!

Cambia subito la password di default dopo il login, in Settings > My Profile > Change Password.

Cosa e in esecuzione

Dopo docker compose up, avrai 4 container:

Container	Funzione	RAM
postgres	Archivia tutti i dati	~256 MB
backend	API Java e logica di business	~512 MB - 1.5 GB
gotenberg	Converte HTML in PDF	~200 MB
frontend	Serve la UI web e il reverse proxy	~20 MB

Totale approssimativo: 1.5 - 2.5 GB di RAM.

Comandi comuni

# Verifica che tutti i servizi siano attivi
docker compose ps

# Log di tutti i servizi
docker compose logs -f

# Log del solo backend
docker compose logs -f backend

# Arresta QuoteNode
docker compose down

# Aggiorna all'ultima versione
docker compose pull && docker compose up -d

Proteggere i tuoi segreti

Il file .env contiene segreti crittografici unici per la tua installazione. Capire cosa protegge ciascun segreto aiuta a pianificare backup e disaster recovery:

Segreto	Cosa protegge	Se viene perso
DB_PASSWORD	Accesso al database	Recuperabile, tramite strumenti amministrativi PostgreSQL
DB_ENCRYPTION_KEY	Codici MFA, password SMTP, chiave API FX e PII quando ENCRYPT_PII=true	Illeggibile per sempre senza la chiave originale
TIMING_TOKEN_SECRET	Token anti timing attack	Rigenerabile, con invalidazione dei token esistenti
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Sessioni dei link pubblici	Rigenerabile, con scadenza delle sessioni attive

Il segreto critico e DB_ENCRYPTION_KEY. Gli altri possono essere rigenerati con disagi limitati. Ma se perdi DB_ENCRYPTION_KEY, perdi la capacita di leggere i campi cifrati. Se ENCRYPT_PII=true, questo include anche PII di clienti, contatti, fornitori e utenti.

Per la produzione consigliamo:

• conserva una copia di .env in un password manager
• per massima sicurezza, stampa i segreti e conserva la stampa in cassaforte
• non committare mai .env nel controllo di versione

Recupero se perdi .env

Se perdi .env ma hai un backup del database non cifrato puoi comunque recuperare i dati:

1. crea un nuovo .env con nuovi segreti
2. ripristina il database dal backup con pg_dump / pg_restore
3. tutti i dati di business, come clienti, offerte, prodotti e utenti, restano accessibili
4. si perdono solo alcuni campi, come codici MFA, password SMTP e chiave FX. Se ENCRYPT_PII=true era attivo, si perde anche tutta la PII

Se i backup sono cifrati con GPG tramite BACKUP_GPG_RECIPIENT, ti serve la chiave privata GPG per decrittarli.

Deployment di produzione

Per usare QuoteNode in produzione devi:

1. Generare segreti reali:

openssl rand -hex 32
openssl rand -base64 32

2. Configurare un dominio con HTTPS, impostando DOMAIN e CORS_ALLOWED_ORIGINS sul dominio reale.

3. Configurare l’email in uno dei due modi:

• Preferito: configurare SMTP in Settings > Email SMTP dentro QuoteNode
• Fallback: impostare SMTP dentro .env

SMTP_HOST=smtp.yourprovider.com
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=your-smtp-password
SMTP_AUTH=true
SMTP_STARTTLS=true

4. Eseguire backup del tuo .env prima di qualunque altra operazione.
5. Abilitare backup del database consultando Backup & Recovery.
6. Rivedere tutte le impostazioni tramite Environment Variables Reference.

Per opzioni avanzate, come Coolify, backup worker o GeoIP, consulta Deployment Options.

Aggiornare QuoteNode

Per aggiornare all’ultima versione:

docker compose pull && docker compose up -d

Il file .env non viene modificato dagli aggiornamenti. Docker scarica nuove immagini, ma configurazione e dati restano intatti. Non eliminare e non ricreare .env durante gli aggiornamenti.

Le migrazioni schema database vengono eseguite automaticamente all’avvio del backend. Non e necessario alcun passaggio manuale di migration.

Risoluzione dei problemi

Il backend non si avvia

Controlla i log con docker compose logs backend. I problemi piu comuni sono:

• database non ancora pronto
• segreti non validi
• conflitti di porta su 80 o 443

Non riesco a collegarmi a QuoteNode

• verifica che tutti i container siano in esecuzione con docker compose ps
• controlla che il frontend risulti healthy
• in locale usa http://localhost e non https://

Ho dimenticato la password admin

Usa invece un percorso di recupero non distruttivo:

1. Se SMTP e configurato, inizia dal flusso nella schermata di login: Password dimenticata?
2. Se un altro amministratore puo ancora accedere, apri Users nel pannello amministrativo e reimposta la password da li. Gli amministratori possono impostare una nuova password e forzare il cambio al prossimo accesso.
3. Se nessun amministratore riesce ad accedere e il reset via email non e disponibile, trattalo come un incidente di recovery operativa. Ripristina l accesso da un backup valido o usa la procedura interna di manutenzione prevista per quell ambiente.

docker compose down -v non e una procedura di reset password. Quel comando ricrea l intera istanza e cancella tutti i dati persistenti, inclusi utenti, offerte, clienti, impostazioni e backup locali. Usalo solo in ambienti di test locali e usa-e-getta quando vuoi azzerare deliberatamente tutta l istanza.

Vedi anche: Reimpostare una password e Backup e ripristino.

Passi successivi

• Configuration Guide
• Environment Variables Reference
• Deployment Options
• Backup & Recovery