Chatwoot com Docker: guia antes de instalar

Instalar Chatwoot com Docker não é apenas baixar um arquivo e executar docker compose up. O Compose organiza os serviços, mas a equipe ainda precisa decidir versão, banco, Redis, armazenamento, domínio, TLS, email, backup, atualização e quem responde por cada camada.

A documentação oficial apresenta um caminho direto: obter os templates, configurar variáveis, preparar o banco, subir os serviços e colocar um proxy reverso na frente da aplicação. Esse roteiro é útil para começar. Para escolher com segurança, porém, é preciso entender o que existe dentro do stack e o que continua sendo responsabilidade da sua operação.

Este guia explica o Chatwoot Docker Compose como arquitetura de implantação — não como comando mágico.

Como instalar Chatwoot com Docker? Resposta direta

O fluxo oficial pode ser resumido em sete etapas:

1. preparar uma máquina compatível e instalar Docker com o plugin Compose;
2. baixar o template de variáveis e o arquivo de Compose da fonte oficial;
3. revisar imagens, versões, senhas, URLs, email e storage;
4. preparar o banco com o comando indicado para a release adotada;
5. iniciar aplicação, worker, PostgreSQL e Redis;
6. validar o serviço localmente;
7. publicar o acesso por domínio, proxy reverso e HTTPS.

Isso coloca os componentes em execução. Não prova, sozinho, que o ambiente está pronto para produção. Antes de receber conversas reais, valide persistência, restore, workers, anexos, WebSockets, email, canais, monitoramento e rollback.

Se a sua dúvida ainda é qual servidor contratar, comece pelo guia de VPS para Chatwoot. Se a instalação já existe e precisa de aceite operacional, use o checklist de Chatwoot self-hosted em produção.

O que o Docker Compose oficial do Chatwoot sobe?

No template oficial consultado em 1º de agosto de 2026, o stack reúne quatro serviços principais:

• Rails: aplicação web que atende a interface e a API;
• Sidekiq: worker que processa tarefas em segundo plano;
• PostgreSQL: banco de dados da aplicação;
• Redis: componente usado por filas e cache.

O arquivo também declara volumes para storage da aplicação, dados do PostgreSQL e dados do Redis. A porta da aplicação e as portas de banco e Redis aparecem vinculadas ao endereço local no template consultado. Isso ajuda a evitar exposição direta, mas não substitui firewall, revisão de rede e proxy bem configurado.

Aplicação e worker precisam do mesmo ambiente

Rails e Sidekiq usam a mesma imagem-base e precisam acessar a configuração esperada de PostgreSQL, Redis e storage. A interface pode abrir enquanto o worker está parado ou acumulando jobs. Por isso, “a tela carregou” não é um teste suficiente.

O template é um ponto de partida, não uma política de versão

O arquivo público da branch de desenvolvimento consultado usa uma tag mutável para a imagem da aplicação. Em produção, registre a release escolhida, confira os arquivos correspondentes a ela e defina uma política explícita de atualização. Copiar a branch atual hoje e repetir o processo meses depois pode produzir um ambiente diferente.

A própria documentação recomenda upgrades iterativos para instalações muito antigas e orienta revisar notas de release e preparar o banco durante atualizações. Trate a versão como decisão operacional, não como detalhe do comando.

Sete decisões antes do primeiro docker compose up

1. Qual versão será implantada?

Defina uma release, registre a origem dos arquivos e preserve o Compose e o .env usados. Evite depender silenciosamente de uma tag mutável. A equipe precisa conseguir responder:

• qual versão está rodando;
• de onde vieram os templates;
• quais mudanças locais foram feitas;
• como reproduzir o ambiente;
• qual é o caminho de rollback.

Sem esse inventário, uma atualização vira tentativa e erro.

2. PostgreSQL e Redis ficam no mesmo host?

O Compose inclui banco e Redis no mesmo desenho, o que simplifica um piloto. Em uma operação crítica, também é possível usar serviços externos configurados por variáveis de ambiente.

