Como instalar Chatwoot no VPS com Docker

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 VPS um Chatwoot autoalojado precisa?

Em agosto de 2026, a página de requisitos do projeto indica 4 GB de RAM e 4 núcleos de CPU como mínimo, com capacidade para até 10,000 conversas por dia. Para 8 GB e 8 núcleos, indica até 20,000 conversas por dia. Também exige pelo menos 1 GB de swap e explica o motivo: evitar que a máquina fique sem memória durante uma atualização. Reserve entre 5 GB e 10 GB de disco para o Postgres, sem contar os uploads de ficheiros.

Agora, sem rodeios. Uma VPS com 2 GB inicia o Chatwoot e parece funcionar bem com dois agentes e uma caixa de entrada pouco movimentada. Falha 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ório faz a máquina ultrapassar a memória disponível antes de Rails, Postgres e Redis consumirem a respetiva parte. O segundo é a atualização, porque db:chatwoot_prepare inicia um novo processo Rails para aplicar as migrações, e o arranque do Rails nesta imagem 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 maior, o Docker deteta que o contentor terminou e restart: always inicia-o novamente. docker compose ps mostra então um contentor que regressa continuamente a Exited (137), onde 137 significa que foi terminado pelo sinal 9. Confirme com sudo dmesg -T | grep -i "killed process", que identifica o processo escolhido pelo kernel.

Se 4 GB excederem o orçamento, pode usar uma máquina com 2 GB e 2 GB de swap. Terá de aceitar tempos de resposta piores sob carga, em vez de uma falha completa do serviço. Definir um limite rígido de memória por serviço é útil em qualquer caso, para impedir que o worker derrube a base de dados. Consulte limites de memória no Docker Compose.

Os uploads de ficheiros são a parte 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 presumir 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 .env

O 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.16.2
    env_file: .env
    volumes:
      - storage_data:/app/storage

latest significa que o próximo docker compose pull lhe entrega o que tiver sido publicado nessa manhã. Isso pode ser uma versão principal com migrações que não foram documentadas para si. 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, não permite desfazer a alteração. Fixe a tag e altere-a deliberadamente. v4.16.2 era a versão atual em agosto de 2026; consulte a página de versões para saber qual é a tag que deve fixar hoje.

O serviço base é uma âncora YAML que rails e sidekiq integram, pelo que alterar a tag num único local altera-a para ambos. Enquanto estiver no ficheiro, elimine a linha version: '3' no topo. As versões modernas do Compose ignoram-na e apresentam the attribute 'version' is obsolete, it will be ignored em todos os comandos.

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=local

POSTGRES_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: true

Use 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 5

Aguarde database system is ready to accept connections. Em seguida, crie o schema.

docker compose run --rm rails bundle exec rails db:chatwoot_prepare

Isto 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 rails

Os 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 1

HTTP/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 a reposição de palavras-passe e as conversas por email falham sem SMTP

O Chatwoot sem definições de SMTP (simple mail transfer protocol) é uma central de suporte que não consegue enviar email, e isso interrompe mais do que as notificações. As reposições de palavras-passe deixam de funcionar, por isso um administrador que fique bloqueado continua sem acesso. Os convites de agentes deixam de funcionar, porque um convite é um email. Responder a um cliente numa conversa por email deixa de funcionar, por isso a conversa só funciona num sentido. Este é o passo que as pessoas ignoram e só descobrem durante a pior semana.

O mecanismo é simples. Sem definições de SMTP, o ActionMailer mantém o valor predefinido de entregar em localhost na porta 25. Não existe um servidor de email dentro do contentor Rails, por isso o job de entrega gera Errno::ECONNREFUSED: Connection refused - connect(2) for "localhost" port 25. O email é enviado por um job em segundo plano, por isso essa linha aparece no log do Sidekiq e nunca no log do Rails. Entretanto, a pessoa que clica em "esqueci-me da 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=true

Use a porta 587 com STARTTLS. A ligação começa em texto simples e é atualizada para uma ligação cifrada antes da autenticação. A maioria dos fornecedores de VPS bloqueia a porta 25 de saída para limitar o spam, por isso um relay na porta 587 costuma ser a única opção que consegue estabelecer ligação. SMTP_DOMAIN é o domínio que o seu 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 sidekiq

Inicie uma reposição de palavra-passe na página de login. Numa entrega funcional, o job do mailer termina normalmente no log do Sidekiq. Uma falha mostra a classe da exceção e, em seguida, o Sidekiq tenta novamente com um intervalo progressivamente maior. Por isso, um relay com problemas produz o mesmo erro a cada poucos minutos durante horas.

Duas rejeições são comuns, e nenhuma é um erro do Chatwoot. 535 Authentication failed significa que o nome de utilizador ou a palavra-passe estão incorretos para esse relay, e muitos fornecedores exigem uma palavra-passe de aplicação em vez da palavra-passe da conta. 550 Sender address rejected significa que MAILER_SENDER_EMAIL é um endereço com o qual o relay não permite enviar, por isso tem de ser uma caixa de correio ou um domínio que tenha verificado junto desse fornecedor.

