Installation

Installare su un laptop locale

Esegui QuoteNode localmente per valutazione senza esporlo ai clienti.

Installare su un laptop locale

Usa questo percorso quando vuoi provare QuoteNode su un unico computer. È il modo più veloce per valutare l’applicazione, ma non è un deployment rivolto ai clienti.

Quando usarlo

Vuoi un’istanza demo o di prova.
Stai testando la creazione di offerte, i PDF, i template, i prodotti e le impostazioni.
Non hai bisogno che i clienti aprano link pubblici delle offerte da un altro dispositivo.

Cosa non funzionerà

I link pubblici delle offerte generati come http://localhost/... funzionano solo sullo stesso laptop.
I link email di solito non sono utili perché i destinatari non possono aprire localhost dalle loro macchine.
HTTPS normalmente non è configurato per questa topologia.
Il laptop deve essere acceso e Docker deve essere in esecuzione.

Prerequisiti

Docker Desktop o Docker Engine con Docker Compose v2.
Almeno 2,5 GB di RAM disponibili per lo stack.
Almeno 10 GB di spazio libero su disco.
Un host x86 a 64 bit (linux/amd64). I dispositivi ARM, compresi i NAS con processore ARM, non sono supportati.

Controlla la configurazione:

docker --version        # Should show 24.0+
docker compose version  # Should show v2.x

Passo 1 — Creare una directory di progetto

mkdir quotenode && cd quotenode
curl -fsSLO https://quotenode.dev/releases/v0.9.8-alpha/quotenode-deploy-v0.9.8-alpha.tar.gz
tar -xzf quotenode-deploy-v0.9.8-alpha.tar.gz --strip-components=1

Così scarichi il pacchetto di distribuzione della release v0.9.8-alpha: docker-compose.yml con ogni immagine fissata tramite digest, env.example, release.json (l’identità della release) e operator/ (strumenti di backup e ripristino).

Problema noto in v0.9.5-alpha: il suo env.example contiene una riga di esempio attiva, BACKUP_RCLONE_REMOTE=s3:mybucket/backups, che fa fallire ogni backup. Le impostazioni di questa guida non la contengono; se copi impostazioni da env.example, ometti quella riga (dettagli).

Passo 2 — Creare il file di configurazione

Crea un file chiamato .env con le impostazioni minime richieste. Genera i tuoi segreti — non usare i valori segnaposto in produzione:

# 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 — READ THIS BEFORE CONTINUING
# These values are UNIQUE to your installation.
# If you lose this file, you CANNOT regenerate the same secrets.
# SAVE THIS FILE and keep a secure backup.
# ============================================================
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=http://localhost

# Client IP is auto-detected behind internal proxies and CDNs (Cloudflare included) — leave empty.
# Set only for an unusual proxy whose transport peer is a PUBLIC address to trust (IP/CIDR or hostname).
SECURITY_TRUSTED_PROXIES=

# Application
LOG_LEVEL=INFO
SPRING_PROFILES_ACTIVE=prod

# Smaller laptop profile (see System resources)
POSTGRES_MEM_LIMIT=384m
GOTENBERG_MEM_LIMIT=384m
BACKEND_MEM_LIMIT=1280m
BACKEND_CPUS=2.0

Salva il tuo file .env immediatamente. Il DB_ENCRYPTION_KEY cifra i dati sensibili a riposo. Se lo perdi, i campi cifrati (codici MFA, password SMTP, chiavi API) diventano permanentemente illeggibili. Copia questo file in un posto sicuro.

Passo 3 — Verifica il file Docker Compose

Il docker-compose.yml del pacchetto esegue la release v0.9.8-alpha con ogni immagine fissata tramite digest. Non modificarlo: tutte le impostazioni vanno in .env, e un aggiornamento sostituisce questo file con quello della release successiva. Per riferimento:

x-json-file-logging: &json-file-logging
  driver: json-file
  options:
    max-size: "${DOCKER_LOG_MAX_SIZE:-10m}"
    max-file: "${DOCKER_LOG_MAX_FILE:-5}"

# ==========================================================================
# QuoteNode — standalone deployment (docker compose)
# GENERATED by scripts/render-deployment.mjs — do not edit by hand.
# Release v0.9.8-alpha (commit ff74453ca68f3c40bd86a32f0b0b813aaffc7aea, build 28); platforms: linux/amd64.
# API image:      ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
# Frontend image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
#
# Settings: the .env file in this directory (start from env.example, the commented catalogue of every
# setting; postgres, backend and backup-worker read it). Start: docker compose up -d
# DOMAIN: public host name for automatic HTTPS, or :80 / http://<address> for plain HTTP on a trusted LAN.
# Only the caddy entry point publishes ports (HTTP_PORT/HTTPS_PORT, default 80/443).
# Upgrades: replace this file with the next release package version; volumes keep the data.
# ==========================================================================

