Risoluzione problemi installazione

La maggior parte dei problemi di installazione derivano da mismatch di URL, SMTP mancante, porte bloccate o segreti persi. Inizia dall’URL visibile nel tuo browser e procedi verso l’interno.

I link pubblici si aprono sul mio computer ma non per i clienti

Controlla quale URL è stato copiato o inviato.

• http://localhost/... funziona solo sulla stessa macchina.
• http://192.168.x.x/... funziona solo nella LAN o VPN. La VPN può essere un ponte valido per i team interni, ma non è una strategia di link cliente pubblico.
• https://crm.example.com/... funziona pubblicamente solo quando DNS, HTTPS, proxy e firewall sono corretti.

Per i link cliente pubblici, effettua il deploy con un dominio pubblico usando Server pubblico Ubuntu o Coolify.

Il browser mostra errori CORS

CORS_ALLOWED_ORIGINS deve corrispondere esattamente all’origine del browser. Queste sono origini diverse:

https://crm.example.com
https://www.crm.example.com
http://crm.example.com
https://crm.example.com:8443

Correggi la variabile, ridistribuisci e riprova in una nuova sessione browser.

L’email non viene consegnata

Controlla prima questi elementi:

• SMTP_HOST e SMTP_PORT sono corretti.
• SMTP_AUTH=true quando il tuo provider richiede autenticazione.
• SMTP_STARTTLS=true per la porta 587.
• SMTP_USERNAME e SMTP_PASSWORD sono validi.
• Il provider consente l’accesso SMTP/app-password.
• NOTIFICATIONS_EMAIL_ENABLED=true quando le email di notifica devono essere inviate.

La condivisione manuale del link pubblico e il download PDF possono comunque funzionare senza SMTP.

I link delle preferenze di notifica sono errati

Imposta:

NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences

Non lasciarlo che punti a localhost in un deployment pubblico.

I container Docker sono unhealthy

Esegui:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f gotenberg

Cause comuni:

• PostgreSQL si sta ancora avviando.
• DB_PASSWORD differisce tra PostgreSQL e backend.
• DB_ENCRYPTION_KEY è mancante o malformato.
• Gotenberg non è healthy, quindi la generazione PDF non può avviarsi.
• Le porte host 80/443 sono già usate da un altro servizio.

Dopo aver corretto la configurazione, riavvia il servizio interessato o lo stack:

docker compose restart backend
docker compose up -d

Il mio IP è bloccato — non riesco ad accedere

Ci sono due cause comuni: la lista IP consentiti ha bloccato l’accesso oppure la protezione anti-brute-force ha bloccato il tuo IP dopo troppi tentativi di accesso falliti.

Blocco dalla lista IP consentiti

QuoteNode ha una lista di IP consentiti configurabile in Impostazioni > Sicurezza > Lista IP consentiti (o tramite la variabile SECURITY_IP_WHITELIST). Quando è attiva, protegge l’intera superficie di amministrazione — comprese le schermate di accesso e 2FA — quindi un indirizzo escluso riceve 403 IP_NOT_ALLOWED e non può nemmeno accedere. (Gli health check e i link pubblici alle offerte per i clienti restano raggiungibili.)

Prima attendi due minuti se l’hai appena modificata nell’app. Un’attivazione o un restringimento nell’app è protetto dal blocco: deve essere riconfermato dalla tua sessione entro una breve finestra (120 s predefiniti) e, se il tuo indirizzo attuale non è incluso, la lista torna automaticamente a quella precedente. Un autoblocco accidentale dalla schermata Sicurezza si risolve quindi da solo — attendi e riprova. (Questa rete di sicurezza non si applica alla variabile SECURITY_IP_WHITELIST, che viene applicata all’avvio.)

Recupero (override dell’operatore): se sei ancora bloccato — es. una SECURITY_IP_WHITELIST dell’operatore, una lista memorizzata non valida o non puoi attendere — aggiungi questa variabile all’ambiente del container backend (.env o sezione environment: nel docker-compose) e riavvia:

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