A receção de email numa conversa é um job separado. Precisa de MAILER_INBOUND_EMAIL_DOMAIN e RAILS_INBOUND_EMAIL_SERVICE, além de um servidor de email que encaminhe as mensagens recebidas para o Chatwoot. 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, porque ACTIVE_STORAGE_SERVICE=local grava os ficheiros carregados no disco e mantém apenas uma linha de referência no PostgreSQL.
• O ficheiro .env, porque contém SECRET_KEY_BASE e as chaves ACTIVE_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.

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

Como atualizar o Chatwoot para uma nova tag

A ordem é mais importante do que os comandos.

1. Leia as notas da versão entre a sua tag e a tag de destino e procure passos manuais obrigatórios.
2. Faça um dump recente da base de dados e um arquivo do armazenamento. Confirme se os tamanhos dos dois ficheiros parecem normais.
3. Edite a tag da imagem do serviço base em docker-compose.yaml.
4. 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 images

Faça 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 esquema são incompatíveis. Um processo Rails antigo em execução pode gerar erros ou escrever linhas que o novo esquema 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 solicita 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.

Não avance várias versões de uma só vez. Para uma instalação antiga, a recomendação do upstream é passar pelas tags intermédias. As migrações são removidas depois de serem incorporadas no esquema base. Por isso, uma base de dados muito antiga pode chegar a um estado sem caminho de atualização. Avance uma versão minor de cada vez e execute o passo de preparação depois de cada atualização.

Se o Rails iniciar antes de a migração ser executada, recusa-se a atender pedidos e regista ActiveRecord::PendingMigrationError: Migrations are pending. Com restart: always definido, o contentor entra num ciclo de reinício. Nesse caso, docker compose ps mostra um uptime que é reiniciado a cada poucos segundos. Execute o passo de preparação para corrigir o problema.

Reverter significa voltar a definir a tag antiga e restaurar o dump. Não existe um caminho de migração inversa em que possa confiar. É para isso que serve o passo 2.

Modos de falha e mensagens que irá encontrar

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 à rede fica invisível para o Traefik. Nesse caso, 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 navegador. Esta diferença faz com que a página tente abrir um websocket para uma origem diferente, que o navegador 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 que já foi inicializada.

NOAUTH Authentication required. O Redis está a executar com --requirepass, mas a aplicação ligou-se sem uma palavra-passe. Por isso, REDIS_PASSWORD está em falta em .env ou não foi carregado. Teste diretamente com docker compose exec redis redis-cli -a "$REDIS_PASSWORD" ping. O comando deve devolver PONG.

Contentores que terminam com o código 137. Isso corresponde a SIGKILL. Numa máquina pequena, normalmente significa que o kernel terminou o processo por falta de memória. Adicione swap, defina limites de memória por serviço ou mude para um plano maior.

FAQ

Quanta RAM é necessária para um Chatwoot autoalojado num VPS?

Em agosto de 2026, o projeto upstream exige 4 GB de RAM e 4 cores de CPU como mínimo, com capacidade indicada para até 10,000 conversas por dia, e 8 GB com 8 cores para até 20,000. Adicione pelo menos 1 GB de swap, porque uma atualização inicia um segundo processo Rails para aplicar as migrações, e é nessa fase que os servidores pequenos ficam sem memória. Um VPS com 2 GB arranca e funciona para alguns agentes, mas o Sidekiq sozinho pode ultrapassar 1 GB sob carga. Por isso, espere que os containers sejam terminados com o código de saída 137 durante períodos de maior atividade e durante as atualizações.

Por que razão os emails de reposição de palavra-passe do Chatwoot nunca chegam?

Porque não estão configuradas definições SMTP. O ActionMailer tenta entregar a mensagem a localhost na porta 25, mas não existe um servidor de email dentro do container. O job falha no Sidekiq com Errno::ECONNREFUSED: Connection refused - connect(2) for "localhost" port 25, enquanto o navegador continua a mostrar uma mensagem de sucesso. Defina SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD e MAILER_SENDER_EMAIL em .env. Depois, reinicie os serviços rails e sidekiq e monitorize docker compose logs -f sidekiq enquanto inicia uma reposição de palavra-passe.

O que preciso de incluir na cópia de segurança 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. Os ficheiros carregados estão no volume, enquanto o Postgres guarda apenas referências a esses ficheiros. Por isso, um restauro apenas da base de dados deixa as conversas com anexos indisponíveis. .env é importante porque um SECRET_KEY_BASE diferente termina a sessão de todos os utilizadores. Chaves ACTIVE_RECORD_ENCRYPTION_* diferentes tornam as colunas encriptadas ilegíveis.

Como posso atualizar o Chatwoot sem danificar a base de dados?

Faça uma cópia de segurança, 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 imagem nova. Pare primeiro a stack, porque executar o código antigo contra um schema novo gera erros. Numa instalação antiga, avance uma versão minor de cada vez, porque as migrações são removidas depois de serem incorporadas no schema base.

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.