services:
  postgres:
    # Database (PostgreSQL 18); internal network only, data in the database volume.
    image: postgres:18-alpine@sha256:77f585114c32fbca283dc835b0596f4e52b51b4c6662d7810b2f4084f60a1873
    # JIT is off by default: for this OLTP workload most queries fall below jit_above_cost,
    # so JIT compilation rarely helps and can add latency. Set PG_JIT=on to re-enable.
    command: ["postgres", "-c", "jit=${PG_JIT:-off}"]
    env_file: .env
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_INITDB_ARGS: "--data-checksums"
      # postgres:18 refuses to start on a bare /var/lib/postgresql/data mount (new default layout).
      # Pin PGDATA to the legacy path so the existing volume mount keeps working; major upgrades go
      # through a logical dump/restore, never an in-place upgrade of the data directory.
      PGDATA: /var/lib/postgresql/data
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME} -d ${DB_NAME}"]
      interval: 10s
      timeout: 5s
      retries: 10
    # CPU ceilings are opt-in (*_CPUS): 0 = no ceiling, all host cores. Docker refuses a ceiling above the
    # host's core count, so a fixed default would stop the stack on smaller hosts (minimum: 2 cores).
    cpus: ${POSTGRES_CPUS:-0}
    # Ceiling, not a reservation: PG sits at tens of MB until working set/connections grow.
    # Default 512m fits the 4 GB-VM profile; raise POSTGRES_MEM_LIMIT for larger tiers.
    mem_limit: ${POSTGRES_MEM_LIMIT:-512m}
    restart: unless-stopped
    logging: *json-file-logging
    # No published host port: the database is reachable only on the internal network.

  gotenberg:
    # PDF rendering (Chromium) for the backend; internal network only, keeps no data.
    image: gotenberg/gotenberg:8@sha256:aa552cc115db488e0f0bcb07446aac13071ad51505b642c84bb894500907b42b
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
    cpus: ${GOTENBERG_CPUS:-0}
    # Chromium PDF rendering: measured ~188 MiB peak rendering a real offer template, so
    # 448m keeps ~2.4x headroom. Freed budget goes to backup-worker (closer to its limit).
    mem_limit: ${GOTENBERG_MEM_LIMIT:-448m}
    restart: unless-stopped
    logging: *json-file-logging

  backend:
    # API server (Java): business logic and web jobs; uploads, PDFs and the GeoIP database live in volumes.
    image: ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
    # Time Docker gives the backend between SIGTERM and SIGKILL. 60 s = the SMTP handoff hard limit
    # (mail.handoff.deadline-ms + end-of-data-allowance-ms = 25 s) + 5 s to record its outcome + the HTTP
    # graceful drain phase (30 s). A ceiling, not a delay: an idle backend exits in seconds.
    stop_grace_period: 60s
    depends_on:
      postgres:
        condition: service_healthy
      gotenberg:
        condition: service_healthy
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: web
      # The caddy edge below is the backend's only HTTP peer, so it is the trusted proxy by default (security
      # finding #80); without it every request would appear to come from the edge container. Override only
      # for a custom proxy chain.
      SECURITY_TRUSTED_PROXIES: ${SECURITY_TRUSTED_PROXIES:-caddy}
      BACKUP_LOCAL_DIR: /app/data/backups
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
      - backend_backups:/app/data/backups
      - backend_geoip:/app/data/geoip
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 45s
    cpus: ${BACKEND_CPUS:-0}
    # Heap auto-scales to 70% of this limit (MaxRAMPercentage); default 1536m → ~1 GB heap,
    # fits the 4 GB-VM profile. Raise BACKEND_MEM_LIMIT for heavier load (see resource docs).
    mem_limit: ${BACKEND_MEM_LIMIT:-1536m}
    restart: unless-stopped
    logging: *json-file-logging

  backup-worker:
    # Scheduled backups: same image as the backend, JOBS_MODE=backup-only; archives go to the backups volume.
    image: ghcr.io/lesisty7/quotenode/quotenode-api@sha256:0ed701f952c27ea0e1db168a00de75facb231f7c6d5f6b4f0f3b77ef98d4f140
    depends_on:
      postgres:
        condition: service_healthy
      backend:
        condition: service_healthy
    env_file: .env
    environment:
      SPRING_PROFILES_ACTIVE: prod
      JOBS_MODE: backup-only
      BACKUP_LOCAL_DIR: /app/data/backups
      # Worker runs pg_dump in a shell (out-of-JVM) and never does web/import heap work,
      # so it needs little heap. On this small 768m container the ~350 MB fixed non-heap
      # cost makes the global MaxRAMPercentage=70 (538 MB heap → 888 MB total) unsafe.
      # Cap heap lower so heap_max + non-heap stays well under the limit.
      JAVA_OPTS: "-XX:MaxRAMPercentage=45.0 -XX:+UseG1GC -XX:G1PeriodicGCInterval=300000"
    volumes:
      - backend_uploads:/app/data/uploads
      - backend_pdfs:/app/data/pdfs
      - backend_backups:/app/data/backups
      - backend_geoip:/app/data/geoip
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/health"]
      interval: 15s
      timeout: 10s
      retries: 5
      # JVM boots a large Spring context (CPU-bound); the grace window must outlast
      # cold start to avoid a false-unhealthy restart loop under load.
      start_period: 300s
    # CPU is a ceiling (idle cost ~0); give the worker enough to boot fast and to run
    # pg_dump + age-encryption/compression bursts without throttling. Idles near zero CPU.
    cpus: ${WORKER_CPUS:-0}
    # Default 832m: measured backup peak (JVM idle + pg_dump + tar + gzip) is ~607 MiB, so
    # this keeps a ~27% margin. Do NOT set WORKER_MEM_LIMIT below ~768m or backups risk OOM.
    mem_limit: ${WORKER_MEM_LIMIT:-832m}
    restart: unless-stopped
    logging: *json-file-logging

  frontend:
    # Web UI: the static build served by Caddy, reached through the caddy entry point.
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
    depends_on:
      backend:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:80/"]
      interval: 15s
      timeout: 5s
      retries: 3
    cpus: ${FRONTEND_CPUS:-0}
    # Prod frontend is Caddy serving the static build (measured ~46 MiB peak under load); 96m is ample.
    # CPU is a free ceiling, so headroom for concurrent connections costs nothing at idle.
    mem_limit: ${FRONTEND_MEM_LIMIT:-96m}
    restart: unless-stopped
    logging: *json-file-logging

  caddy:
    # Entry point: the only published ports (HTTP_PORT/HTTPS_PORT, default 80/443), TLS for DOMAIN, routing, security headers.
    image: ghcr.io/lesisty7/quotenode/quotenode-frontend@sha256:40a1cdc4fca5cebd9f43d34daef4ba059a88000ff08af821e199566f07260606
    # The released frontend image carries the edge config (frontend/caddy/Caddyfile.edge) and the Cloudflare
    # ranges, so the edge needs no host files. Same image digest as the frontend service.
    command: ["caddy", "run", "--config", "/etc/caddy/Caddyfile.edge", "--adapter", "caddyfile"]
    depends_on:
      backend:
        condition: service_healthy
      frontend:
        condition: service_healthy
    environment:
      # Site address for frontend/caddy/Caddyfile.edge: a public host name enables automatic HTTPS; ":80" or
      # "http://host" serves plain HTTP on a trusted LAN. Required: an empty site address is not a valid config.
      DOMAIN: ${DOMAIN:?set DOMAIN to the public host name, or :80 for plain HTTP on a LAN}
      # Optional: address(es) of an operator reverse proxy in front of this edge (default: trust none).
      EDGE_TRUSTED_PROXIES: ${EDGE_TRUSTED_PROXIES:-}
    ports:
      - "${HTTP_PORT:-80}:80"
      - "${HTTPS_PORT:-443}:443"
      - "${HTTPS_PORT:-443}:443/udp"      # HTTP/3 (QUIC)
    volumes:
      - caddy_data:/data
      - caddy_config:/config
    # caddy is the single ingress (TLS, HTTP/3/QUIC, proxying all traffic); give it
    # cores for handshake/encryption bursts under load. CPU idle cost ~0.
    cpus: ${CADDY_CPUS:-0}
    # 96m fits the 4 GB / light-traffic profile. Under heavy TLS load (many concurrent
    # handshakes, large QUIC buffers) raise CADDY_MEM_LIMIT — this ingress is untested at scale.
    mem_limit: ${CADDY_MEM_LIMIT:-96m}
    restart: unless-stopped
    logging: *json-file-logging