A escolha muda custo, rede e responsabilidade:

Não existe uma resposta universal. Escolha um desenho que sua equipe consiga monitorar e recuperar.

3. Onde ficarão os anexos?

O template usa volume de storage da aplicação. Esse volume precisa sobreviver à recriação do container e entrar no plano de backup. Em arquiteturas distribuídas, object storage pode ser avaliado para separar anexos do ciclo de vida de um host.

Antes de instalar, responda:

• o volume é persistente?
• quem faz backup dos anexos?
• o restore recupera arquivo e referência no banco?
• há retenção, criptografia e controle de acesso definidos?
• o storage cresce sem derrubar a aplicação?

Banco recuperado sem anexos não é recuperação completa.

4. Como domínio, HTTPS e WebSockets serão publicados?

A documentação orienta manter o container no endereço local e usar Nginx ou outro proxy reverso. O proxy precisa preservar host, protocolo e conexão de upgrade quando aplicável.

Planeje antes:

• domínio e DNS;
• certificado TLS e renovação;
• URL pública configurada na aplicação;
• headers do proxy;
• suporte a conexões persistentes;
• limites de upload e timeouts;
• firewall e portas realmente necessárias.

Expor a porta da aplicação diretamente para “resolver rápido” aumenta a superfície operacional e não entrega, por si só, uma publicação adequada.

5. Quais variáveis e segredos precisam existir?

O .env concentra configuração sensível e funcional. Ele deve ser revisado, protegido e incluído em um processo seguro de recuperação — sem ser enviado para repositório público.

Agrupe as variáveis por responsabilidade:

• URL e ambiente da aplicação;
• credenciais de PostgreSQL e Redis;
• chave secreta da aplicação;
• email transacional;
• storage;
• integrações e canais;
• observabilidade;
• recursos condicionados à edição, licença, versão e configuração vigentes.

Use valores únicos, controle acesso e defina rotação. Um exemplo de documentação não é um cofre de secrets.

6. Quem executará backup, atualização e incidentes?

Docker empacota processos; não assume plantão. Nomeie responsáveis por:

• sistema operacional e Docker;
• aplicação e workers;
• banco, Redis e storage;
• domínio, proxy e TLS;
• backup e restore;
• atualização e rollback;
• canais e integrações;
• monitoramento e incidentes.

Se a resposta for “o fornecedor”, confirme o escopo por escrito. Suporte à aplicação, hospedagem, canal de WhatsApp e integração podem pertencer a empresas diferentes.

7. Qual evidência aprova a instalação?

Defina o aceite antes de subir o stack. Um conjunto mínimo inclui:

• aplicação responde pelo domínio HTTPS;
• worker processa tarefas sem acúmulo contínuo;
• PostgreSQL e Redis persistem após reinício controlado;
• anexos podem ser enviados, lidos e recuperados;
• email transacional funciona quando necessário;
• logs e alertas chegam ao responsável;
• backup conclui e restore é testado em ambiente separado;
• canais e webhooks críticos passam por teste ponta a ponta.

O critério precisa indicar evidência, responsável e resultado. “Funcionou aqui” não é runbook.

Fluxo de instalação com Chatwoot Docker Compose

Etapa 1: fixe a fonte e a versão

Consulte a documentação oficial de Docker do Chatwoot, a release escolhida e os arquivos correspondentes. Salve a referência da versão e os hashes dos templates que serão revisados.

A documentação pública pode apontar para arquivos em branch mutável. Não confunda conveniência de download com reprodutibilidade de produção.

Etapa 2: prepare o host

Valide sistema operacional, Docker, Compose, CPU, memória, disco, swap, rede e sincronização de horário conforme a documentação vigente. Requisitos publicados são ponto de partida, não garantia para qualquer volume de agentes, conversas, anexos e integrações.

Reserve margem para aplicação, worker, banco, Redis, sistema operacional e processo de atualização. Meça o cenário real em piloto.

Etapa 3: revise o Compose

