Como instalar Chatwoot no VPS com Docker
Instale o Chatwoot em um VPS com Docker Compose e Traefik, usando tags fixas, SMTP funcional, backups de Postgres e uploads e upgrades seguros.
O que você vai criar
Para alojar o Chatwoot num VPS, execute quatro contentores: um processo web Rails, um worker de fundo Sidekiq, PostgreSQL com a extensão pgvector e Redis. O Chatwoot é uma plataforma open source de suporte ao cliente. Assim, terá uma caixa de entrada partilhada pela equipa e um widget de chat para o site num servidor que controla. A instalação demora cerca de vinte minutos. Tudo o que vem depois, como entrega de correio, cópias de segurança, atualizações e dimensionamento, é o que determina se o serviço continuará a funcionar daqui a um ano.
Cada contentor tem uma função. Rails disponibiliza o painel dos agentes e a API (interface de programação de aplicações) do widget. Sidekiq executa as tarefas demoradas: enviar correio, consultar canais ligados, executar regras de automatização e gerar relatórios. Postgres armazena conversas, contactos, contas de agentes e todas as definições alteradas no painel. Redis armazena as filas do Sidekiq e o canal pub/sub do ActionCable, que envia uma mensagem nova para um painel aberto sem recarregar a página. Neste caso, Redis não é uma cache descartável, porque perdê-lo significa perder os trabalhos em fila.
A imagem Postgres no ficheiro compose a montante é pgvector/pgvector:pg16, e não a imagem postgres padrão, porque o esquema do Chatwoot ativa a extensão vector para as suas funcionalidades de IA. Se substituir Postgres pela imagem padrão, a primeira execução da base de dados termina com ERROR: extension "vector" is not available, porque o ficheiro de controlo da extensão não existe nessa imagem. Use a imagem fornecida pelo projeto a montante.
Este guia pressupõe que o Docker e um reverse proxy já funcionam no servidor. Se não funcionarem, comece por Docker Compose num VPS e depois volte aqui.
De quanta capacidade precisa um VPS para alojar o Chatwoot?
Em outubro de 2026, a página de requisitos do projeto indica 4 GB de RAM e 4 cores de CPU como mínimo, com capacidade para até 10.000 conversas por dia. Para 8 GB e 8 cores, indica até 20.000 conversas por dia. Também exige pelo menos 1 GB de swap e explica diretamente o motivo: evitar que a máquina fique sem memória durante uma atualização. Reserve 5 GB a 10 GB de disco para o Postgres, sem contar os uploads de ficheiros.
Agora, a parte direta. Um VPS com 2 GB inicia o Chatwoot e parece funcionar bem com dois agentes e uma caixa de entrada pouco movimentada. O problema surge em dois pontos. O primeiro é o Sidekiq, que, segundo o projeto, usa mais de 1 GB num servidor ocupado. Um pico de emails ou uma tarefa de relatórios pode fazer a máquina ultrapassar a memória disponível antes de o Rails, o Postgres e o Redis consumirem a respetiva parte. O segundo é a atualização, porque db:chatwoot_prepare inicia um processo Rails novo para aplicar as migrações. Neste sistema, o arranque do Rails consome centenas de megabytes antes de executar qualquer trabalho útil.
Não recebe primeiro um aviso claro. O out of memory killer do kernel envia SIGKILL para o processo que selecionar, normalmente o maior. O Docker deteta que o container terminou e restart: always inicia-o novamente. docker compose ps --all mostra então um container que reinicia continuamente ou permanece em Exited (137), onde 137 significa que foi terminado pelo sinal 9. Sem --all, um container parado nem sequer é apresentado. O código de saída 137, por si só, não prova que a causa foi falta de memória, porque docker kill envia o mesmo sinal. Confirme a causa com sudo dmesg -T | grep -i "killed process", que identifica o processo selecionado pelo kernel.
Se 4 GB ultrapassarem o orçamento, pode executar a máquina com 2 GB e adicionar 2 GB de swap, aceitando que os tempos de resposta piorem sob carga. A swap funciona como uma reserva contra a falta de memória, mas não é uma garantia. Um pico suficientemente grande ainda pode fazer com que um container seja terminado. De qualquer forma, vale a pena definir um limite rígido de memória para cada serviço. Assim, o worker não consegue derrubar a base de dados com ele. Consulte limites de memória no Docker Compose.
Os uploads de ficheiros são o componente que cresce sem um limite definido por si. Cada captura de ecrã anexada por um cliente é guardada no volume de armazenamento e permanece lá. Por isso, monitorize docker system df -v em vez de assumir que foi a base de dados que encheu o disco.
Obtenha o ficheiro Compose e fixe uma tag de versão
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 .envO ficheiro que acabou de descarregar indica image: chatwoot/chatwoot:latest. Altere isso antes de fazer qualquer outra coisa.
services:
base: &base
image: chatwoot/chatwoot:v4.19.1
env_file: .env
volumes:
- storage_data:/app/storagelatest significa que o próximo docker compose pull fornece o que foi publicado nessa manhã. Isso pode ser uma versão principal com migrações que nunca leu. Na prática, as migrações do Chatwoot não são reversíveis. Um salto acidental exige restaurar uma cópia de segurança, e não desfazer a alteração. Fixe a tag e altere-a deliberadamente. v4.19.1 era a versão atual em 25 October 2026, e as notas da versão recomendam-na para obter as correções de segurança e as melhorias de hardening mais recentes. Consulte a página de versões para saber qual é a tag que deve fixar hoje. Se estiver a atualizar a partir de v4.18.0 ou anterior, leia primeiro as notas da versão v4.19.0: o Captain V1 foi descontinuado, e as instalações self-hosted que usam instruções para V1 têm de migrar para V2 antes da atualização. Qualquer aplicação que mantenha uma base de dados exige a mesma cautela. Por isso, alojar o tracker de treinos openGym começa por fixar uma tag git, embora seja uma aplicação muito mais pequena do que esta.
O serviço base é uma âncora YAML que rails e sidekiq integram, pelo que alterar a tag num local altera-a nos dois serviços. Enquanto estiver no ficheiro, elimine a linha version: '3' no início. As versões modernas do Compose ignoram-na e apresentam the attribute 'version' is obsolete, it will be ignored em cada comando.
Preencha o ficheiro .env
Gere primeiro o segredo. O upstream pede um valor alfanumérico, porque os caracteres especiais podem ser alterados quando o valor passa por uma shell ou por um analisador YAML.
head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''Depois, defina estas chaves em .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 são os nomes dos serviços do Compose, que são resolvidos na rede predefinida do projeto. FRONTEND_URL não é apenas decorativo. O Chatwoot constrói a partir dele o URL do script do widget e todas as ligações nas mensagens de email enviadas. Um valor incorreto gera ligações de reposição de palavra-passe para um host que não responde.
Agora, veja a armadilha no ficheiro upstream. O serviço postgres não lê .env. Tem o seu próprio bloco environment, com POSTGRES_PASSWORD= vazio. Assim, definir a palavra-passe apenas em .env deixa a base de dados sem palavra-passe e a aplicação com uma. Faça o serviço apontar para a mesma variável:
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}O Compose lê .env no diretório do projeto para fazer a substituição de ${...}. Assim, ambos os lados recebem agora a mesma cadeia. Se isto estiver incorreto, o Rails termina com PG::ConnectionBad: FATAL: password authentication failed for user "postgres".
Um comportamento surpreende quase toda a gente: a imagem do Postgres só aplica POSTGRES_PASSWORD quando inicializa um diretório de dados vazio. Alterar o valor mais tarde não tem efeito, porque o initdb não é executado uma segunda vez. Se já iniciou a stack uma vez, altere-o dentro da base de dados.
docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"ENABLE_ACCOUNT_SIGNUP=true é temporário. Abre o formulário público de registo para que possa criar a primeira conta. Defina-o como false e execute docker compose up -d novamente assim que a sua conta existir. Caso contrário, qualquer pessoa que encontre o URL pode registar-se no seu serviço de suporte. A partir desse momento, os agentes entram por convite e as respetivas palavras-passe ficam apenas nesta aplicação. Isto é aceitável até executar meia dúzia de serviços e se cansar de manter uma lista de contas separada em cada um. Nessa altura, um fornecedor de identidade autoalojado como o Authentik é o componente que os substitui.
.env contém agora todos os segredos desta stack em texto simples. Mantenha o ficheiro com o modo 600 e fora do git. Como o Compose lê ficheiros env e onde os segredos ficam expostos explica os pontos mais sensíveis, incluindo a diferença entre env_file e environment.
Coloque o Chatwoot atrás do Traefik existente
Não crie um segundo reverse proxy para uma aplicação. Se o Traefik já termina o TLS (transport layer security) para outros containers neste servidor, o Chatwoot junta-se a ele através de um bloco de labels. Se ainda não tem essa configuração, configure-a uma vez com Traefik à frente de várias aplicações Docker Compose e volte depois a esta secção.
Mantenha o docker-compose.yaml do upstream próximo do original para poder compará-lo com uma cópia mais recente, e coloque as suas alterações num ficheiro de override. O Compose faz automaticamente o merge de docker-compose.override.yaml, e dividir o Compose por vários ficheiros explica as regras de 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: trueUse os seus próprios nomes de entrypoint e certresolver. O container deve estar na mesma rede Docker que o Traefik. É isso que a entrada proxy garante. Também deve permanecer em default, caso contrário perde o acesso ao Postgres e ao Redis. Esta é a segunda linha que muitas pessoas esquecem.
Não altere o bloco ports:. O upstream associa-o a 127.0.0.1:3000, que aceita ligações apenas no loopback. Assim, não fica acessível a partir da Internet e continua disponível para testes a partir do próprio servidor com curl -I http://127.0.0.1:3000.
O painel do agente mantém um websocket aberto para /cable para receber mensagens em tempo real. O Traefik encaminha a atualização HTTP sem configuração adicional, por isso não é necessário acrescentar nada. Se mais tarde colocar uma CDN ou outro proxy à frente do Traefik, permita websockets nesse componente. Caso contrário, o painel carrega normalmente, mas as mensagens novas só aparecem depois de uma atualização manual.
Inicialize o banco de dados e inicie a stack
Inicie primeiro os serviços de dados e aguarde o Postgres concluir a primeira execução.
docker compose up -d postgres redis
docker compose logs postgres | tail -n 5Aguarde database system is ready to accept connections. Em seguida, crie o schema.
docker compose run --rm rails bundle exec rails db:chatwoot_prepareIsto cria o banco de dados se ele não existir e, depois, carrega o schema e os dados seed padrão. O comando exibe as linhas das migrações e termina corretamente. Se ficar exibindo postgres:5432 - no response, o entrypoint está aguardando um banco de dados que ainda não aceita ligações. Na primeira execução, isso normalmente significa que o initdb ainda está a ser executado. Aguarde, consulte os logs do Postgres e execute o comando novamente. Se parar na extensão vector, substituiu a imagem com pgvector por uma imagem padrão do Postgres.
docker compose up -d
docker compose ps
docker compose logs --tail 30 railsOs quatro containers devem mostrar Up, e o log do Rails deve terminar com uma linha do Puma a escutar em http://0.0.0.0:3000. Em seguida, verifique o caminho público:
curl -sI https://support.example.com | head -n 1HTTP/2 200 significa que toda a cadeia está a funcionar. Um erro 404 do Traefik significa que a regra do router não correspondeu, normalmente devido a um erro de digitação no hostname. Um erro 502 significa que o Traefik encontrou o router, mas não conseguiu alcançar o container. Quase sempre isso é causado pela rede proxy em falta ou por um loadbalancer.server.port diferente de 3000.
Abra a URL, crie a sua conta em /app/auth/signup, defina ENABLE_ACCOUNT_SIGNUP=false e execute docker compose up -d para fechar o formulário.
Por que as redefinições de palavra-passe e as conversas por email falham sem SMTP
Sem as definições de SMTP (simple mail transfer protocol), o Chatwoot é uma central de suporte que não consegue enviar emails, e isso interrompe mais do que as notificações. As redefinições de palavra-passe deixam de funcionar, por isso um administrador bloqueado continua sem acesso. Os convites de agentes deixam de funcionar, porque um convite é um email. As respostas a clientes numa conversa por email deixam de funcionar, por isso a conversa só funciona num sentido. Este é o passo que muitas pessoas ignoram e só descobrem durante o pior período.
O mecanismo é simples. Sem SMTP_ADDRESS definido, o Chatwoot muda o ActionMailer para a entrega por sendmail. A documentação do projeto descreve isto como a configuração do Postfix, predefinida desde a v2.12.0, e as instruções instalam o Postfix no servidor com sudo apt install -y postfix. Esta configuração Docker não faz isso, por isso não existe um servidor de email configurado para receber as mensagens desse mecanismo de entrega. O email é enviado a partir de um job em segundo plano, por isso qualquer erro produzido pela entrega aparece no log do Sidekiq e não no log do Rails. Entretanto, a pessoa que clica em "esqueci a palavra-passe" vê uma confirmação tranquilizadora, mas não recebe nada.
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=trueUse a porta 587 com STARTTLS. A ligação começa em texto simples e é atualizada para uma ligação cifrada antes da autenticação. Muitos fornecedores de VPS bloqueiam a porta de saída 25 por predefinição para limitar o spam. Em 8 de novembro de 2026, a Hetzner bloqueia as portas 25 e 465 por predefinição nos servidores cloud. O bloqueio é aplicado por conta. A Vultr bloqueia a porta 25 em todas as novas Compute Instances. Ambos analisam os pedidos de desbloqueio individualmente. A Hetzner exige um mês como cliente e o pagamento da primeira fatura antes de permitir o envio de um pedido de aumento de limite. Nenhum dos dois bloqueia a porta 587. Por isso, um relay na porta 587 funciona desde o primeiro arranque, sem abrir um ticket nem esperar. SMTP_DOMAIN é o domínio que o servidor anuncia durante a conversa SMTP, e alguns relays rejeitam uma discrepância.
Aplique as definições e monitorize o worker:
docker compose up -d rails sidekiq
docker compose logs -f sidekiqInicie uma redefinição de palavra-passe a partir da página de login. Quando a entrega funciona, o job do mailer termina normalmente no log do Sidekiq. Quando falha, aparece a classe da exceção. Em seguida, o Sidekiq tenta novamente com um intervalo crescente. Por isso, um relay com problemas produz o mesmo erro de poucos em poucos minutos durante horas.
Duas rejeições são comuns, e nenhuma é um bug do Chatwoot. 535 Authentication failed significa que a autenticação falhou. Verifique as credenciais, se a autenticação SMTP está ativada e se uma política de acesso a está a bloquear. Apenas corrigir as credenciais não exclui este erro. Alguns fornecedores exigem uma palavra-passe de aplicação em vez da palavra-passe da conta. 550 Sender address rejected significa que o servidor rejeitou o endereço do remetente. Leia a resposta completa antes de alterar MAILER_SENDER_EMAIL. As permissões ou a verificação do remetente são uma causa possível, mas 550 5.7.27 Sender address rejected: Domain does not accept mail indica um domínio do remetente com um registo MX nulo.
Receber emails numa conversa é uma tarefa separada. Para encaminhar emails através da entrada do Chatwoot, são necessários MAILER_INBOUND_EMAIL_DOMAIN e RAILS_INBOUND_EMAIL_SERVICE, além de um servidor de email que entregue as mensagens recebidas ao Chatwoot. Também pode ligar uma caixa de correio através de IMAP, incluindo OAuth da Google ou da Microsoft, sem configurar esse encaminhamento. Alugar um relay é a opção mais rápida. Se preferir gerir todo o percurso do email, executar o seu próprio servidor de email com Mailcow explica o que esse compromisso realmente envolve.
O que fazer backup e como comprovar que a restauração funciona
Um backup do Chatwoot tem quatro partes. Ignorar qualquer uma delas transforma a restauração numa reconstrução.
- A base de dados PostgreSQL, que contém as conversas, os contactos, as contas dos agentes e todas as definições.
- O volume
storage_data, porqueACTIVE_STORAGE_SERVICE=localgrava os ficheiros carregados no disco e mantém apenas uma linha de referência no PostgreSQL. - O ficheiro
.env, porque contémSECRET_KEY_BASEe as chavesACTIVE_RECORD_ENCRYPTION_*. - Os ficheiros Compose, porque registam a tag exata da imagem compatível com o esquema da base de dados.
Restaurar apenas a base de dados faz com que todas as conversas voltem com os anexos danificados, porque as linhas apontam para ficheiros que já não estão no disco.
cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump-T é importante. Sem essa opção, o Compose aloca um pseudo-terminal, que altera os bytes de mudança de linha no fluxo. O resultado é um ficheiro de dump que pg_restore rejeita. -Fc é o formato personalizado. Comprime os dados e permite que pg_restore trabalhe de forma seletiva.
docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
tar czf /backup/storage-$(date +%F).tgz -C /data .O nome do volume é o nome do diretório do projeto seguido de _storage_data. Confirme-o com docker volume ls | grep storage_data antes de confiar nesse comando, porque o Docker cria um volume vazio em vez de falhar quando é indicado um volume inexistente. Obtém um arquivo válido e vazio, sem qualquer erro. Verifique o tamanho depois com ls -lh storage-*.tgz.
Ambos os ficheiros estão agora no mesmo disco que os dados que protegem. Isso não oferece proteção contra a perda desse disco. Envie-os para fora do servidor e cifre-os, porque um dump da base de dados contém todas as mensagens dos clientes em texto simples. Backups cifrados fora do servidor com restic explica o agendamento e a retenção.
O teste de restauração: execute-o antes de precisar dele
Restaure numa segunda VPS, não no servidor ativo. Copie .env, os ficheiros Compose e ambos os arquivos para esse servidor. Em seguida, execute:
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 os objetos existentes antes de os carregar. Por isso, indique apenas uma base de dados que possa perder. Depois, inicie sessão e abra uma conversa que tenha um anexo. Se a lista de mensagens carregar e o ficheiro for transferido, o backup é válido.
Uma restauração com um SECRET_KEY_BASE diferente invalida todos os cookies de sessão. Todos os utilizadores têm de iniciar sessão novamente. Uma restauração com chaves ACTIVE_RECORD_ENCRYPTION_* diferentes é mais grave: o Chatwoot não consegue decifrar as colunas que contêm as credenciais dos canais e apresenta ActiveRecord::Encryption::Errors::Decryption. Por isso, .env faz parte da lista de backup.
Como atualizar o Chatwoot para uma nova tag
A ordem é mais importante do que os comandos.
- Leia as notas da versão entre a sua tag e a tag de destino e procure passos manuais obrigatórios.
- Crie um dump recente da base de dados e um arquivo do armazenamento. Confirme se os tamanhos dos dois ficheiros parecem normais.
- Edite a tag da imagem no serviço
baseemdocker-compose.yaml. - Faça pull da nova imagem, pare a stack, execute as migrações e inicie-a novamente.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose imagesFaça o pull antes de executar a migração, porque ela tem de ser executada a partir da nova imagem. A imagem antiga não contém os novos ficheiros de migração. Pare a stack antes da migração, porque o código antigo e o novo schema ficam incompatíveis. Um processo Rails antigo em execução pode gerar erros ou escrever linhas que o novo schema não aceita. Parar a stack também liberta a memória necessária para a migração. Essa é a razão pela qual o upstream pede swap.
docker compose images mostra a tag que cada contentor está realmente a executar. Isto deteta o caso em que editou a tag, mas se esqueceu de fazer pull.
A distância entre versões que pode percorrer depende da idade da instalação. Se a instalação estiver uma ou duas releases atrasada, reveja as notas da versão entre a sua tag e a tag de destino, defina a tag de destino e execute os passos acima uma vez. Só quando a instalação é muito antiga o guia Docker do upstream indica que deve atualizar iterativamente através de tags de imagens intermédias, em vez de saltar diretamente para a imagem mais recente. Nesse caso, repita a alteração da tag, o pull e o passo de preparação para cada tag intermédia, porque o upstream pede db:chatwoot_prepare após cada atualização.
Se o Rails iniciar antes de a migração ser executada, recusa-se a servir e regista ActiveRecord::PendingMigrationError: Migrations are pending. Com restart: always definido, o contentor entra num ciclo de reinícios, pelo que docker compose ps mostra um uptime que é reiniciado a cada poucos segundos. Execute o passo de preparação para corrigir o problema.
Para fazer rollback, volte a definir a tag antiga e restaure o dump. Não existe um caminho de migração inversa em que possa confiar. É essa a finalidade do passo 2.
Modos de falha e mensagens apresentadas
502 Bad Gateway do Traefik. O router correspondeu ao pedido, mas o backend não respondeu. Verifique se docker compose ps mostra rails como Up. Em seguida, execute docker network inspect proxy e confirme que o contentor rails aparece na lista de contentores. Um contentor que não está ligado fica invisível para o Traefik. Por isso, o pedido corresponde a um router, mas não é encaminhado para lado nenhum.
O dashboard carrega, mas as mensagens novas só aparecem depois de atualizar a página. A ligação WebSocket a /cable não está a passar, ou FRONTEND_URL não corresponde ao endereço apresentado na barra do browser. Uma discrepância faz com que a página tente abrir um WebSocket para uma origem diferente, que o browser bloqueia.
FATAL: password authentication failed for user "postgres". A palavra-passe em .env é diferente da palavra-passe gravada no volume de dados do Postgres. Corrija-a com ALTER USER dentro do contentor em execução. Editar .env novamente não altera uma base de dados já inicializada.
NOAUTH Authentication required. O Redis está a ser executado com --requirepass, mas a aplicação ligou-se sem uma palavra-passe. Isto significa que REDIS_PASSWORD está em falta em .env ou não foi carregada. Teste diretamente a palavra-passe esperada pelo Redis com docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping'. O resultado deve ser PONG. As aspas simples são importantes. Fazem com que a variável seja expandida dentro do contentor, que lê .env, e não na sua própria shell, onde normalmente fica vazia.
Contentores terminados com o código 137. Isso corresponde a SIGKILL. Num servidor pequeno, o emissor habitual é o mecanismo do kernel que termina processos por falta de memória. No entanto, docker kill envia o mesmo sinal. Por isso, verifique sudo dmesg -T | grep -i "killed process" antes de atribuir a causa à memória. Se for um problema de memória, adicione swap, defina limites de memória por serviço ou mude para um plano maior.
FAQ
De quanta RAM precisa um VPS Chatwoot autoalojado?
Em outubro de 2026, o projeto upstream exige 4 GB de RAM e 4 núcleos de CPU como mínimo, com capacidade indicada para até 10,000 conversas por dia, e 8 GB com 8 núcleos para até 20,000. Adicione pelo menos 1 GB de swap, porque uma atualização executa um segundo processo Rails para aplicar as migrações, e é nesse ponto que as máquinas pequenas ficam sem memória. Um VPS com 2 GB arranca e funciona para alguns agentes, mas só o Sidekiq pode ultrapassar 1 GB sob carga. Por isso, espere que os contentores sejam terminados com o código de saída 137 durante períodos de maior utilização e durante as atualizações.
Porque é que os emails de reposição da palavra-passe do Chatwoot nunca chegam?
Porque SMTP_ADDRESS não está definido. O Chatwoot recorre então à entrega através do sendmail, que o projeto upstream pressupõe ser fornecido por um servidor Postfix instalado no host, mas esta configuração Docker não tem nenhum. O trabalho é executado no Sidekiq, pelo que qualquer erro de entrega aparece no log do Sidekiq, enquanto o browser continua a apresentar uma mensagem de sucesso. Defina SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD e MAILER_SENDER_EMAIL em .env, reinicie os serviços rails e sidekiq e, em seguida, monitorize docker compose logs -f sidekiq enquanto inicia uma reposição.
O que preciso de salvaguardar para restaurar o Chatwoot?
A base de dados Postgres, o volume Docker storage_data, o ficheiro .env e os ficheiros compose. A base de dados, por si só, não é suficiente, porque os ficheiros carregados estão guardados no volume, enquanto o Postgres mantém apenas referências para esses ficheiros. Assim, uma restauração apenas da base de dados deixa as conversas com anexos danificados. .env é importante porque um SECRET_KEY_BASE diferente termina a sessão de todos os utilizadores, e chaves ACTIVE_RECORD_ENCRYPTION_* diferentes tornam as colunas cifradas ilegíveis.
Como atualizo o Chatwoot sem danificar a base de dados?
Faça uma cópia de segurança, leia as notas da versão entre a sua tag e o destino, altere a tag da imagem no ficheiro compose e execute docker compose pull, docker compose down, docker compose run --rm rails bundle exec rails db:chatwoot_prepare e docker compose up -d. Faça primeiro o pull, porque as migrações têm de ser executadas a partir da nova imagem. Pare primeiro a stack, porque executar código antigo com um schema novo gera erros. Só uma instalação muito antiga precisa de passar por tags de imagem intermédias, em vez de avançar diretamente para a versão mais recente, executando o passo de preparação depois de cada uma.
Posso usar a imagem postgres padrão em vez de pgvector?
Não. O schema do Chatwoot ativa a extensão vector. Por isso, a imagem postgres padrão falha durante db:chatwoot_prepare com ERROR: extension "vector" is not available, porque o ficheiro de controlo da extensão não está presente nessa imagem. Mantenha pgvector/pgvector:pg16 do ficheiro compose upstream ou use outra imagem que inclua pgvector para a sua versão principal do Postgres.