Tutoriais de VPS
Chatwoot na VPS (2026): Docker, HTTPS, e-mail e restauração
Instale Chatwoot Community Edition no Ubuntu com Docker, PostgreSQL, Redis e Caddy. Configure chat do site, SMTP, anexos, backups seguros, restauração e atualização controlada.

Hospedar atendimento ao cliente em uma VPS exige mais do que abrir a tela de login. O widget do site, as notificações, as tarefas em segundo plano, os anexos, o HTTPS e a recuperação precisam funcionar juntos com estabilidade. O Chatwoot depende de Rails, Sidekiq, PostgreSQL e Redis; um comando antigo pode deixar imagens sem versão fixa, banco exposto ou backups que não restauram o serviço.
Este guia completo usa Ubuntu 24.04, Chatwoot Community Edition v4.17.1, Docker Compose oficial e Caddy. A proposta atende equipes pequenas e médias, com painel HTTPS, chat no site, notificações SMTP, armazenamento S3 compatível opcional, backups externos, testes de restauração e atualizações controladas.
Contexto da versão: o exemplo original de 8 de setembro de 2026 identificava a v4.17.1 como versão estável. Aqui usamos
chatwoot/chatwoot:v4.17.1-ceem vez delatest. A referência histórica não afirma qual é a versão mais recente hoje. Confira Chatwoot Releases e as tags oficiais no Docker Hub no dia da implantação; escolha uma versão estável com suporte e correções de segurança pertinentes.
O Chatwoot reúne chat do site, e-mail e mensagens sociais conectadas por integrações oficiais em uma central de atendimento. Sua finalidade se aproxima de Intercom ou Zendesk; não é um mensageiro interno para a equipe.
A hospedagem própria faz sentido quando:
- Conversas e contatos precisam permanecer na infraestrutura que você controla.
- Vários atendentes precisam de distribuição de conversas, etiquetas, notas privadas e respostas prontas.
- Chat, e-mail, webhooks ou APIs precisam chegar à mesma caixa de entrada.
- Alguém pode cuidar de Linux, Docker, entrega de e-mail, backups e atualizações de segurança.
- A cobrança SaaS por atendente supera claramente infraestrutura e operação.
Para um site pessoal ou uma equipe sem responsável por monitoramento e restauração, um serviço gerenciado costuma dar menos trabalho. A Community Edition é gratuita, mas VPS, domínio, provedor de e-mail, objetos, backups externos e tempo de manutenção têm custo.
| Opção | Necessidades atendidas | Vantagens | Custos e responsabilidades |
|---|---|---|---|
| Chatwoot próprio | Controle dos dados, vários atendentes, APIs | Infraestrutura própria, canais reunidos, personalização | VPS, e-mail, backup, atualização e incidentes |
| Intercom / Zendesk | Serviço gerenciado e suporte do fornecedor | Recursos consolidados, infraestrutura gerenciada | Cobrança por plano ou atendente e termos SaaS sobre dados |
| Plugin simples | Site pequeno, uma pessoa, apenas chat web | Instalação rápida, pouca manutenção | Canais, automação e colaboração limitados |
A Community Edition não inclui todas as funções comerciais. A comparação oficial atual exclui da CE Captain AI, chamadas de voz, marca personalizada, capacidade de agentes, funções e permissões avançadas, SSO/SAML, políticas de SLA e suporte prioritário. Confira os planos de hospedagem própria conforme suas necessidades; não coloque recursos pagos na lista de compras da edição gratuita.
Para canais internos, mensagens privadas da equipe e ChatOps, consulte o guia de Mattermost.
Os requisitos oficiais exigem pelo menos 4 GB de RAM. As referências do fornecedor associam 4 núcleos/4 GB a cerca de 10.000 conversas por dia e 8 núcleos/8 GB a aproximadamente 20.000. São referências de capacidade, não medições nem garantia para sua carga. Atendentes simultâneos, canais, anexos, webhooks e tarefas alteram o consumo; um Sidekiq ocupado pode usar sozinho mais de 1 GB.
| Carga | Configuração inicial sugerida | Armazenamento | Observações |
|---|---|---|---|
| Teste ou baixo volume | 2–4 vCPU, 4 GB RAM | 50 GB NVMe | Poucos atendentes e chat web; acompanhe a memória |
| Equipe pequena ou média em produção | 4 vCPU, 8 GB RAM | 80–160 GB NVMe | Folga para Rails, Sidekiq, PostgreSQL e arquivos |
| Alto volume ou muitos canais | 8 vCPU, 16 GB+ RAM | Planeje banco e objetos separadamente | Separe web, workers e banco; faça teste de carga |
A documentação também recomenda pelo menos 1 GB de swap para picos durante atualizações. Swap é uma reserva; troca constante pede mais RAM ou separação de serviços. Confira se já existe arquivo swap antes do exemplo e evite duplicar entradas no fstab:
sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h
O diagrama original mostra clientes HTTPS chegando ao Caddy no host, que encaminha ao Rails na porta local 3000. Rails e Sidekiq usam PostgreSQL e Redis; anexos ficam em volume Docker ou armazenamento S3 compatível:
访客网站 / 客服浏览器
│ HTTPS 443
▼
Caddy(宿主机)
│ 127.0.0.1:3000
▼
Chatwoot Rails 容器 ───── PostgreSQL
│
└──── Sidekiq ─── Redis
附件:本地 Docker volume,或 S3 兼容对象存储
Somente 22/tcp, 80/tcp e 443/tcp precisam ser públicos. O Compose fixado vincula Rails 3000, PostgreSQL 5432 e Redis 6379 a 127.0.0.1. Mantenha essas definições; mudar banco ou Redis para 0.0.0.0 não resolve problemas internos.
Escolha um subdomínio como support.example.com e aponte o registro A ao IPv4 público. Adicione AAAA somente com IPv6 funcional até o servidor; uma rota quebrada pode causar falhas intermitentes de certificado e acesso.
export CW_DOMAIN="support.example.com"
getent ahosts "$CW_DOMAIN"
curl -4 https://ifconfig.me
Atualize o Ubuntu e configure UFW:
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl openssl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
Aplique regras equivalentes no grupo de segurança do provedor. Limite SSH aos endereços administrativos quando possível e teste outra sessão antes de fechar a atual. Verifique portas publicadas pelo Docker separadamente; o firewall sozinho não comprova que os contêineres estejam privados.
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
Inclua rotação de logs, alertas de recursos e observabilidade na operação. Veja a lista de configuração de Docker Compose em produção.
Use os arquivos da tag v4.17.1 para impedir que mudanças futuras em develop alterem a implantação:
sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/chatwoot
cd /opt/chatwoot
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/.env.example -o .env
curl -fL https://raw.githubusercontent.com/chatwoot/chatwoot/v4.17.1/docker-compose.production.yaml -o docker-compose.production.yaml
sed -i 's|image: chatwoot/chatwoot:latest|image: chatwoot/chatwoot:v4.17.1-ce|' docker-compose.production.yaml
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
A imagem -ce não inclui código Enterprise. Fixar a versão torna as atualizações deliberadas, não permanentes. Revise também imagens PostgreSQL/pgvector e Redis, extensões e compatibilidade; não altere suas versões principais sem planejamento ao atualizar a aplicação.
Gere três segredos diferentes e guarde-os em um gerenciador de senhas:
openssl rand -hex 64
openssl rand -base64 36
openssl rand -base64 36
O primeiro valor é SECRET_KEY_BASE; os outros são senhas independentes de PostgreSQL e Redis. Base64 pode conter caracteres especiais em URLs. Para incluir a senha Redis na URL, codifique corretamente ou gere uma hexadecimal, por exemplo openssl rand -hex 32, usando exatamente o mesmo valor nos dois ajustes Redis.
Edite /opt/chatwoot/.env e substitua todos os domínios, senhas e remetentes de exemplo:
SECRET_KEY_BASE=replace-with-the-128-character-hex-secret
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
ENABLE_ACCOUNT_SIGNUP=true
DEFAULT_LOCALE=zh_CN
REDIS_URL=redis://:replace-with-redis-password@redis:6379
REDIS_PASSWORD=replace-with-redis-password
POSTGRES_HOST=postgres
POSTGRES_DATABASE=chatwoot
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=replace-with-postgres-password
RAILS_ENV=production
RAILS_LOG_TO_STDOUT=true
LOG_LEVEL=info
MAILER_SENDER_EMAIL=Support <[email protected]>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
[email protected]
SMTP_PASSWORD=replace-with-smtp-password
SMTP_AUTHENTICATION=login
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_OPENSSL_VERIFY_MODE=peer
ACTIVE_STORAGE_SERVICE=local
O exemplo preservado usa DEFAULT_LOCALE=zh_CN. Para uma organização em português brasileiro, use DEFAULT_LOCALE=pt_BR; ele define o idioma inicial das contas novas, sem determinar a localização dos clientes. A grafia do ajuste do Chatwoot difere do código de idioma da página.
Corrija a senha PostgreSQL antes da inicialização. O Compose oficial fixado traz POSTGRES_PASSWORD= vazio no serviço postgres. O dotenv da aplicação não substitui esse valor literal. Troque essa entrada da lista environment por:
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
Mantenha POSTGRES_DB e POSTGRES_USER compatíveis com a aplicação. Em banco já inicializado, editar uma variável não muda a senha do usuário existente; faça a alteração de senha de forma controlada no banco.
O original apresenta esta verificação:
cd /opt/chatwoot
chmod 600 .env
sudo docker compose -f docker-compose.production.yaml config >/tmp/chatwoot-compose.yaml
grep -A4 -E '127.0.0.1:3000|127.0.0.1:5432|127.0.0.1:6379' /tmp/chatwoot-compose.yaml
Evite gravar segredos expandidos em arquivo temporário acessível a outros usuários. Prefira o pipe abaixo, que imprime somente portas. Compose moderno representa portas em campos estruturados; o grep literal do original pode não retornar nada mesmo com vínculos corretos:
sudo docker compose -f /opt/chatwoot/docker-compose.production.yaml config --format json | python3 -c '
import json, sys
config = json.load(sys.stdin)
for name in ("rails", "postgres", "redis"):
for port in config["services"][name].get("ports", []):
assert port.get("host_ip") == "127.0.0.1", (name, "non-loopback binding")
print(name, port.get("host_ip"), port.get("published"), port.get("target"))
'
Mantenha o dotenv com permissão 600. Não publique a saída completa de docker compose config; ela pode incluir credenciais PostgreSQL, Redis e SMTP.
Execute a preparação oficial antes do primeiro início da aplicação:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml up -d
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=100 rails sidekiq postgres redis
Confira porta web e dependências:
curl -I http://127.0.0.1:3000
ss -lntp | grep -E ':3000|:5432|:6379'
sudo docker compose -f docker-compose.production.yaml exec -T postgres pg_isready -U postgres -d chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" ping'
PostgreSQL deve informar accepting connections, Redis PONG, e as três portas publicadas devem usar loopback. Uma resposta de saúde não testa as credenciais reais da aplicação; confira logs Rails/Sidekiq e envie uma conversa de teste.
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy
Crie /etc/caddy/Caddyfile com seu domínio:
support.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:3000
log {
output file /var/log/caddy/chatwoot-access.log {
roll_size 100MiB
roll_keep 7
}
}
}
Prepare o diretório de log com acesso de escrita para o serviço Caddy. reverse_proxy já suporta WebSocket; não precisa definir manualmente Upgrade. Valide e recarregue:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -I https://support.example.com
Para várias aplicações no mesmo host, consulte o guia de proxy reverso Caddy e HTTPS automático.
Abra inicialmente:
https://support.example.com/app/auth/signup
Restrinja o acesso ao administrador previsto durante a configuração. Depois de criar a primeira conta e a organização, altere .env para:
ENABLE_ACCOUNT_SIGNUP=false
Recrie os contêineres para aplicar o ambiente:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml up -d --force-recreate rails sidekiq
Convide os demais atendentes pela administração em vez de manter cadastro público. Habilite MFA onde houver suporte. Antes, configure as três chaves Active Record Encryption descritas em .env.example:
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:encryption:init
Guarde ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY, ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY e ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT da saída em .env e em um gerenciador protegido. Recrie Rails e Sidekiq. Preserve as chaves em implantações e restaurações; gerar outras ou perdê-las pode tornar dados cifrados ilegíveis.
Vá a Configurações → Caixas de entrada → Adicionar caixa, selecione Website e informe nome do site e domínios permitidos. Coloque o script gerado com websiteToken no layout comum ou gerenciador de tags.
Antes de publicar, valide:
- A bolha aparece em janela anônima.
- A primeira mensagem chega imediatamente ao painel do atendente.
- A resposta volta ao site sem recarregar a página.
- Um domínio de teste não autorizado não consegue abusar do widget; confirme os controles reais da versão escolhida.
- Tipos e tamanhos de anexos atendem às regras do negócio.
- As notificações por e-mail chegam com o painel fechado.
Se a bolha não aparece, examine Console, Network e WebSocket no navegador. Procure FRONTEND_URL incorreto, CSP bloqueando scripts, código antigo em cache CDN ou redirecionamento HTTPS errado antes do proxy.
SMTP participa de convites, notificações, recuperação de senha e e-mails das conversas. Envie uma mensagem de teste pelo painel e confira:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml logs -f --tail=100 rails sidekiq
Se a mensagem vai para spam, revise SPF, DKIM e DMARC do domínio remetente, sem desabilitar validação TLS. O domínio de MAILER_SENDER_EMAIL deve corresponder a uma identidade autorizada pelo provedor. Com relay, o provedor administra o DNS reverso do servidor que envia.
Para respostas de clientes continuarem na mesma conversa, configure entrada de e-mail separadamente. Use uma integração compatível de Mailgun, Postmark, SendGrid, SES ou encaminhamento, com RAILS_INBOUND_EMAIL_SERVICE, senha de entrada e webhook apropriado. Confira suporte da versão e do provedor: SMTP de saída funcionando não prova que a entrada esteja pronta.
Uma caixa unificada não contorna regras das plataformas. WhatsApp, Instagram e Facebook normalmente exigem conta Business, aplicação de desenvolvedor, webhooks, revisão e cobranças da plataforma.
Em produção:
- Solicite credenciais pela documentação oficial do Chatwoot e do canal.
- Use aplicação separada e tokens com permissões mínimas.
- Mantenha callbacks em HTTPS.
- Defina responsáveis por rotação dos tokens e revisão do canal.
- Evite contas compartilhadas duvidosas e serviços que prometem dispensar revisão.
Valide primeiro chat do site e API Inbox; depois acrescente canais externos um por vez.
ACTIVE_STORAGE_SERVICE=local grava anexos no volume Docker storage_data. É simples, mas a perda do disco leva os arquivos junto se não houver backup externo.
Quando os anexos crescerem, configure:
ACTIVE_STORAGE_SERVICE=s3_compatible
STORAGE_BUCKET_NAME=chatwoot-attachments
STORAGE_ACCESS_KEY_ID=replace-with-access-key
STORAGE_SECRET_ACCESS_KEY=replace-with-secret-key
STORAGE_REGION=auto
STORAGE_ENDPOINT=https://your-s3-compatible-endpoint
STORAGE_FORCE_PATH_STYLE=true
Provedores diferem em path-style, CORS e URLs assinadas. Teste upload, visualização, download e exclusão antes da mudança. Migre os arquivos existentes deliberadamente; alterar a variável não os transfere. Recrie aplicações ao mudar configuração. Ative versionamento, ciclo de vida e backup também no armazenamento de objetos; S3 sozinho não cumpre o objetivo de recuperação. Para solução compatível própria, veja o tutorial de MinIO.
O escopo oficial inclui PostgreSQL, anexos, variáveis e customizações de código. Redis guarda filas e cache; não é a fonte única das conversas. Banco e arquivos precisam de um ponto de recuperação coordenado, e trabalhos pendentes exigem uma política explícita.
O exemplo original de parada e cópia está preservado abaixo. Na topologia local, use a versão revisada seguinte: o original não garante reinício após falha, descoberta exata dos volumes nem um manifesto portátil de somas:
cd /opt/chatwoot
STAMP=$(date +%F-%H%M%S)
BACKUP_DIR="/var/backups/chatwoot/$STAMP"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
sudo sh -c "docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_dump -U postgres -d chatwoot -Fc > '$BACKUP_DIR/chatwoot.dump'"
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
-v "$BACKUP_DIR:/backup" rails \
tar -czf /backup/storage.tar.gz -C /app/storage .
sudo cp .env docker-compose.production.yaml "$BACKUP_DIR/"
sudo sha256sum "$BACKUP_DIR"/* | sudo tee "$BACKUP_DIR/SHA256SUMS"
sudo docker compose -f docker-compose.production.yaml start rails sidekiq
Pause produtores de mensagens ou abra manutenção e, quando possível, deixe as filas Sidekiq esvaziarem. Baixe previamente a imagem auxiliar de arquivamento. Este exemplo como root identifica os volumes realmente montados em Rails e Redis, verifica sua existência, aplica permissões privadas, salva filas Redis, registra a imagem e usa uma trap EXIT para tentar reiniciar serviços:
sudo bash <<'BACKUP'
set -Eeuo pipefail
umask 077
cd /opt/chatwoot
compose=(docker compose -f docker-compose.production.yaml)
rails_id=$("${compose[@]}" ps -q rails)
redis_id=$("${compose[@]}" ps -q redis)
test -n "$rails_id" && test -n "$redis_id"
storage_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/app/storage"}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}{{end}}' "$rails_id")
redis_volume=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{if eq .Type "volume"}}{{.Name}}{{end}}{{end}}{{end}}' "$redis_id")
test -n "$storage_volume" && test -n "$redis_volume"
docker volume inspect "$storage_volume" "$redis_volume" >/dev/null
backup_dir="/var/backups/chatwoot/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$backup_dir"
resume_apps() { "${compose[@]}" start rails sidekiq >/dev/null || true; }
trap resume_apps EXIT
"${compose[@]}" stop rails sidekiq
"${compose[@]}" exec -T postgres pg_dump -U postgres -d chatwoot -Fc > "$backup_dir/chatwoot.dump"
"${compose[@]}" exec -T redis sh -ec 'REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli SAVE'
"${compose[@]}" stop redis
resume_services() { "${compose[@]}" start redis rails sidekiq >/dev/null || true; }
trap resume_services EXIT
docker run --rm --network none -v "$storage_volume:/source:ro" -v "$backup_dir:/backup" alpine:3.22 tar -czf /backup/storage.tar.gz -C /source .
docker run --rm --network none -v "$redis_volume:/source:ro" -v "$backup_dir:/backup" alpine:3.22 tar -czf /backup/redis.tar.gz -C /source .
cp -p .env docker-compose.production.yaml "$backup_dir/"
cp -p /etc/caddy/Caddyfile "$backup_dir/Caddyfile"
docker inspect --format '{{.Config.Image}} {{.Image}}' "$rails_id" > "$backup_dir/image-reference.txt"
(cd "$backup_dir" && sha256sum chatwoot.dump storage.tar.gz redis.tar.gz .env docker-compose.production.yaml Caddyfile image-reference.txt > SHA256SUMS && sha256sum -c SHA256SUMS)
printf 'Backup directory: %s\n' "$backup_dir"
BACKUP
Ele pressupõe anexos locais, o banco indicado e ausência de outro produtor escrevendo em Redis ou anexos. Para S3, crie um ponto equivalente dos objetos; o arquivo local não é a origem principal dos anexos. Inclua código próprio, configuração adicional e montagens fora do padrão. Confira saúde após qualquer falha: a trap tenta reiniciar, mas não é teste de disponibilidade.
Criptografe a pasta completa e copie para outra região ou provedor. Outra pasta no mesmo disco não é recuperação de desastre. Defina retenção pelo RPO: por exemplo, 7 backups diários, 4 semanais e 6–12 mensais. Veja a estratégia de backup de VPS.
Use uma VPS de teste isolada, bloqueie webhooks e e-mails de saída e restaure imagem, banco, armazenamento e chaves correspondentes a .env. Verifique SHA256SUMS dentro da pasta do backup antes de restaurar.
A sequência básica original é:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
sudo docker compose -f docker-compose.production.yaml exec -T postgres dropdb -U postgres --if-exists chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T postgres createdb -U postgres chatwoot
sudo sh -c "cat /var/backups/chatwoot/RESTORE_POINT/chatwoot.dump | docker compose -f /opt/chatwoot/docker-compose.production.yaml exec -T postgres pg_restore -U postgres -d chatwoot"
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps \
-v /var/backups/chatwoot/RESTORE_POINT:/backup:ro rails \
tar -xzf /backup/storage.tar.gz -C /app/storage
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml start rails sidekiq
A exclusão do banco nesse exemplo só serve para o destino vazio e descartável do teste. Suba PostgreSQL/Redis primeiro e mantenha Rails/Sidekiq parados. Se o usuário da aplicação não consegue ler o backup ou restaurar arquivos, use um auxiliar privilegiado ligado ao volume existente do destino, previamente verificado. Não adivinhe nomes nem restaure sobre a origem de produção; ajuste proprietário conforme a imagem. Para preservar tarefas, restaure Redis em seu volume parado. Caso aceite perder a fila, documente a decisão e reconcilie entregas ausentes ou repetidas. Isole o destino antes de iniciar workers para não repetir notificações reais.
Execute a preparação com a imagem correspondente e inicie aplicações. Teste login administrativo, conversas antigas, contatos, anexos aleatórios, widget, e-mail e tarefas de forma controlada. Um arquivo exportado demonstra uma cópia; um teste de restauração demonstra capacidade de recuperar o serviço.
Leia as notas entre versão atual e destino e siga etapas intermediárias obrigatórias; não pule várias versões principais de uma vez.
O exemplo original abaixo inicia as aplicações antes de preparar o banco. A tag v4.17.2-ce é ilustrativa, sem garantir que exista ou seja apropriada:
cd /opt/chatwoot
# 1. 先执行上一节的完整备份并记录当前镜像
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
# 2. 把 Compose 中的镜像改成已经核对过的新版本,例如 v4.17.2-ce
sudo docker compose -f docker-compose.production.yaml down
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml up -d
# 3. 官方要求升级后运行数据库准备任务
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
# 4. 回读状态与日志
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
curl -I https://support.example.com
Depois de backup completo verificado e seleção da imagem real, use esta ordem:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml stop rails sidekiq
# Edit the shared base image to the reviewed target tag before pulling.
sudo docker compose -f docker-compose.production.yaml pull
sudo docker compose -f docker-compose.production.yaml up -d postgres redis
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml up -d --force-recreate rails sidekiq
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
curl -I https://support.example.com
Prepare o banco com as aplicações paradas e então recrie Rails/Sidekiq. Após migração de esquema, voltar à imagem antiga não é rollback confiável. Restaure banco e anexos anteriores com chaves e imagem correspondentes e teste primeiro em isolamento.
Monitore pelo menos:
- RAM, swap, CPU, disco e inodes do host.
- Reinícios de Rails e Sidekiq.
- Conexões, tamanho e resultados de backup PostgreSQL.
- Disponibilidade e memória Redis.
- Filas Sidekiq acumuladas e tarefas com falha.
- Certificados HTTPS, DNS e disponibilidade externa.
- Devoluções SMTP, falhas de webhook e crescimento de anexos.
Inspeção rápida:
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml ps
sudo docker stats --no-stream
df -h
df -i
free -h
sudo docker compose -f docker-compose.production.yaml logs --since=30m rails sidekiq postgres redis
Não limite alertas à página fora do ar. Com Sidekiq parado, o login pode funcionar enquanto e-mails, webhooks, importações e tarefas se acumulam.
cd /opt/chatwoot
sudo docker compose -f docker-compose.production.yaml ps
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
sudo docker inspect --format '{{.State.OOMKilled}} {{.RestartCount}}' chatwoot-rails-1
Confira SECRET_KEY_BASE, conexão de banco, senha Redis e OOM. O nome depende do projeto Compose; obtenha o real com docker compose ps antes de inspecionar.
sudo docker compose -f docker-compose.production.yaml exec -T postgres pg_isready -U postgres -d chatwoot
sudo docker compose -f docker-compose.production.yaml exec -T redis sh -lc 'redis-cli -a "$REDIS_PASSWORD" ping'
Mantenha POSTGRES_DATABASE=chatwoot alinhado com POSTGRES_DB=chatwoot e a senha de REDIS_URL igual a REDIS_PASSWORD. Aplique a correção da senha vazia anterior. Abrir 5432 ou 6379 para a Internet não repara autenticação interna.
Teste a origem sem CDN e examine WebSocket do navegador e logs Caddy/Rails. Caddy já oferece suporte; o CDN/WAF anterior precisa permitir conexões longas e evitar cache de API ou WebSocket.
sudo docker compose -f docker-compose.production.yaml logs --since=30m rails sidekiq | grep -Ei 'smtp|mail|timeout|auth|tls'
Confira porta, autenticação, remetente autorizado, TLS e restrições IP. Muitos provedores bloqueiam 25. Use 587 STARTTLS ou 465 TLS conforme a documentação do serviço de e-mail.
df -h
df -i
sudo docker compose -f docker-compose.production.yaml run --rm --no-deps rails sh -lc 'df -h /app/storage && ls -ld /app/storage'
Para local, confira disco, inodes e permissões. Para S3 compatível, endpoint, bucket, região, path-style, CORS e horário da assinatura. Um relógio incorreto pode invalidar URLs assinadas imediatamente.
Confira imagem e preparação do banco:
grep 'image: chatwoot/chatwoot' docker-compose.production.yaml
sudo docker compose -f docker-compose.production.yaml run --rm rails bundle exec rails db:chatwoot_prepare
sudo docker compose -f docker-compose.production.yaml logs --tail=200 rails sidekiq
Mantenha tráfego parado enquanto corrige migrações. Se o salto de versão não é suportado, siga o caminho oficial em vez de reiniciar repetidamente.
- A/AAAA correspondem a caminhos de rede funcionais.
- Somente 22, 80 e 443 públicos; 3000/5432/6379 em loopback.
- Imagem revisada
v4.17.1-cefixada, semlatest. -
.envcom permissão 600 e senhas padrão/vazias substituídas na aplicação e no banco. -
ENABLE_ACCOUNT_SIGNUPdesativado após o primeiro administrador. - Chaves MFA preservadas em backups protegidos.
- Widget envia e recebe em tempo real.
- SMTP, convites, notificações e redefinição de senha testados.
- Canais oficiais com plano de rotação de credenciais.
- Pontos externos de recuperação para PostgreSQL, anexos, configuração e política de filas Redis.
- Um teste de restauração isolada concluído.
- Alertas para Rails, Sidekiq, banco, Redis, disco e HTTPS.
Não é recomendada para produção. O mínimo oficial é 4 GB e ainda há Sidekiq, PostgreSQL, Redis, Docker e Caddy no host. Com 2 GB pode iniciar sob pouca carga, mas sofrer OOM em atualizações, importações ou picos de mensagens.
CE permite hospedagem própria e está anunciada atualmente a US$ 0 por atendente. Confira obrigações da licença escolhida. Nem todos os recursos avançados estão incluídos: Captain AI, voz, marca, permissões, SSO/SAML, SLA e suporte dependem dos planos atuais.
Não. PostgreSQL é o banco oficialmente suportado; adaptações não oficiais não correspondem à implantação mantida descrita aqui.
PostgreSQL guarda conversas, contatos e configurações; Redis fornece filas e cache. Perda de Redis pode eliminar tarefas pendentes ou causar novas tentativas. Persista e monitore Redis, esvazie filas antes de manutenção quando possível e defina a política de recuperação.
Em geral não: reverse_proxy já suporta. Em falhas, confira CDN/WAF, conexões do navegador, FRONTEND_URL e logs Rails.
Não. Regras da Meta sobre contas, revisão, modelos, webhooks e cobrança continuam valendo. Siga a integração oficial.
Uma instalação sustentável exige versões controladas, dependências Rails/Sidekiq/PostgreSQL/Redis claras, HTTPS e e-mail verificados, e banco e anexos restauráveis.
Para uma equipe nova pequena ou média, comece por cerca de 4 vCPU e 8 GB RAM, imagem CE fixada, Caddy HTTPS, anexos locais e backup externo. Separe PostgreSQL, workers e objetos conforme crescem carga e canais. A implantação estará pronta quando mensagens circularem, tarefas não acumularem e você tiver realizado uma restauração.