Antes de executar, confira:

• imagens e tags;
• serviços e dependências;
• volumes persistentes;
• portas e bindings;
• política de restart;
• limites e reservas quando adotados;
• rede entre serviços;
• uso de serviços gerenciados;
• estratégia de logs.

Uma alteração pequena de caminho ou volume pode mudar completamente o comportamento de persistência.

Etapa 4: configure o ambiente

Preencha URLs, banco, Redis, secret da aplicação, email, storage e integrações necessárias. Use um método seguro para secrets e valide que nenhum valor sensível entrou no histórico do shell, do Git ou de documentação compartilhada.

Também separe configuração obrigatória para iniciar da configuração opcional de canais. É melhor provar o núcleo primeiro e adicionar integrações de forma controlada do que depurar tudo ao mesmo tempo.

Etapa 5: prepare o banco

A documentação oficial orienta usar o comando de preparação do banco para a instalação inicial. Em atualização, confirme a sequência da versão adotada e leia as notas de release. Não substitua automaticamente o procedimento por um comando de migração genérico.

Registre saída, duração e falhas. Banco parcialmente preparado não deve ser tratado como instalação concluída.

Etapa 6: suba e valide cada camada

Depois de iniciar os serviços, verifique mais do que o status dos containers:

• aplicação responde localmente;
• Rails conecta ao banco e ao Redis esperados;
• worker está ativo;
• jobs são processados;
• volumes mantêm dados após reinício controlado;
• logs não mostram loop de erro;
• espaço, memória e filas têm baseline inicial.

Um container marcado como “running” pode hospedar um processo degradado.

Etapa 7: publique por proxy e execute smoke tests

Configure domínio, HTTPS e proxy reverso; depois teste pela URL pública. Inclua login, criação de conversa de teste, processamento por worker, anexo, email e um canal ou webhook crítico já autorizado.

O próximo passo é o checklist completo de go-live, que cobre backup, restore, monitoramento, canais, contingência e decisão GO, GO CONDICIONAL ou NO-GO.

Docker facilita a instalação, mas não elimina operação

O principal benefício do Docker Compose é tornar a topologia visível e repetível: serviços, imagem, ambiente, volumes e comandos ficam declarados. Isso reduz instalação manual, mas não resolve automaticamente:

• dimensionamento;
• alta disponibilidade;
• backup e restore;
• proteção de segredos;
• monitoramento;
• atualização compatível;
• incidentes de canal ou integração;
• política de dados;
• suporte e plantão.

Essa diferença importa na compra. O custo real de self-hosting inclui infraestrutura, tempo técnico e risco operacional. Para comparar no mesmo horizonte, consulte o guia de custo do Chatwoot self-hosted.

Erros comuns ao instalar Chatwoot com Docker

Usar tag mutável sem registrar a release

O ambiente pode mudar entre downloads. Fixe a versão aprovada e preserve os arquivos usados.

Expor banco, Redis ou aplicação sem necessidade

Bindings locais no template não substituem firewall, mas são um sinal de que esses serviços não precisam ficar abertos publicamente no desenho comum. Exponha somente o necessário e valide a rede.

Guardar apenas o arquivo Compose

Sem .env, secrets, banco, anexos e procedimento de recuperação, o Compose não reconstrói a operação.

Testar só a interface

A aplicação web pode responder com worker parado, email quebrado, storage incorreto ou fila acumulando. Teste fluxos assíncronos.

Confundir snapshot com restore comprovado

Snapshot, dump ou cópia de volume só vira evidência quando a restauração é executada e validada fora de produção.

Atualizar direto sem ler a sequência da release

Instalações antigas podem exigir etapas intermediárias. Preserve backup, teste migrações e defina rollback antes de trocar imagem.

Presumir que “self-hosted” significa “sem terceiros”

Email, storage, DNS, TLS, canais, APIs e integrações podem depender de serviços externos. Liste cada dependência e seu responsável.

Chatwoot Docker, Cloud ou uma distribuição licenciada?

