Installare con Coolify

Coolify è il percorso di deployment raccomandato in public beta quando vuoi HTTPS gestito, deploy basati su Git, health check dei container e un’interfaccia web per le variabili d’ambiente.

Impostazioni del repository

Crea un’applicazione dal repository di QuoteNode e usa queste impostazioni:

Impostazione	Valore
Build Pack	Docker Compose
Base Directory	/
Docker Compose Location	/infra/docker-compose.coolify.yml
Public domain	configura solo su frontend, ad esempio https://crm2.prodata.cc
Backend domain	lascia vuoto a meno che tu non sappia perché deve essere pubblico
Backup worker domain	lascia vuoto
Gotenberg domain	lascia vuoto

Il proxy di Coolify dovrebbe instradare il dominio verso il servizio frontend. Il backend, il backup worker, PostgreSQL e Gotenberg restano interni. Non assegnare domini pubblici a backend, backup-worker, postgres o gotenberg; esporre direttamente quei servizi aumenta la superficie di attacco e può aggirare il confine previsto tra frontend/proxy.

Comandi di build e avvio

Per i deployment Coolify normali, lascia vuoti i comandi personalizzati a meno che la tua installazione Coolify non li richieda. Se Coolify mostra comandi generati, potrebbero apparire così:

docker compose build
docker compose up -d

Non fare affidamento sulle impostazioni Nixpacks Node per il runtime di QuoteNode in questa modalità. I Dockerfile e il file Compose definiscono il runtime.

Switch avanzati

Valori predefiniti consigliati:

Opzione Coolify	Raccomandazione
Inject Build Args to Dockerfile	abilitato
Auto Deploy	abilitato per staging, opzionale per produzione
Git Submodules	solo se il checkout ne ha bisogno
LFS	solo se il repo usa asset Git LFS
Shallow Clone	accettabile
Proxy Force HTTPS	abilitato
Enable Gzip Compression	abilitato
Strip Prefixes	lascia il default a meno di non deployare sotto un path prefix

Rivedi i Watch Paths prima di usarli. Un path come services/api/** è stale per questo layout di repository; il codice backend risiede sotto backend/** e il codice frontend sotto frontend/**.

Variabili d’ambiente richieste

Imposta queste nell’interfaccia ambiente di Coolify:

DB_NAME=quotenode
DB_USERNAME=quotenode
DB_PASSWORD=<random-32+-characters>
DB_URL=jdbc:postgresql://postgres:5432/quotenode
DB_ENCRYPTION_KEY=<64-hex-characters>
TIMING_TOKEN_SECRET=<random-32+-characters>
PUBLIC_LINK_PASSWORD_SESSION_SECRET=<random-32+-characters>
CORS_ALLOWED_ORIGINS=https://<frontend-domain>
NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences
PDF_ENABLED=true
NOTIFICATIONS_ENABLED=true
NOTIFICATIONS_EMAIL_ENABLED=false
FEATURE_2FA_ENABLED=true
BACKUP_ENABLED=false
BACKUP_CRON=0 0 2 * * *
SECURITY_BOT_DETECTION_ENABLED=true
# L'IP del client viene rilevato automaticamente dietro proxy interni e CDN (incluso Cloudflare) — lascia vuoto.
# Imposta solo per un proxy insolito il cui peer di trasporto è un indirizzo PUBBLICO da considerare attendibile (IP/CIDR o hostname).
SECURITY_TRUSTED_PROXIES=
GEOIP_ENABLED=false
LOG_LEVEL=INFO
VITE_RELEASE_CHECK_ENABLED=true
VITE_RELEASE_MANIFEST_URL=https://quotenode.dev/releases/latest.json

Se la consegna email e abilitata, imposta anche:

NOTIFICATIONS_EMAIL_ENABLED=true
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME[email protected]
SMTP_PASSWORD=<smtp-password>
SMTP_AUTH=true
SMTP_STARTTLS=true

BACKUP_CRON usa il formato cron a sei campi di Spring, quindi 0 0 2 * * * significa alle 02:00 ogni giorno.

Alcuni template operatore includono anche SERVICE_URL_FRONTEND=https://<frontend-domain>. Mantienilo allineato con il dominio frontend se il tuo processo di deployment lo usa. Il file compose Coolify attuale non consuma direttamente questa variabile; l’accesso del browser e controllato da CORS_ALLOWED_ORIGINS, e i link delle preferenze di notifica usano NOTIFICATIONS_PUBLIC_PREFERENCES_URL.

Metadati di rilascio

I deployment da sorgente Coolify possono lasciare APP_VERSION vuoto a meno che non si stia costruendo un tag di rilascio. Imposta i metadati quando la tua CI o pipeline Coolify possono fornirli:

# APP_VERSION puo essere omesso per i deployment da sorgente finche non viene costruito un tag di rilascio.
APP_CHANNEL=beta
APP_COMMIT_SHA=<commit-sha>
APP_BUILD_TIME=<iso-time>
APP_BUILD_NUMBER=<build-number>
APP_SOURCE_REF=<branch-or-tag>
APP_IMAGE_TAG=<image-tag>

Usa APP_CHANNEL=alpha, beta, rc, dev o stable in base al rilascio che distribuisci.

Sicurezza della licenza

Per deployment beta reali e pubblici:

LICENSE_SKIP_SIGNATURE_CHECK=false

Impostalo esplicitamente a false per i deployment beta reali. Il file compose defaulta a false quando la variabile è omessa, ma gli operatori di produzione non dovrebbero fare affidamento sull’ambiguità. Impostarlo a true disabilita la verifica dell’autenticità della licenza e può violare i termini di licenza; usalo solo in ambienti di sviluppo locali usa e getta.

Controlli post-deploy

Dopo che il deployment è healthy in Coolify:

1. Apri https://<frontend-domain>/health.
2. Apri il dominio frontend in un browser.
3. Accedi con l’amministratore seedato solo per il primo bootstrap, poi cambia la password.
4. Crea un’offerta.
5. Genera un PDF.
6. Crea e apri un link pubblico.
7. Se l’email è abilitata, verifica SMTP e i link delle preferenze di notifica.
8. Controlla l’area admin licenza/versione per la versione corrente e lo stato delle notifiche di rilascio.

Problemi comuni di Coolify

• I link pubblici falliscono quando CORS_ALLOWED_ORIGINS non corrisponde esattamente all’origine del browser.
• I link delle preferenze di notifica falliscono quando NOTIFICATIONS_PUBLIC_PREFERENCES_URL punta ancora a localhost o a un vecchio dominio.
• Gotenberg non dovrebbe ricevere un dominio pubblico; e un servizio PDF interno.
• L’HTTPS gestito da Coolify richiede che il dominio frontend risolva sul server Coolify.
• Se i metadati di build sono vuoti, l’applicazione può comunque funzionare, ma la visualizzazione della versione admin potrebbe mostrare meno dettagli di rilascio.