# Persistent data: database, uploads, generated PDFs, local backup archives, GeoIP database and the entry
# point's certificates/config. Docker prefixes each name with the Compose project name (by default the
# directory name), so keep the project name across upgrades.
volumes:
  postgres_data:
  backend_uploads:
  backend_pdfs:
  backend_backups:
  backend_geoip:
  caddy_data:
  caddy_config:

DOMAIN stabilisce come il punto di ingresso caddy serve QuoteNode: un nome host pubblico (crm.example.com) ottiene automaticamente un certificato HTTPS; http://<indirizzo> o :80 serve HTTP semplice in una rete fidata. Se le porte 80/443 sono già occupate, imposta HTTP_PORT / HTTPS_PORT in .env. Dietro il tuo reverse proxy, imposta DOMAIN=:80 e indica l’indirizzo del proxy in EDGE_TRUSTED_PROXIES.

Passo 4 — Avviare QuoteNode

docker compose up -d

Docker scaricherà le immagini dei container (al primo avvio ci vogliono alcuni minuti). Monitora l’avanzamento dell’avvio:

docker compose logs -f backend

Attendi di vedere Started QuoteNodeApplication — significa che il backend è pronto.

Passo 5 — Aprire QuoteNode

Naviga su http://localhost nel tuo browser.