A escolha depende do nível de controle e de responsabilidade que a empresa quer assumir.

• Chatwoot self-hosted com Docker: a equipe controla o ambiente e opera aplicação, dados e dependências, diretamente ou por parceiro.
• Chatwoot Cloud: a infraestrutura principal da aplicação faz parte do serviço contratado, enquanto configuração, canais, integrações e governança continuam exigindo responsáveis.
• NooviChat: alternativa para quem avalia uma distribuição própria com operação mais guiada e recursos NooviChat, conforme licença, versão e configuração vigentes.

O NooviChat não é open-source. É uma distribuição privada/licenciada baseada em fork modificado do Chatwoot, comercializada por licença/acesso à imagem Docker. A licença comercial NooviChat não é a Chatwoot Enterprise License, não implica afiliação ou endosso da Chatwoot Inc. e não substitui licenças, avisos ou atribuições aplicáveis ao código de origem e a componentes de terceiros.

Infraestrutura, hospedagem, backup, implantação, suporte, canais, integrações e serviços de terceiros dependem do contrato e da configuração adotada. Não presuma inclusão automática.

Para comparar a proposta no Brasil, veja Chatwoot self-hosted no Brasil e as condições comerciais vigentes do NooviChat.

Perguntas frequentes

Docker é obrigatório para instalar Chatwoot?

Não. A documentação do Chatwoot apresenta diferentes métodos de implantação, incluindo Docker, Linux VM e Kubernetes. Docker Compose é uma opção documentada; a escolha deve considerar escala, conhecimento da equipe, recuperação e manutenção.

O arquivo Docker Compose oficial está pronto para produção?

Ele é um template de implantação e um ponto de partida. A equipe ainda precisa revisar versão, secrets, volumes, banco, Redis, storage, proxy, TLS, email, backup, monitoramento, atualização e responsabilidades. Produção exige aceite do ambiente, não apenas containers ativos.

Posso colocar Chatwoot, PostgreSQL e Redis na mesma VPS?

Pode ser uma hipótese inicial para piloto ou operação de risco controlado. O desenho compartilha recursos e concentra falhas. Valide carga, persistência, backup, restore, monitoramento e caminho de expansão antes de aprovar.

docker compose up -d conclui a instalação?

Esse comando inicia os serviços definidos. Ainda é necessário preparar e validar o banco, configurar o ambiente, publicar por proxy seguro e testar aplicação, worker, anexos, email, canais, backup e recuperação.

Como atualizar o Chatwoot em Docker?

Siga a documentação e as notas da versão adotada. Registre origem e destino, faça backup verificável, teste a sequência, atualize imagens e prepare o banco conforme o procedimento oficial. Instalações antigas podem exigir upgrades intermediários. Não presuma atualização sem indisponibilidade.

Docker elimina a necessidade de DevOps?

Não. Ele padroniza empacotamento e execução, mas a operação ainda precisa de responsáveis por infraestrutura, banco, filas, storage, secrets, proxy, monitoramento, atualização, backup e incidentes.

O NooviChat entrega o código-fonte aberto?

Não. NooviChat não é open-source. O modelo comercial é licença/acesso à imagem Docker de uma distribuição privada baseada em fork modificado do Chatwoot. Direitos de uso, infraestrutura, implantação e suporte seguem o contrato e a oferta vigentes.

Conclusão: instale com um plano de operação

O Chatwoot com Docker pode simplificar a montagem do ambiente, mas o Compose não substitui decisões de arquitetura. Antes de instalar, fixe a versão, escolha onde ficam banco, Redis e anexos, proteja secrets, planeje domínio e TLS, defina backup e atualização e nomeie os responsáveis.

Depois de subir os serviços, valide aplicação e worker, persistência, anexos, email, canais e restauração. Só então avance para o go-live.

Se sua empresa quer comparar a implantação própria com uma alternativa privada/licenciada e mais guiada, avalie o NooviChat self-hosted ou consulte as condições comerciais.