Instalação do Chatwoot: Docker, VPS e os 4 pontos onde todo mundo trava

Há um relato público no GitHub do Chatwoot que resume a distância entre o tutorial e a vida real: um usuário descrevendo uma a duas semanas tentando subir a plataforma via Docker, com filas do Sidekiq travando, widget devolvendo erros 404 e 500 e e-mail que não saía (discussão #8954). Ele conseguiu no final, e compartilhou a configuração que funcionou. A história tem as duas morais certas: a instalação do Chatwoot é perfeitamente possível, e ela é um projeto de infraestrutura, não um next-next-finish.

TL;DR: Instalar o Chatwoot em VPS via Docker envolve: máquina com no mínimo 4 GB de RAM, Docker Compose com os serviços Rails, Sidekiq, PostgreSQL e Redis, variáveis de ambiente corretas (URL, SMTP, storage), migração de banco e proxy reverso com SSL. Os pontos onde as instalações travam, pelos relatos públicos da comunidade: Sidekiq sem processar filas (e-mails e automações param), SMTP mal configurado, assets do widget quebrando atrás do proxy e a migração de banco esquecida após updates. Reserve meio dia com método, não meia hora com sorte.

Antes de começar: a máquina certa

O Chatwoot roda Rails + PostgreSQL + Redis + Sidekiq, e cada peça quer memória. O piso confortável para equipe pequena: VPS dedicada com 4 GB de RAM e 2 vCPUs, sem dividir a máquina com outras aplicações pesadas. Abaixo disso, os sintomas são os clássicos: instalação que passa e operação que engasga. E o teto chega antes do que parece: a issue #3425 do repositório registra instância “muito lenta com 10 a 15 usuários”, lembrete público de que carga real pede dimensionamento real. Os números completos estão em requisitos e custo do self-host.

A instalação em seis passos (com os detalhes que travam)

1. Docker e Compose atualizados na VPS, com usuário não-root configurado e firewall liberando 80/443.
2. Compose oficial: parta do docker-compose do projeto, que sobe Rails (web), Sidekiq (worker), PostgreSQL e Redis como serviços separados. O detalhe que resolveu o caso da discussão #8954: Rails e Sidekiq em containers separados, cada um com sua responsabilidade, nunca um processo só fingindo ser os dois.
3. Variáveis de ambiente: FRONTEND_URL com o domínio definitivo (mudar depois dá trabalho), credenciais de banco, SECRET_KEY_BASE gerada, e SMTP completo. SMTP é o campeão de configuração adiada: sem ele, convites de agente e notificações morrem em silêncio.
4. Prepare o banco: rode a preparação/migração de banco antes do primeiro acesso. Guarde este comando na memória da operação: ele volta a cada atualização, e esquecê-lo tem consequência documentada (a discussão #5518 registra o caso clássico de “Account Suspended” após update, resolvido justamente rodando as migrações pendentes).
5. Proxy reverso com SSL: Nginx ou Caddy na frente, certificado válido, websockets habilitados (sem eles, a atualização em tempo real das conversas quebra de formas confusas).
6. Teste o circuito completo: criar conta, enviar e-mail de convite, plugar o widget numa página de teste, abrir conversa, responder. Só depois disso conecte canais reais.

Os quatro pontos de travamento clássicos

Sidekiq parado. Tudo parece funcionar, mas e-mail não sai e automação não roda: a fila não está sendo processada. Verifique o container do worker e a conexão dele com o Redis; é o primeiro lugar para olhar quando “funciona, mas não acontece nada”.

Widget com 404/500. Assets não compilados ou proxy sem os headers corretos. O sintoma aparece no site do cliente, o que o torna o mais constrangedor da lista.

E-mail que não envia. SMTP incompleto, porta bloqueada pelo provedor da VPS ou remetente sem autenticação. Teste com um e-mail real durante a instalação, não na primeira crise.

Atualização que quebra. Nova versão baixada, migração não rodada, edge cases de release (a v2.16.0 tem registro público de quebra de API e e-mail na discussão #6917). O método de atualização segura merece artigo próprio: como atualizar o Chatwoot sem quebrar.

Conheça o CRM white label →

Instalou. Agora começa a segunda conta

A instalação é o pedágio de entrada; a operação é a estrada. Backup do banco agendado e testado, monitoramento com alerta, rotina de atualização, e alguém nomeado para o incidente de sábado: sem esses quatro, a instância saudável de hoje é a surpresa de amanhã. É a parte da conta que o “grátis” não mostra no início, e que dimensionamos em quanto custa o Chatwoot de verdade. Para quem conclui que o pedágio vale a pena, o guia completo do Chatwoot mapeia o resto do caminho; para quem conclui que não, atendimento com CRM e API oficial nativa sem nenhuma dessas etapas é o que o Cubo Suite entrega pronto, interesse declarado.

Quanto tempo leva a instalação do Chatwoot?

Com experiência em Docker e o roteiro acima, meio dia incluindo testes. Os relatos públicos de semanas de luta vêm de ambientes fora do padrão e de configuração por tentativa: método encurta o caminho de forma dramática.

Dá para instalar Chatwoot em hospedagem compartilhada?

Não: a pilha exige Docker (ou instalação nativa Rails) com serviços persistentes, o que pede VPS ou servidor dedicado. Painéis como Plesk em ambientes com serviços conflitantes são fonte documentada de atrito.

Chatwoot ou a versão cloud paga?

Sem alguém para operar a instância, a cloud oficial paga elimina a conta de infraestrutura e atualização, pagando em mensalidade por agente. A régua está no nosso artigo de preços do Chatwoot.