Questo disabilita completamente la lista consentiti e permette l’accesso. Una volta dentro, correggi la lista in Impostazioni > Sicurezza, poi rimuovi SECURITY_IP_WHITELIST_FORCE_DISABLE e riavvia di nuovo.

Non lasciare SECURITY_IP_WHITELIST_FORCE_DISABLE=true in produzione. Disabilita l’intero controllo accessi per IP.

Blocco dalla protezione anti-brute-force

QuoteNode blocca gli indirizzi IP dopo troppi tentativi di accesso falliti in un’ora:

Soglia	Fallimenti in 1 h	Effetto
Soft	10	Ritardo progressivo (1 s per tentativo aggiuntivo, max. 30 s)
Blocco temporaneo	20	Bloccato per 5 minuti
Blocco permanente	50	Bloccato fino allo sblocco manuale

Come sbloccare:

1. Pannello admin — un altro amministratore apre Impostazioni > Dashboard Sicurezza > IP bloccati e clicca Sblocca.
2. Attendere — i blocchi temporanei scadono dopo SECURITY_TEMP_LOCK_MINUTES (5 minuti predefiniti). I blocchi permanenti non scadono da soli.
3. Alzare temporaneamente le soglie se sei bloccato e nessun altro admin può aiutare. Aggiungi al .env, riavvia, accedi, poi rimuovi:

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Ripristina i valori predefiniti dopo aver recuperato l’accesso.

Blocchi IP dei link pubblici

Il rate limiter dei link pubblici blocca gli indirizzi IP che superano i limiti di tentativi. Questi blocchi sono in memoria e scadono dopo PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (60 minuti predefiniti) o dopo un riavvio del backend.

Il certificato HTTPS non viene emesso

Per i deployment pubblici:

• Il DNS deve puntare al server di deployment.
• Le porte 80 e 443 devono essere raggiungibili da internet.
• Solo un proxy dovrebbe terminare HTTPS per lo stesso dominio.
• In Coolify, assegna il dominio al servizio frontend.

Ho perso .env

Se hai perso .env, fermati e valuta prima di ruotare i valori.

• DB_PASSWORD può solitamente essere reimpostato con accesso amministrativo PostgreSQL.
• TIMING_TOKEN_SECRET e PUBLIC_LINK_PASSWORD_SESSION_SECRET possono essere rigenerati, ma le sessioni/token esistenti potrebbero scadere.
• DB_ENCRYPTION_KEY è critico. Senza la chiave originale, i valori cifrati non possono essere decifrati.
• Se la cifratura PII e abilitata, i campi cliente/contatto cifrati dipendono da DB_ENCRYPTION_KEY.

Ripristina .env dal backup ogniqualvolta possibile.

Ripristino se .env è perso ma esiste un backup del database

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

Se i tuoi backup sono cifrati con age (impostazione predefinita), hai bisogno del file di identità age dal tuo kit di recupero per decifrarli. Consulta la guida Backup e Ripristino.

Password admin dimenticata

Usa un percorso di recupero non distruttivo:

1. Se SMTP è configurato, usa la pagina di accesso: Password dimenticata?
2. Se un altro amministratore può ancora accedere, apri Utenti nel pannello admin e reimposta la password.
3. Se nessun amministratore riesce ad accedere e il flusso di reset via email non è disponibile, ripristina l’accesso da un backup funzionante o usa la tua procedura di manutenzione interna.

docker compose down -v non e una procedura di reset della password. Elimina tutti i dati — utenti, offerte, clienti, impostazioni e backup. Usalo solo per ambienti di test usa-e-getta.

La verifica della licenza fallisce

Per i deployment reali, mantieni:

LICENSE_SKIP_SIGNATURE_CHECK=false

Se una licenza valida fallisce comunque, controlla che il deployment abbia la versione app attesa e un orologio di sistema sincronizzato con NTP. Conferma che la licenza corrisponda all’edizione/versione distribuita, quindi contatta il supporto o sostituisci il file di licenza tramite il percorso operatore documentato. Non impostare il bypass della firma a true come workaround di produzione.