Ir para o conteúdo
Promovaweb

Como o Chatwoot é montado na sua VPS

O Chatwoot é uma aplicação Rails com um serviço web e processos Sidekiq que executam tarefas em segundo plano. Ele guarda as conversas no PostgreSQL e usa o Redis nas filas, por isso sua VPS precisa manter esses serviços conectados para receber mensagens e concluir os envios.

Ficha e sumário da página

Referência técnica
Chatwoot v4.19.1
Revisão
13 de novembro de 2026
Conteúdo
Documentação oficial consultada
  1. O serviço web recebe as conexões
  2. Tarefas em segundo plano com Sidekiq
  3. Histórico no PostgreSQL e recuperação do banco
  4. O Redis mantém as filas
  5. Armazenamento dos anexos e serviços de email

O serviço web recebe as conexões

O processo web do Rails atende o painel, a API e os endpoints usados pelas integrações. O navegador e os canais externos alcançam esse serviço pelo endereço público da central. Numa VPS com proxy reverso, o Traefik recebe o HTTPS e encaminha a requisição ao Chatwoot pela rede dos containers. O aplicativo processa a requisição usando os serviços internos configurados.

Você pode abrir o painel e ainda ter tarefas de atendimento paradas. A interface acessível mostra que o processo web respondeu, mas o envio de mensagens e outras tarefas também dependem dos workers. Essa separação existe porque algumas atividades continuam fora do tempo de resposta da requisição HTTP. O navegador não precisa esperar todo o processamento de uma fila para receber a página.

  • Chatwoot na VPSO domínio público alcança o serviço web.
  • Rails webAtende o painel, a API e as integrações.
  • SidekiqExecuta tarefas retiradas das filas.
  • PostgreSQLGuarda conversas, mensagens e cadastros.
  • RedisMantém as filas consumidas pelo Sidekiq.
  • ArmazenamentoPreserva os arquivos anexados às mensagens.
O serviço web e os workers usam o mesmo banco e as filas do Redis. Os anexos precisam de armazenamento persistente separado do ciclo de vida dos containers.

Tarefas em segundo plano com Sidekiq

O Sidekiq executa jobs, que são tarefas colocadas numa fila para processamento em segundo plano. O Chatwoot usa esses processos para atividades que não precisam terminar dentro da mesma requisição do navegador. O worker consulta as filas no Redis e executa o trabalho com acesso ao banco e aos serviços externos necessários à tarefa.

Uma falha no serviço externo pode fazer uma tarefa falhar mesmo com o worker em execução. O painel de monitoramento do Sidekiq permite observar filas e tarefas com erro. No Chatwoot, esse painel exige acesso de superadministrador da instalação. O papel de administrador no painel de atendimento não concede esse acesso. Você relaciona o estado da fila à mensagem que não saiu para investigar se o trabalho aguarda execução ou falhou durante o envio.

O serviço web e o worker usam a configuração da mesma instalação. Credenciais de banco, endereço do Redis e opções de armazenamento precisam corresponder aos serviços utilizados. Se o worker aponta para outro banco ou não alcança a fila, ele pode iniciar como processo sem participar corretamente do atendimento esperado. A existência do processo não comprova a ligação entre as peças.

Histórico no PostgreSQL e recuperação do banco

O PostgreSQL guarda os registros persistentes do Chatwoot, incluindo mensagens, contatos e conversas. O volume ou serviço de banco precisa sobreviver à substituição do container da aplicação. Atualizar a imagem do Chatwoot altera o código executado, enquanto as migrações ajustam a estrutura do banco conforme a versão. Esses dois movimentos participam da atualização documentada pelo projeto.

Você precisa tratar o backup como recuperação das mensagens e dos cadastros, com uma cópia que possa ser restaurada e conferida. Copiar apenas a configuração dos containers não preserva o histórico do banco. Também é necessário considerar os anexos, porque as referências guardadas nas mensagens dependem dos arquivos correspondentes no armazenamento. Um banco restaurado sem esses arquivos pode mostrar a conversa sem conseguir abrir seu anexo.

O acesso ao banco pertence à comunicação interna dos serviços. O cliente que conversa pelo widget não precisa alcançar a porta do PostgreSQL. Numa arquitetura com Traefik, a publicação do serviço web atende à entrada pública, enquanto o banco continua acessível aos processos autorizados na rede interna. Essa separação mantém o caminho do atendimento diferente do caminho de administração do banco.

O Redis mantém as filas

O Redis participa do processamento assíncrono e de informações temporárias utilizadas pelo aplicativo. O Sidekiq depende dessa conexão para retirar tarefas da fila. Tratar o Redis como uma peça descartável sem considerar os jobs pendentes pode interromper trabalho ainda não concluído. A configuração precisa respeitar o papel específico desse serviço na instalação do Chatwoot.

Quando você investiga demora no envio, uma mensagem registrada no PostgreSQL pode ainda aguardar o processamento de um job pelo Sidekiq. O painel do Sidekiq exibe as tarefas pendentes na fila. Se o banco permanece disponível, mas o worker perde a conexão com o Redis, a central pode exibir o histórico enquanto o trabalho pendente fica sem execução. Você confere a comunicação com a fila junto do estado do worker.

Armazenamento dos anexos e serviços de email

O armazenamento de arquivos guarda anexos fora do ciclo de vida do processo web. A configuração pode usar armazenamento local persistente ou um provedor compatível. Os serviços que processam esses arquivos precisam acessar o mesmo destino. Ao separar web e workers em containers, você considera essa ligação para que um arquivo recebido continue disponível durante o processamento posterior.

O email também depende de serviços próprios para recebimento e envio. As variáveis de ambiente registram os endereços e as opções necessárias, sem transformar o Chatwoot num provedor de email. A referência de variáveis de ambiente reúne as 149 variáveis catalogadas para a v4.19.1, com categorias e fontes para consulta.

A Chatwoot Inc. mantém o projeto sob MIT Expat fora das partes com licença própria. O Compose aparece neste portal apenas como ambiente de estudo, sem promessa de disponibilidade para produção. Para revisar a ligação entre servidor, banco e integrações com acompanhamento técnico, o Desenvolvimento Colaborativo da Dev Side Studio permite investigar a configuração com o editor e o terminal abertos.

Continue na comunidade

Leve ao Discord da Promovaweb a mensagem do WhatsApp que não chega à caixa de entrada ou a fila do Sidekiq parada. Com o log do Chatwoot na conversa, a comunidade compara o seu caso com instalações parecidas.

Uma VPS para o seu Chatwoot

O Chatwoot mantém o serviço web e o Sidekiq no ar ao lado do PostgreSQL e do Redis. A VPS da StayCloud em São Paulo vem com acesso root e disco NVMe para a central, o banco e os anexos ficarem na mesma máquina.

Ver a VPS da StayCloud

Link de parceiro da Promovaweb.