Installare Chatwoot su VPS con Docker e Traefik
Guida a Chatwoot self-hosted su VPS: Docker Compose, tag fissati, SMTP funzionante, backup di Postgres e upload, oltre ad aggiornamenti sicuri.
Cosa si sta configurando
Per eseguire Chatwoot in self-hosting su un VPS, avvii quattro container: un processo web Rails, un worker in background Sidekiq, PostgreSQL con l'estensione pgvector e Redis. Chatwoot è un help desk open source per l'assistenza clienti. Offre quindi una casella di posta condivisa per il team e un widget di chat per il sito web, su un server sotto il tuo controllo. L'installazione richiede circa venti minuti. Tutto ciò che viene dopo, ovvero recapito della posta, backup, aggiornamenti e dimensionamento, determina se il servizio sarà ancora operativo tra un anno.
Ogni container svolge una sola funzione. Rails pubblica il pannello degli agenti e l'API (application programming interface) del widget. Sidekiq esegue le attività lente: invio delle email, interrogazione periodica dei canali collegati, esecuzione delle regole di automazione e generazione dei report. Postgres archivia conversazioni, contatti, account degli agenti e tutte le impostazioni modificate nel pannello. Redis gestisce le code Sidekiq e il canale pub/sub di ActionCable, che inserisce un nuovo messaggio in un pannello aperto senza ricaricare la pagina. In questo caso Redis non è una cache temporanea, perché perderlo significa perdere i job accodati.
L'immagine Postgres nel file compose upstream è pgvector/pgvector:pg16 anziché l'immagine standard postgres, perché lo schema di Chatwoot abilita l'estensione vector per le funzioni di intelligenza artificiale. Se sostituisci l'immagine con Postgres standard, la prima esecuzione del database si interrompe con ERROR: extension "vector" is not available, perché il file di controllo dell'estensione non è presente in quell'immagine. Usa l'immagine distribuita dall'upstream.
Questa guida presuppone che Docker e un reverse proxy siano già operativi sul server. In caso contrario, inizia da Docker Compose su un VPS e poi torna qui.
Quanta potenza serve per un Chatwoot self-hosted su VPS?
A ottobre 2026, la pagina dei requisiti upstream indica 4 GB di RAM e 4 core CPU come valori minimi e associa questa configurazione a un massimo di 10.000 conversazioni al giorno. Indica 8 GB e 8 core per un massimo di 20.000 conversazioni al giorno. Richiede inoltre almeno 1 GB di swap e ne spiega direttamente il motivo: evitare che la macchina esaurisca la memoria durante un aggiornamento. Prevedi da 5 GB a 10 GB di spazio su disco per Postgres, senza considerare gli upload dei file.
Veniamo al punto. Un VPS da 2 GB avvia Chatwoot e sembra funzionare correttamente con due agenti e una casella di posta poco utilizzata. I problemi si verificano in due situazioni. La prima riguarda Sidekiq, che upstream misura in oltre 1 GB su un server sotto carico. Un picco di email o un'attività di report può quindi portare la macchina oltre il limite di memoria, prima ancora che Rails, Postgres e Redis abbiano utilizzato la propria quota. La seconda è l'aggiornamento, perché db:chatwoot_prepare avvia un nuovo processo Rails per applicare le migrazioni e l'avvio di Rails su questa immagine richiede centinaia di megabyte prima di eseguire qualsiasi attività utile.
Non viene mostrato prima un avviso chiaro. L'out of memory killer del kernel invia SIGKILL al processo selezionato, di solito quello più grande; Docker rileva l'arresto del container e restart: always lo avvia nuovamente. docker compose ps --all mostra quindi un container che continua a riavviarsi o rimane nello stato Exited (137), dove 137 significa terminato dal signal 9. Se ometti --all, un container arrestato non viene elencato. Il solo codice di uscita 137 non dimostra che la causa sia la memoria, perché docker kill invia lo stesso signal. Per confermare la causa, usa sudo dmesg -T | grep -i "killed process", che identifica il processo selezionato dal kernel.
Se 4 GB superano il budget, puoi usare una macchina da 2 GB con 2 GB di swap, accettando tempi di risposta peggiori sotto carico. La swap è un buffer contro l'esaurimento della memoria, non una garanzia. Un picco sufficientemente elevato può quindi causare comunque l'arresto di un container. In ogni caso conviene impostare un limite rigido di memoria per ogni servizio, così il worker non può causare l'arresto del database. Vedi i limiti di memoria in Docker Compose.
Gli upload dei file sono l'elemento che cresce senza un limite definito. Ogni screenshot allegato da un cliente viene salvato nel volume di storage e vi rimane. Monitora quindi docker system df -v invece di presumere che sia il database ad aver riempito il disco.
Scaricare il file Compose e fissare un tag di versione
mkdir -p ~/chatwoot && cd ~/chatwoot
wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
chmod 600 .envIl file appena scaricato contiene image: chatwoot/chatwoot:latest. Modificalo prima di eseguire qualsiasi altra operazione.
services:
base: &base
image: chatwoot/chatwoot:v4.19.1
env_file: .env
volumes:
- storage_data:/app/storagelatest significa che il successivo docker compose pull utilizzerà qualunque versione sia stata pubblicata quella mattina. Potrebbe trattarsi di una versione principale con migrazioni che non hai mai esaminato. Nella pratica, le migrazioni di Chatwoot non sono reversibili. Un aggiornamento accidentale richiede quindi un ripristino dal backup, non un annullamento. Fissa il tag e modificalo intenzionalmente. v4.19.1 era la release corrente il 25 October 2026 e le relative note di rilascio la consigliano per gli ultimi aggiornamenti di sicurezza e i miglioramenti all’hardening; controlla la pagina delle release per conoscere il tag da fissare oggi. Se esegui l’aggiornamento da v4.18.0 o da una versione precedente, leggi prima le note di v4.19.0: Captain V1 è stato ritirato e le installazioni self-hosted che usano le istruzioni per V1 devono eseguire la migrazione a V2 prima dell’aggiornamento. La stessa cautela si applica a qualsiasi applicazione che gestisca un database. Per questo l’hosting autonomo del tracker di allenamento openGym inizia fissando un tag git, anche se si tratta di un’applicazione molto più piccola di questa.
Il servizio base è un’ancora YAML che rails e sidekiq incorporano tramite merge. Modificando il tag in un solo punto, lo cambi per entrambi. Mentre modifichi il file, elimina la riga version: '3' all’inizio. Le versioni moderne di Compose la ignorano e visualizzano the attribute 'version' is obsolete, it will be ignored a ogni comando.
Compila il file .env
Genera prima il secret. Upstream richiede un valore alfanumerico, perché i caratteri speciali possono essere alterati quando il valore passa attraverso una shell o un parser YAML.
head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''Imposta quindi queste chiavi in .env.
SECRET_KEY_BASE=<the 63 characters you just generated>
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
DEFAULT_LOCALE=en
ENABLE_ACCOUNT_SIGNUP=true
POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=<long random string>
POSTGRES_DATABASE=chatwoot
REDIS_URL=redis://redis:6379
REDIS_PASSWORD=<a different long random string>
RAILS_ENV=production
INSTALLATION_ENV=docker
ACTIVE_STORAGE_SERVICE=localPOSTGRES_HOST=postgres e redis://redis:6379 sono i nomi dei servizi Compose, che vengono risolti sulla rete predefinita del progetto. FRONTEND_URL non è un valore ornamentale. Chatwoot lo usa per costruire l’URL dello script del widget e ogni link contenuto nelle email in uscita. Un valore errato produce link per il ripristino della password che puntano a un host non raggiungibile.
Ora considera il problema nel file upstream. Il servizio postgres non legge .env. Contiene un proprio blocco environment con POSTGRES_PASSWORD= vuoto. Di conseguenza, impostare la password soltanto in .env lascia il database senza password e l’applicazione con una password configurata. Imposta il servizio in modo che utilizzi la stessa variabile:
postgres:
image: pgvector/pgvector:pg16
restart: always
volumes:
- postgres_data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=chatwoot
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}Compose legge .env dalla directory del progetto per la sostituzione di ${...}. In questo modo entrambi i componenti ricevono la stessa stringa. Se il valore non è corretto, Rails si interrompe con PG::ConnectionBad: FATAL: password authentication failed for user "postgres".
Un comportamento sorprende quasi tutti: l’immagine Postgres applica POSTGRES_PASSWORD soltanto quando inizializza una directory dati vuota. La modifica successiva del valore non ha effetto, perché initdb non viene eseguito una seconda volta. Se lo stack è già stato avviato, modifica il valore direttamente nel database.
docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"ENABLE_ACCOUNT_SIGNUP=true è temporaneo. Apre il modulo pubblico di registrazione, così puoi creare il primo account. Impostalo su false ed esegui di nuovo docker compose up -d non appena l’account è disponibile. In caso contrario, chiunque trovi l’URL può registrarsi nel tuo help desk. In seguito, gli agenti accedono tramite invito e le relative password vengono gestite soltanto da questa applicazione. Questo approccio è adeguato finché non gestisci una mezza dozzina di servizi e non vuoi più mantenere un elenco di account separato per ciascuno. A quel punto, un identity provider self-hosted come Authentik sostituisce questi elenchi.
.env contiene ora tutti i secret utilizzati da questo stack, in chiaro. Imposta quindi i permessi a mode 600 e non inserirlo in git. Come Compose legge i file env e dove possono fuoriuscire i secret descrive i principali rischi, inclusa la differenza tra env_file e environment.
Metti Chatwoot dietro il tuo Traefik esistente
Non creare un secondo reverse proxy per una sola applicazione. Se Traefik gestisce già la terminazione TLS (transport layer security) per altri container su questo server, Chatwoot può utilizzarlo tramite un blocco di label. Se non hai ancora questa configurazione, impostala una sola volta seguendo Traefik davanti a più applicazioni Docker Compose, quindi torna qui.
Mantieni il file docker-compose.yaml dell’upstream il più possibile invariato, così in seguito potrai confrontarlo con una copia più recente, e inserisci le modifiche in un file di override. Compose esegue automaticamente il merge di docker-compose.override.yaml; suddividere Compose in più file spiega le regole di merge.
services:
rails:
networks:
- default
- proxy
labels:
- "traefik.enable=true"
- "traefik.http.routers.chatwoot.rule=Host(`support.example.com`)"
- "traefik.http.routers.chatwoot.entrypoints=websecure"
- "traefik.http.routers.chatwoot.tls.certresolver=letsencrypt"
- "traefik.http.services.chatwoot.loadbalancer.server.port=3000"
networks:
proxy:
external: trueUsa i nomi che hai scelto per l’entrypoint e il certresolver. Il container deve trovarsi sulla stessa rete Docker di Traefik, come specificato dall’istruzione proxy, e deve restare anche su default, altrimenti perde l’accesso a Postgres e Redis. Questa è la seconda riga che viene spesso dimenticata.
Lascia invariato il blocco ports:. Upstream lo associa a 127.0.0.1:3000, che accetta connessioni solo sull’interfaccia di loopback; quindi non è raggiungibile da Internet e resta utile per i test eseguiti dall’interno del server con curl -I http://127.0.0.1:3000.
Il dashboard dell’agente mantiene aperta una connessione websocket a /cable per la distribuzione in tempo reale dei messaggi. Traefik inoltra l’upgrade HTTP senza configurazioni aggiuntive, quindi non devi aggiungere nulla. Se in seguito metti una CDN o un altro proxy davanti a Traefik, abilita i websocket anche su quel componente: il sintomo è un dashboard che si carica normalmente, mentre i nuovi messaggi compaiono soltanto dopo un aggiornamento manuale.
Inizializzare il database e avviare lo stack
Avviare prima i servizi dati e attendere il completamento della prima esecuzione di Postgres.
docker compose up -d postgres redis
docker compose logs postgres | tail -n 5Attendere database system is ready to accept connections. Quindi creare lo schema.
docker compose run --rm rails bundle exec rails db:chatwoot_prepareQuesto comando crea il database se non esiste, quindi carica lo schema e i dati seed predefiniti. Stampa le righe delle migrazioni e termina correttamente. Se continua a stampare postgres:5432 - no response, l’entrypoint sta attendendo un database che non accetta ancora connessioni. Al primo avvio, di solito significa che initdb è ancora in esecuzione. Attendere, leggere i log di Postgres, quindi eseguire nuovamente il comando. Se si interrompe sull’estensione vector, l’immagine pgvector è stata sostituita con un’immagine standard di Postgres.
docker compose up -d
docker compose ps
docker compose logs --tail 30 railsTutti e quattro i container dovrebbero riportare Up e il log di Rails dovrebbe terminare con una riga di Puma in ascolto su http://0.0.0.0:3000. Quindi verificare il percorso pubblico:
curl -sI https://support.example.com | head -n 1HTTP/2 200 indica che l’intera catena funziona. Un errore 404 da Traefik indica che la regola del router non corrisponde, di solito a causa di un errore di battitura nel nome host. Un errore 502 indica che Traefik ha trovato il router, ma non riesce a raggiungere il container. Nella quasi totalità dei casi manca la rete proxy oppure loadbalancer.server.port non è impostato su 3000.
Aprire l’URL, creare l’account su /app/auth/signup, quindi impostare ENABLE_ACCOUNT_SIGNUP=false ed eseguire docker compose up -d per chiudere il modulo.
Perché il ripristino delle password e le conversazioni email non funzionano senza SMTP
Chatwoot senza le impostazioni SMTP (simple mail transfer protocol) è un help desk che non può inviare email, e questo interrompe più delle sole notifiche. Il ripristino delle password non funziona più, quindi un amministratore che rimane bloccato fuori dall’account non può rientrare. Anche gli inviti agli agenti non funzionano, perché un invito viene inviato tramite email. Le risposte ai clienti nelle conversazioni email non vengono più inviate, quindi la conversazione procede in una sola direzione. Questo è il passaggio che molti saltano e che poi scoprono nel momento peggiore.
Il meccanismo è semplice. Se SMTP_ADDRESS non è impostato, Chatwoot configura ActionMailer per la consegna tramite sendmail. La documentazione upstream descrive questa modalità come configurazione Postfix, predefinita dalla versione v2.12.0, e nelle relative istruzioni installa Postfix sul server tramite sudo apt install -y postfix. Questa configurazione Docker non lo fa, quindi non esiste un server di posta configurato a cui il sistema di consegna possa affidare i messaggi. L’invio avviene da un job in background, quindi qualsiasi errore prodotto dalla consegna finisce nel log di Sidekiq e non nel log di Rails. Nel frattempo, la persona che fa clic su "password dimenticata" vede una conferma rassicurante, ma non riceve nulla.
MAILER_SENDER_EMAIL=Support <support@example.com>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=support@example.com
SMTP_PASSWORD=<the relay password>
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=trueUsa la porta 587 con STARTTLS. La connessione viene aperta in testo semplice e aggiornata a una connessione cifrata prima dell’autenticazione. Molti provider VPS bloccano per impostazione predefinita la porta 25 in uscita per limitare lo spam. Alla data dell’8 novembre 2026, Hetzner blocca per impostazione predefinita le porte 25 e 465 sui cloud server, con un blocco applicato per account, mentre Vultr blocca la porta 25 su tutte le nuove Compute Instances. Entrambi valutano caso per caso le richieste di sblocco. Hetzner richiede almeno un mese di anzianità come cliente e il pagamento della prima fattura prima di consentire l’invio di una richiesta di aumento del limite. Nessuno dei due blocca la porta 587, quindi un relay sulla porta 587 funziona dal primo avvio, senza aprire ticket e senza attendere. SMTP_DOMAIN è il dominio che il server annuncia durante la conversazione SMTP, e alcuni relay rifiutano un valore non corrispondente.
Applica le impostazioni e monitora il worker:
docker compose up -d rails sidekiq
docker compose logs -f sidekiqAvvia il ripristino della password dalla pagina di accesso. Quando la consegna funziona, nel log di Sidekiq il job del mailer termina normalmente. In caso di errore compare la classe dell’eccezione, quindi Sidekiq ritenta con un intervallo crescente. Per questo un relay non funzionante produce lo stesso errore ogni pochi minuti, per diverse ore.
Due rifiuti sono comuni e nessuno dei due indica un bug di Chatwoot. 535 Authentication failed significa che l’autenticazione non è riuscita. Controlla le credenziali, verifica che l’autenticazione SMTP sia abilitata e accertati che una policy di accesso non la blocchi. Le sole credenziali corrette non escludono questo errore. Alcuni provider richiedono una password per applicazioni invece della password dell’account. 550 Sender address rejected significa che il server ha rifiutato l’indirizzo del mittente. Leggi la risposta completa prima di modificare MAILER_SENDER_EMAIL. I permessi o la verifica del mittente sono una possibile causa, ma 550 5.7.27 Sender address rejected: Domain does not accept mail indica un dominio del mittente con un record MX nullo.
La ricezione delle email in una conversazione è un’attività separata. Per l’inoltro tramite l’ingress di Chatwoot, sono necessari MAILER_INBOUND_EMAIL_DOMAIN e RAILS_INBOUND_EMAIL_SERVICE, oltre a un server di posta che consegni i messaggi in arrivo a Chatwoot. In alternativa, puoi collegare una casella tramite IMAP, anche usando OAuth di Google o Microsoft, senza configurare questo percorso di inoltro. Noleggiare un relay è la soluzione più rapida. Se invece vuoi gestire internamente l’intero percorso della posta, gestire un server di posta autonomo con Mailcow spiega cosa comporta realmente questa scelta.
Cosa sottoporre a backup e come verificare che il ripristino funzioni
Un backup di Chatwoot comprende quattro elementi. Se ne salti anche solo uno, il ripristino diventa una ricostruzione.
- Il database Postgres, che contiene conversazioni, contatti, account degli agenti e tutte le impostazioni.
- Il volume
storage_data, perchéACTIVE_STORAGE_SERVICE=localscrive i file caricati su disco e conserva in Postgres soltanto una riga di riferimento. - Il file
.env, perché contieneSECRET_KEY_BASEe le chiaviACTIVE_RECORD_ENCRYPTION_*. - I file compose, perché registrano il tag esatto dell'immagine compatibile con lo schema del database.
Se ripristini solo il database, tutte le conversazioni tornano disponibili con gli allegati non funzionanti, perché le righe puntano a file che non sono più presenti su disco.
cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump-T è importante. Senza questa opzione Compose alloca un terminale pseudo-TTY, che modifica i byte di nuova riga nel flusso. Il risultato è un file di dump che pg_restore rifiuta. -Fc indica il formato custom, che comprime i dati e consente a pg_restore di lavorare in modo selettivo.
docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
tar czf /backup/storage-$(date +%F).tgz -C /data .Il nome del volume è il nome della directory del progetto seguito da _storage_data. Confermalo con docker volume ls | grep storage_data prima di eseguire quel comando, perché Docker crea un volume vuoto invece di segnalare un errore quando indichi un volume inesistente. Otterresti un archivio valido ma vuoto, senza alcun errore. Controlla poi le dimensioni con ls -lh storage-*.tgz.
Ora entrambi i file si trovano sullo stesso disco dei dati che dovrebbero proteggere. Questo non offre alcuna protezione. Copiali fuori dal server e cifrali, perché un dump del database contiene in chiaro tutti i messaggi dei clienti. Backup cifrati fuori sede con restic descrive la pianificazione e la gestione della conservazione.
Esegui il test di ripristino prima di averne bisogno
Ripristina i dati su un secondo VPS, non sul server in produzione. Copia .env, i file compose e entrambi gli archivi, quindi esegui:
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U postgres -d chatwoot --clean --if-exists < db-2026-08-10.dump
docker run --rm -v chatwoot_storage_data:/data -v "$PWD":/backup alpine \
sh -c 'rm -rf /data/* && tar xzf /backup/storage-2026-08-10.tgz -C /data'
docker compose up -d--clean --if-exists elimina gli oggetti esistenti prima del caricamento. Usalo quindi solo con un database che sei disposto a perdere. Accedi poi all'applicazione e apri una conversazione con un allegato. Se l'elenco dei messaggi viene caricato e il file viene scaricato, il backup è valido.
Un ripristino con un valore SECRET_KEY_BASE diverso invalida tutti i cookie di sessione, quindi tutti gli utenti vengono disconnessi. Un ripristino con chiavi ACTIVE_RECORD_ENCRYPTION_* diverse è ancora più problematico: Chatwoot non può decifrare le colonne che contengono le credenziali dei canali e genera ActiveRecord::Encryption::Errors::Decryption. Per questo .env è incluso nell'elenco dei dati da sottoporre a backup.
Come aggiornare Chatwoot a un nuovo tag
L’ordine è più importante dei singoli comandi.
- Leggere le note di rilascio comprese tra il tag attuale e quello di destinazione, verificando la presenza di passaggi manuali obbligatori.
- Creare un nuovo dump del database e un archivio dello storage, quindi verificare che le dimensioni dei file siano plausibili.
- Modificare il tag dell’immagine nel servizio
baseindocker-compose.yaml. - Scaricare la nuova immagine, arrestare lo stack, eseguire le migration e riavviare lo stack.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose imagesScaricare l’immagine prima di eseguire le migration, perché le migration devono essere eseguite dalla nuova immagine: quella precedente non contiene i nuovi file delle migration. Arrestare lo stack prima delle migration, perché il codice precedente e il nuovo schema non sono compatibili. Un processo Rails precedente ancora in esecuzione può quindi generare errori o scrivere righe che il nuovo schema non accetta. L’arresto libera inoltre la memoria necessaria alle migration. Questo è il motivo per cui upstream richiede lo swap.
docker compose images mostra il tag effettivamente in esecuzione in ogni container. In questo modo è possibile individuare il caso in cui il tag è stato modificato ma l’immagine non è stata scaricata.
La distanza tra i tag che è possibile coprire in un solo aggiornamento dipende dall’età dell’installazione. Se l’installazione è indietro di una o due release, esaminare le note di rilascio comprese tra il tag attuale e quello di destinazione, impostare il tag di destinazione ed eseguire una sola volta i passaggi precedenti. Solo per installazioni molto vecchie la guida Docker di upstream indica di eseguire l’aggiornamento in modo iterativo attraverso i tag intermedi delle immagini, invece di passare direttamente all’immagine più recente. In questo caso, ripetere la modifica del tag, il download dell’immagine e il passaggio prepare per ogni tag intermedio, perché upstream richiede db:chatwoot_prepare dopo ogni aggiornamento.
Se Rails viene avviato prima dell’esecuzione delle migration, rifiuta di fornire il servizio e registra ActiveRecord::PendingMigrationError: Migrations are pending. Con restart: always impostato, il container entra quindi in un ciclo di riavvio, perciò docker compose ps mostra un uptime che si azzera ogni pochi secondi. Eseguire il passaggio prepare per risolvere il problema.
Per eseguire il rollback, ripristinare il vecchio tag e il dump. Non esiste un percorso di reverse migration affidabile. Questo è il motivo del passaggio 2.
Modalità di errore e stringhe visualizzate
502 Bad Gateway da Traefik. Il router ha trovato una corrispondenza, ma il backend non ha risposto. Verifica che docker compose ps mostri rails come Up, quindi esegui docker network inspect proxy e conferma che il container rails compaia nell’elenco dei container. Un container non collegato è invisibile a Traefik: la richiesta corrisponde a un router, ma poi non raggiunge alcuna destinazione.
La dashboard viene caricata, ma per visualizzare i nuovi messaggi è necessario aggiornare la pagina. La connessione WebSocket a /cable non passa oppure FRONTEND_URL non corrisponde all’indirizzo mostrato nella barra del browser. Una mancata corrispondenza indica che la pagina tenta di aprire una connessione WebSocket verso un’origine diversa, che il browser blocca.
FATAL: password authentication failed for user "postgres". La password in .env e quella memorizzata nel volume dati di Postgres sono diverse. Correggi il problema con ALTER USER all’interno del container in esecuzione, perché modificare nuovamente .env non cambia un database già inizializzato.
NOAUTH Authentication required. Redis è in esecuzione con --requirepass, ma l’applicazione si è connessa senza password: REDIS_PASSWORD manca da .env oppure non è stata acquisita. Verifica direttamente la password richiesta da Redis con docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping', che dovrebbe restituire PONG. Gli apici singoli sono importanti: fanno espandere la variabile all’interno del container, che legge .env, invece che nella shell locale, dove in genere è vuota.
I container terminano con il codice 137. Si tratta di SIGKILL. Su un server di piccole dimensioni, il responsabile più comune è il killer del kernel per esaurimento della memoria, ma docker kill invia lo stesso segnale. Controlla quindi sudo dmesg -T | grep -i "killed process" prima di attribuire il problema alla memoria. Se la memoria è effettivamente insufficiente, aggiungi swap, imposta limiti di memoria per ogni servizio oppure passa a un piano più grande.
FAQ
Quanta RAM richiede un VPS Chatwoot self-hosted?
A ottobre 2026, il progetto upstream richiede almeno 4 GB di RAM e 4 core CPU, con una capacità dichiarata fino a 10,000 conversazioni al giorno, e 8 GB con 8 core per arrivare a 20,000. Aggiungete almeno 1 GB di swap, perché durante un aggiornamento viene avviato un secondo processo Rails per applicare le migrazioni ed è in quel momento che le macchine con poche risorse esauriscono la memoria. Un VPS da 2 GB si avvia e funziona per un paio di agenti, ma il solo Sidekiq può superare 1 GB sotto carico. Durante i periodi di attività intensa e gli aggiornamenti, quindi, prevedete l'arresto dei container con codice di uscita 137.
Perché le email di reimpostazione della password di Chatwoot non arrivano mai?
Perché non è impostato alcun SMTP_ADDRESS, quindi Chatwoot ricorre alla consegna tramite sendmail. Questa modalità presuppone un server Postfix installato sull'host, che in questa configurazione Docker non è presente. Il job viene eseguito in Sidekiq, quindi ogni errore di consegna finisce nel log di Sidekiq, mentre il browser continua a mostrare un messaggio di operazione riuscita. Impostate SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD e MAILER_SENDER_EMAIL in .env, riavviate i servizi rails e sidekiq, quindi monitorate docker compose logs -f sidekiq mentre avviate una reimpostazione.
Che cosa devo includere nel backup per ripristinare Chatwoot?
Il database Postgres, il volume Docker storage_data, il file .env e i file compose. Il solo database non è sufficiente, perché i file caricati risiedono nel volume, mentre Postgres conserva soltanto i relativi riferimenti. Un ripristino del solo database produce quindi conversazioni con allegati non accessibili. .env è importante perché un SECRET_KEY_BASE diverso disconnette tutti gli utenti, mentre chiavi ACTIVE_RECORD_ENCRYPTION_* diverse rendono illeggibili le colonne cifrate.
Come posso aggiornare Chatwoot senza danneggiare il database?
Eseguite un backup, leggete le note di rilascio comprese tra il vostro tag e quello di destinazione, modificate il tag dell'immagine nel file compose, quindi eseguite docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare e docker compose up -d. Eseguite prima il pull, perché le migrazioni devono essere applicate dalla nuova immagine. Arrestate prima lo stack, perché il vecchio codice utilizzato con uno schema nuovo genera errori. Solo un'installazione molto vecchia deve passare attraverso tag intermedi dell'immagine invece di passare direttamente all'ultima versione. In questo caso, eseguite il passaggio di preparazione dopo ciascun tag.
Posso usare l'immagine postgres standard invece di pgvector?
No. Lo schema di Chatwoot abilita l'estensione vector, quindi l'immagine postgres standard fallisce durante db:chatwoot_prepare con ERROR: extension "vector" is not available, perché il file di controllo dell'estensione non è presente in quell'immagine. Mantenete pgvector/pgvector:pg16 dal file compose upstream oppure utilizzate un'altra immagine che includa pgvector per la vostra versione principale di Postgres.