Credenziali di accesso predefinite:

Campo	Valore
Email	`[email protected]`
Password	`Admin123!`

Cambia la password predefinita immediatamente dopo aver effettuato l’accesso (Impostazioni > Il mio profilo > Cambia password).

Cosa è in esecuzione?

Dopo docker compose up, hai 6 container:

Container	Cosa fa	Utilizzo RAM
`postgres`	Archivia tutti i tuoi dati	~256 MB
`backend`	Server API Java, logica di business	~512 MB – 1,5 GB
`gotenberg`	Converte HTML in PDF (basato su Chromium)	~200 MB
`frontend`	Serve l’interfaccia web	~20 MB
`backup-worker`	Esegue i backup pianificati (stessa immagine del backend)	~300 MB
`caddy`	Punto di ingresso: certificati HTTPS, instradamento, header di sicurezza	~20 MB

Totale: circa 1,5 – 2,5 GB di RAM.

Comandi comuni

# Check if all services are running
docker compose ps

# View logs (all services)
docker compose logs -f

# View logs (backend only)
docker compose logs -f backend

# Stop QuoteNode
docker compose down

# Aggiornamento: sostituisci docker-compose.yml con quello del pacchetto della release successiva (vedi la guida all'aggiornamento)

Mantenere al sicuro i tuoi segreti

Il tuo file .env contiene segreti crittografici unici per la tua installazione:

Segreto	Cosa protegge	Se perso
`DB_PASSWORD`	Accesso al database	Recuperabile — reimposta tramite strumenti di amministrazione PostgreSQL
`DB_ENCRYPTION_KEY`	Codici MFA, password SMTP, chiave API FX e tutti i campi PII se `ENCRYPT_PII=true`	Permanentemente illeggibile — non può essere decifrato senza la chiave originale
`TIMING_TOKEN_SECRET`	Token anti-timing-attack	Rigenera — token esistenti invalidati, gli utenti si ri-autenticano
`PUBLIC_LINK_PASSWORD_SESSION_SECRET`	Sessioni dei link pubblici	Rigenera — le sessioni attive scadono, i link continuano a funzionare

Il segreto critico è DB_ENCRYPTION_KEY. Tutti gli altri segreti possono essere rigenerati con un piccolo disagio. Ma DB_ENCRYPTION_KEY cifra i dati a riposo — perderlo significa che quei campi sono andati per sempre.

Ripristino se `.env` è perso

Se perdi il tuo file .env ma hai un backup del database non cifrato (la modalità di backup predefinita):

Crea un nuovo .env con nuovi segreti.
Ripristina il database dal tuo backup.
Tutti i dati di business (clienti, offerte, prodotti, utenti) saranno completamente accessibili.
Solo pochi campi vengono persi: codici MFA (gli utenti si re-iscrivono), password SMTP (reinserire nelle impostazioni), chiave API FX (reinserire nelle impostazioni). Se ENCRYPT_PII=true era abilitato, anche i dati cliente cifrati vengono persi.

Backup

Lo stack include un servizio di backup dedicato (backup-worker), come su un server, così i backup non competono mai per la memoria con l’applicazione web. Configura i backup pianificati come descritto in Backup e ripristino; mantieni WORKER_MEM_LIMIT ad almeno 768m.

Passare da laptop a server

Non pubblicare link da laptop ai clienti. Quando sei pronto per un deployment condiviso o pubblico, scegli uno di questi percorsi:

Installare su un laptop locale

Quando usarlo

Cosa non funzionerà

Prerequisiti

Passo 1 — Creare una directory di progetto

Passo 2 — Creare il file di configurazione

Passo 3 — Verifica il file Docker Compose

Passo 4 — Avviare QuoteNode

Passo 5 — Aprire QuoteNode

Cosa è in esecuzione?

Comandi comuni

Mantenere al sicuro i tuoi segreti

Ripristino se .env è perso

Backup

Passare da laptop a server

Ripristino se `.env` è perso